Pushpin Location REST API Documentation: Beta

Home

Pushpin API Blog

Getting Started

URI Structure

Output Formats

Geographic Types Supported

Place Attributes

The Location REST API is a fast, convenient way to retrieve location and statistical information about places. This early version of the API focuses only on places that are administratively-defined within the USA (states, counties, cities, zip codes and census tracts).

The API makes a variety of information available about each of these places, inluding its geographic coordinates, its relationship to other geographies, and various statistical and physical attributes about a location including population, elevation, household income, unemployment rates, and its campaign contributions.

Getting Started

Here are some examples of how to retrieve information about a location:

http://rest.beta.pushpin.com/states/WI/
  Returns information on Wisconsin in an HTML-formatted page. HTML is the default output format.

http://rest.beta.pushpin.com/states/CA/counties/alameda.js
  Returns information on Alameda county in GeoJSON format.

http://rest.beta.pushpin.com/states/OH/cities/
  Returns a list of all the cities in Ohio.

http://rest.beta.pushpin.com/zipcodes/94010.kml
  Returns information on 94010 in KML format.

http://rest.beta.pushpin.com/states/CA/counties/alameda/tracts/451101
  Returns information on census tract 451101 in Alameda county.

http://rest.beta.pushpin.com/FL/counties/broward/i9608690,i9598273,label,vertices.js
  Retrieves the vertices, median household income, and percent subprime loan attributes for Broward County, FL.

URI Structure

URI's should be designed to alternate between geographic types (such as 'cities', 'states', or 'zipcodes') and geographic identifiers (commonly known names such as "Chicago") or their equivalent FIPS codes.

URI's that end with a geographic identifier that resolve successfully will return information about an individual geography, for example http://rest.beta.pushpin.com/IL/cities/chicago.

URI's that end with a geographic type will return a list of such types, for example a list of cities in Louisiana: http://rest.beta.pushpin.com/states/LA/cities/.

Output Formats

The API currently supports HTML, GeoJSON and KML formats.

Geographic Types Supported

Currently the API is limited to geographies in the USA. International support is on the roadmap. The following geographic types are supported:

Geographic Type	Identifier to use [aliases]	Example URI
US States	states	http://rest.beta.pushpin.com/states/MA
Counties	counties	http://rest.beta.pushpin.com/states/CA/counties/orange
Cities	cities [places]	http://rest.beta.pushpin.com/states/TX/cities/plano
Zip codes	zipcodes [zips]	http://rest.beta.pushpin.com/zipcodes/10011
Census tracts	censustracts [tracts]	http://rest.beta.pushpin.com/states/CA/counties/alameda/tracts/451101

Place Attributes (retreiving data)

Any of the following attributes may be retrieved for a location by adding the ?attr= parameter. For example, The following attributes are supported by the API. Currently only the JSON output format supports all attributes, support will be added to other formats soon.

The commercial version of this API makes over 10,000 variables available, including current year data.

Parameter	Description
label	Name of a place
centroid	Centroid point of place
bounds	Bounding box of a place
vertices	Generalized vertices (polygon) of place
area	Area of place in meters squared
pop	Population of a place
state	State that a place falls within
i9608653	PolicyMap's Percent of all mortgage loans that were subprime in 2006. (may not be available for all geography types).
i9607064	PolicyMap's Percent of all campaign contribution transactions that were to Hillary Clinton as of March 2008. (may not be available for all geography types).
i9607066	PolicyMap's Percent of all campaign contribution transactions that were to Barak Obama as of March 2008. (may not be available for all geography types).
i9607067	PolicyMap's Percent of all campaign contribution transactions that were to John McCain as of March 2008. (may not be available for all geography types).
i9608381	Homeownership rate in a place in 2000 (may not be available for all geography types).
i9608255	Percentage of households that are married with Children in 2000 (may not be available for all geography types).
i9608288	Median year homes were built in a place in 2000 (may not be available for all geography types).
i9608690	Median household income in 2000 (may not be available for all geography types).
i9608352	Median year homes were built in a place in 2000 (may not be available for all geography types).
i9608288	Percent foreign born population in 2000 (may not be available for all geography types).
i9608453	Percent of population with a high school degree in 2000 (may not be available for all geography types).
i9608693	Percent of population with a bachelor's degree in 2000 (may not be available for all geography types).
i9608496	Percent unemployed in 2000 (may not be available for all geography types).
i9608653	Total population in 2000 (may not be available for all geography types).
i9610104	Average annual rainfall (may not be available for all geography types).
i9607663	Average January temperature (may not be available for all geography types).
i9607661	Average July temperature (may not be available for all geography types).

This service and the documentation is in beta. We would love to have your feedback on it!