Places

class Places(url=None, auth=None, maxsize=10, ttl=600, retries=None)

Parameters:

• url (str) – A HTTP URL pointing to a version of the storage service (defaults to current version)
• auth (Auth) – A custom user authentication (defaults to the user authenticated locally by token information on disk or by environment variables)
• maxsize (int) – Maximum size of the internal cache
• ttl (int) – Maximum lifetime of entries in the internal cache in seconds
• retries (urllib3.util.retry.Retry) – A custom retry configuration used for all API requests (defaults to a reasonable amount of retries)

categories()

Get a list of categories

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

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)

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()

Get a list of metrics

placetypes()

Get a list of place types.

return: list

List of placetypes [‘continent’, ‘country’, ‘dependency’, ‘macroregion’, ‘region’,

‘district’, ‘mesoregion’, ‘microregion’, ‘county’, ‘locality’]

prefix(*args, **kwargs)

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)

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)

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)

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()

Get a list of sources

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

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)

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