Documentation Spotlight: Pushpin Identify
Pushpin Identify *NEW
API Documentation
Pushpin Collections
API Catalog
Getting Started
More Examples
Reference
Contact us


(c) 2009 Placebase, Inc.
 The Pushpin Identify Service is a REST service that takes geographic coordinates (latitude and longitude) and resolves them to named locations on the earth. This process is also known as reverse geocoding. The Pushpin Identify Service is unique in that it can be used to resolve geographic coordinates to a variety of types of locations including countries, states, cities, zip codes, census tracts, neighborhoods and more, and to retrieve attributes about those locations such as population, total area, or demographic information.

The service documented here is for evaluation only, and therefore resolves locations from public data sources within the United States only. The commercial version of the service runs worldwide and with a variety of data sources. If you want to try the evaluation version of the service, please sign up for a free developer key at www.pushpin.com and follow the examples below. To see the evaluation service in action click on the map in the examples section.

Getting Started

The first thing you'll need is a Pushpin API key. You can sign up for one at www.pushpin.com and in a matter of seconds should receive it in your inbox. Once you've gotten a key, you'll be ready to invoke the Identify Service with URL's such as this one:

http://place.pushpin.com/boundary/js?act=ctg&x=-118.2737&y=34.0234&pti=8 &fmt=geojson&attr=label,vertices&key=A8C2B4DB310FF6A1987E1C06FCE83516

This URL calls the service looking for the zip code with the coordinates -118.2737, 34.0234 (longitude, latitude). What's returned is a GeoJSON formatted response containing the name and vertices of that zipode:
[
  {
    "vertices":
    {
      "type":"MultiPolygon",
      "coordinates":[
                      [[
                        [-118.2931,34.0168],
                        [-118.3002,34.0173],
                        [-118.3003,34.04],
                        [-118.2848,34.04],
                        [-118.2829,34.0393],
                        [-118.2837,34.038],
                        [-118.2744,34.0355],
                        [-118.2735,34.0321],
                        [-118.272,34.0344],
                        [-118.2646,34.0311],
                        [-118.2741,34.0163],
                        [-118.274,34.0131],
                        [-118.2828,34.0165],
                        [-118.2915,34.0157],
                        [-118.2931,34.0168]
                      ]],
                      [[
                        [-118.2914,34.0253],
                        [-118.289,34.022],
                        [-118.2914,34.0183],
                        [-118.2864,34.0183],
                        [-118.2853,34.0203],
                        [-118.2872,34.0212],
                        [-118.2853,34.0242],
                        [-118.2914,34.0253]
                      ]]
                    ]
    },
    "label":"90007"
  }
]
You can customize the types of locations that are returned by the service by using the appropriate Place Type ID. In the example above, the parameter pti=8 is used to specify that a zip code should be returned. Multiple Place Type ID's can be specified using a comma delimited list. There are additional ways to customize the Identify Service to your needs, see the examples and parameters described in the reference section below for more.

More Examples

Click on the map below to get a reverse geocode:

All locations

If you're interested in finding every location available at a specific point, you can use the following as an example:

http://place.pushpin.com/boundary/js?act=ctg&x=-118.2737&y=34.0234&pti=1,2,4,6,8,714,15,16,19,23,36,38 &fmt=geojson&attr=label,typeid&key=A8C2B4DB310FF6A1987E1C06FCE83516

This will return a GeoJSON array containing one object per location that contains the coordinate passed in. In this case you will see that state, county, city, census tract, school district, etc. were all found using this single URL.

Verbose attributes

More information is available than just a place's name and geometry. Here's an example that gets almost all attributes associated with a place:

http://place.pushpin.com/boundary/js?act=ctg&x=-118.2737&y=34.0234&pti=16&fmt=geojson &attr=label,id,identifier,typeid,centroid,bounds,area,pop,state,country,pcube(9608381) &key=A8C2B4DB310FF6A1987E1C06FCE83516

By adding more values to the attr parameter we've added more information to the response. We've omitted the vertices in this example to make the response easier to read. We also chose a special attribute here called a pcube which is exemplified in more detail below.

Statistics about places

To display statistics about places you can use a URL that looks like this:

http://place.pushpin.com/boundary/js?act=ctg&x=-118.2737&y=34.0234&pti=16&fmt=geojson &attr=label,id,pcube(9608381)&key=A8C2B4DB310FF6A1987E1C06FCE83516

In our example it has the effect of displaying the home ownership rate of Los Angeles in year 2000.

Reference

The Identify service takes this generic form (bracketed parameters are optional)

http://place.pushpin.com/boundary/js?act=ctg&x=longitude&y=latitude[&pti=types&fmt=format&attr=attributes&max=max-places]&key=api-key

Here is a list that describes the fields and what values they can have:

x

- longitude of the coordinate we're searching with.

y

- latitude of the coordinate we're searching with.

pti

- the place type ID(s) to include in the search. The value must be a comma-separated list of ids e.g. 4,16. The possible place ID's is defined by this list:

Place Type ID
Country 1
State 2
US County 4
US CBSA (Metro) 14
US Census Place (City) 16
USPS Zip Code 8
US Census ZCTA (Zip Code Tabulation Area) 7
US Census Tract 6
US Census Block Group 15
US School District 19
US Congressional District 23
US Neighborhoods (Urban Mapping) 36
US NOAA Divisions 38

fmt

- format of the output returned. Currently, the supported values are json which returns the output in JSON, and geojson which returns the output in strict GeoJSON http://geojson.org/geojson-spec.html (difference with JSON is the coordinates are represented as x,y instead of latitude,longitude). By default, the output returned will be an array of PPlace objects.

attr

- attributes of the place objects to return. The supported values are a comma-separated list of specific attributes to return, supported only if fmt is json or geojson. The following are the attributes that can be passed (the non special attributes all show up by default):
  • id - unique ID of place
  • identifier - identifier of place
  • label - name of place
  • typeid - place type ID
  • centroid - center point of place
  • bounds - bounding box (extent) of place
  • vertices - generalized vertices (polygon) of place
  • area - area of place in meters squared
  • pop - population of place (if available)
  • state - state that place belongs to (abbreviated if possible)
  • country - country that place belongs to
  • special value pcube can also be passed to return cubes with indicator ID(s) in the form pcube(ind1,ind2,...) which returns the indicator values for the default (most recent available) period. If you want to specify the period(s) of the indicators to retrieve, this format pcube((ind1,ind2,...),(period1,period2...)) is also supported. The output returned as an attribute in the form of a cube (contact us for more inforamtion on this).
  • special value con can also be passed to return the place containments, in the form con(attr1,attr2,...) which would return all containments and attr represents the attributes listed above. If you want to specify the place types of the containments to retrieve, this format con((attr1,attr2,...),(typeid1,typeid2,...)) is also supported, where typeid represents a place type ID, e.g. con((id,label),(2,4)). Note that the attributes for the con attribute does not currently support the pcube or the con attribute itself.

max

- maximum number of results to return. This parameter takes a number (the maximum that the system will return is 100).

key

- Pushpin API Key that is required to make requests to the system. You can get one from our home page.