Places

class Places(url=None, auth=None, maxsize=10, ttl=600, retries=None)[source]
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()[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(path, **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(slug, output='geojson', placetype=None, geom='low')[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(slug, output='geojson', geom='low')[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