Places

Warning

This client has been deprecated

The Places API provides a convenient method for delivering political boundaries to your Descartes Labs development environment. We use the Who’s on First API as our places provider. There are two ways to work with Places outlined below.

Accessing Geometries

Find Returns a list of all matching places. Each element in the list represents a distinct political boundary, and has the attribute slug. A slug identifier is a valid value to pass to other Descartes Labs APIs, including Metadata Search as the key shape. This return does not include the geometry, but can be passed to the Metadata Shape method (described next) to access coordinate information.

This example searches for New Mexico, grabs the first element in the return, and prints its identifier.

>>> from descarteslabs.client.services.places import Places
>>> places_client = Places()
>>> new_mexico = places_client.find(
...     'north-america_united-states_new-mexico'
... )
...
>>> new_mexico_shape = new_mexico[0]['slug']
north-america_united-states_new-mexico

Shape Returns a single matching GeoJSON with defined coordinates given a slug identifier. The output can be passed to the Metadata API Search method as the key geom.

Here is an example accessing the GeoJSON for New Mexico’s boundary.

>>> from descarteslabs.client.services.places import Places
>>> from pprint import pprint
>>> places_client = Places()
>>> new_mexico_geojson = places_client.shape(
...     'north-america_united-states_new-mexico'
... )
...
>>> pprint(new_mexico_geojson)
{
 u'bbox': [-109.050039, 31.332244, -103.002199, 37.000141],
 u'geometry': {
   u'coordinates': [
     [
       [-109.046156, 34.579291],
       [-109.045223, 36.999084],
       [-106.877293, 37.000141],
       [-106.869798, 36.992424],
       ...
     ]
   ],
   u'type': u'Polygon'
 },
 u'id': 85688493,
 u'properties': {
   u'name': u'New Mexico',
   u'parent_id': 85633793,
   u'path': u'continent:north-america_country:united-states_region:new-mexico',
   u'placetype': u'region',
   u'slug': u'north-america_united-states_new-mexico'
 },
 u'type': u'Feature'
}

Slugs

Slug identifiers uniquely identify a place on Earth, and reflect its placetype hierarchy. The slug is formatted with all lowercase letters, an underscore (“_”) separating administrative levels, and a hyphen (“-”) in lieu of spaces. Because parts of the slug may be specific to administrative units, it’s typical that you will want to search for a slug using the find method. For example, you can find the slug for Santa Fe, New Mexico using places_client.find("new-mexico_santa-fe"), and see that the full slug identifier is north-america_united-states_new-mexico_northwest_santa-fe.