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, 30)¶: Places and statistics service