datasets.md

Datasets

The Datasets class from the mapbox.services.datasets module provides access to the Mapbox Datasets API. You can also import it directly from the mapbox module.

>>> from mapbox import Datasets

See https://www.mapbox.com/api-documentation/maps/#datasets for general documentation of the API.

Your Mapbox access token should be set in your environment; see the access tokens documentation for more information. To use the Datasets API, you must use a token created with datasets:* scopes. See https://www.mapbox.com/account/apps/.

Upload methods

The methods of the Datasets class that provide access to the Datasets API generally take dataset id and feature id arguments and return an instance of requests.Response.

Usage

Create a new dataset using the Dataset class, giving it a name and description. The id of the created dataset is in JSON data of the response.

>>> datasets = Datasets()
>>> create_resp = datasets.create(
...     name='example', description='An example dataset')
>>> new = create_resp.json()
>>> new['name']
'example'
>>> new['description']
'An example dataset'
>>> new_id = new['id']

You can find it in your account's list of datasets.

>>> listing_resp = datasets.list()
>>> [ds['id'] for ds in listing_resp.json()]
[...]

Instead of scanning the list for attributes of the dataset, you can read them directly by dataset id.

>>> attrs = datasets.read_dataset(new_id).json()
>>> attrs['id'] == new_id
True
>>> attrs['name']
'example'
>>> attrs['description']
'An example dataset'

If you want to change a dataset's name or description, you can.

>>> attrs = datasets.update_dataset(
...     new_id, name='updated example', description='An updated example dataset'
...     ).json()
>>> # attrs = datasets.read_dataset(new_id).json()
>>> attrs['id'] == new_id
True
>>> attrs['name']
'updated example'
>>> attrs['description']
'An updated example dataset'

You can delete the dataset and it will no longer be present in your listing.

>>> resp = datasets.delete_dataset(new_id)
>>> resp.status_code
204
>>> listing_resp = datasets.list()
>>> [ds['id'] for ds in listing_resp.json()]
[...]

Dataset features

The main point of a dataset is store a collection of GeoJSON features. Let us create a new dataset and then add a GeoJSON feature to it.

>>> resp = datasets.create(
...     name='features-example', description='An example dataset with features')
>>> new_id = resp.json()['id']
>>> feature = {
...     'type': 'Feature', 'id': '1', 'properties': {'name': 'Insula Nulla'},
...     'geometry': {'type': 'Point', 'coordinates': [0, 0]}}
>>> resp = datasets.update_feature(new_id, '1', feature)
>>> resp.status_code
200

In the feature collection of the dataset you will see this feature.

>>> collection = datasets.list_features(new_id).json()
>>> len(collection['features'])
1
>>> first = collection['features'][0]
>>> first['id']
'1'
>>> first['properties']['name']
'Insula Nulla'

Individual feature access

You can also read, update, and delete features individually.

Read

The read_feature() method has the semantics of HTTP GET.

>>> resp = datasets.read_feature(new_id, '1')
>>> resp.status_code
200
>>> feature = resp.json()
>>> feature['id']
'1'
>>> feature['properties']['name']
'Insula Nulla'

Update

The update_feature() method has the semantics of HTTP PUT. If there is no feature in the dataset with the given id, a new feature will be created.

>>> update = {
...     'type': 'Feature', 'id': '1', 'properties': {'name': 'Insula Nulla C'},
...     'geometry': {'type': 'Point', 'coordinates': [0, 0]}}
>>> update = datasets.update_feature(new_id, '1', update).json()
>>> update['id']
'1'
>>> update['properties']['name']
'Insula Nulla C'

Delete

The delete_feature() method has the semantics of HTTP DELETE.

>>> resp = datasets.delete_feature(new_id, '1')
>>> resp.status_code
204

Finally, let's clean up the features example dataset.

>>> resp = datasets.delete_dataset(new_id)
>>> resp.status_code
204
>>> listing_resp = datasets.list()
>>> [ds['id'] for ds in listing_resp.json()]
[...]