Places

class Places(url=None, auth=None, maxsize=10, ttl=600)[source]
categories()[source]

Get a list of categories

data(slug, source=None, category=None, metric=None, units=None, date=None, placetype='county')[source]

Get all values for a prefix search and point in time

Parameters:
  • slug (str) – Slug identifier (or shape id).
  • source (str) – Source
  • category (str) – Category
  • metric (str) – Metric
  • units (str) – Units
  • date (str) – Date
  • placetype (str) – Restrict results to a particular place type.
find(*args, **kwargs)[source]

Find candidate slugs based on full or partial path.

Parameters:
  • path (str) – Candidate underscore-separated slug.
  • placetype – Optional place type for filtering.

Example:

>>> from descarteslabs.client.services import Places
>>> results = Places().find('morocco')
>>> _ = results[0].pop('bbox')
>>> results
[
  {
    'id': 85632693,
    'name': 'Morocco',
    'path': 'continent:africa_country:morocco',
    'placetype': 'country',
    'slug': 'africa_morocco'
  }
]
metrics()[source]

Get a list of metrics

placetypes()[source]

Get a list of place types.

return: list
List of placetypes [‘continent’, ‘country’, ‘dependency’, ‘macroregion’, ‘region’,
‘district’, ‘mesoregion’, ‘microregion’, ‘county’, ‘locality’]
prefix(*args, **kwargs)[source]

Get all the places that start with a prefix

Parameters:
  • slug (str) – Slug identifier.
  • output (str) – Desired geometry format (GeoJSON, TopoJSON).
  • placetype (str) – Restrict results to a particular place type.
  • geom (str) – Desired resolution for the geometry (low, medium, high).
Returns:

GeoJSON or TopoJSON FeatureCollection

Example::
>>> from descarteslabs.client.services import Places
>>> il_counties = Places().prefix('north-america_united-states_illinois', placetype='county')
>>> len(il_counties['features'])
102
random(geom='low', placetype=None)[source]

Get a random location

geom: string
Resolution for the shape [low (default), medium, high]

return: geojson

search(q, limit=10, country=None, region=None, placetype=None)[source]

Search for shapes

Parameters:
  • q (str) – A query string.
  • limit (int) – Max number of matches to return
  • country (str) – Restrict search to a specific country
  • region (str) – Restrict search to a specific region
  • placetype (str) – Restrict search to a specific placetype
Returns:

list of candidates

Example::
>>> from descarteslabs.client.services import Places
>>> results = Places().search('texas')
>>> results[0]
{
  'bbox': [-106.645584, 25.837395, -93.508039, 36.50035],
  'id': 85688753,
  'name': 'Texas',
  'placetype': 'region',
  'slug': 'north-america_united-states_texas'
}
shape(*args, **kwargs)[source]

Get the geometry for a specific slug

Parameters:
  • slug – Slug identifier.
  • output (str) – Desired geometry format (GeoJSON).
  • geom (str) – Desired resolution for the geometry (low, medium, high).
Returns:

GeoJSON Feature

Example::
>>> from descarteslabs.client.services import Places
>>> kansas = Places().shape('north-america_united-states_kansas')
>>> kansas['bbox']
[-102.051744, 36.993016, -94.588658, 40.003078]
>>> kansas['geometry']['type']
'Polygon'
>>> kansas['properties']
{
  'name': 'Kansas',
  'parent_id': 85633793,
  'path': 'continent:north-america_country:united-states_region:kansas',
  'placetype': 'region',
  'slug': 'north-america_united-states_kansas'
}
sources()[source]

Get a list of sources

statistics(slug, source=None, category=None, metric=None, units=None)[source]

Get a time series for a specific place

Parameters:
  • slug (str) – Slug identifier (or shape id).
  • slug – Slug identifier (or shape id).
  • source (str) – Source
  • category (str) – Category
  • metric (str) – Metric
  • units (str) – Units
value(slug, source=None, category=None, metric=None, date=None)[source]

Get point values for a specific place

Parameters:
  • slug (str) – Slug identifier (or shape id).
  • source (list(str)) – Source(s)
  • category (list(str)) – Category(s)
  • metric (list(str)) – Metric(s)
  • date (str) – Date
TIMEOUT = (9.5, 360)

Places and statistics service