Datasets API
The Mapbox Datasets API supports reading, creating, updating, and removing features from a dataset.
Using the Datasets API involves interacting with two types of objects: datasets and features. Datasets contain one or more collections of GeoJSON features. When you edit a dataset object, you change the name
and description
properties of the dataset itself. When you edit a feature object, you edit the contents of the dataset, such as the coordinates or properties of a feature.
To serve your geographic data at scale, you can convert your dataset into a tileset using the Uploads API.
Using the Datasets API requires an access token with the appropriate dataset
scopes
(datasets:list
, datasets:write
, and datasets:read
). Each endpoint below
specifies the required scope. You can create a new access token with these
scopes on your account page.
The dataset object
The dataset object contains information pertinent to a specific dataset. Each dataset object contains the following properties:
Property | Type | Description |
---|---|---|
owner | string | The username of the dataset owner. |
id | string | The ID for an existing dataset. |
created | string | A timestamp indicating when the dataset was created. |
modified | string | A timestamp indicating when the dataset was last modified. |
bounds | array | The extent of features in the dataset in the format [west , south , east , north ]. |
features | integer | The number of features in the dataset. |
size | integer | The size of the dataset in bytes. |
name | string | Optional. The name of the dataset. |
description | string | Optional. A description of the dataset. |
Example dataset object
{
"owner": "{username}",
"id": "{dataset_id}",
"created": "{timestamp}",
"modified": "{timestamp}",
"bounds": [-10, -10, 10, 10],
"features": 100,
"size": 409600,
"name": "{name}",
"description": "{description}"
}
List datasets
List all the datasets that belong to a particular account. This endpoint supports pagination.
Required parameter | Type | Description |
---|---|---|
username | string | The username of the account for which to list datasets. |
You can further refine the results from this endpoint with the following optional parameters:
Optional parameters | Type | Description |
---|---|---|
limit | integer | The maximum number of datasets to return. |
sortby | string | Sort the results by modified or created dates. modified sorts by the most recently updated dataset, while created sorts by the oldest dataset first. |
start | string | The ID of the dataset after which to start the listing. Find the dataset ID in the Link header of a response. See the pagination section for details. |
Example request: List datasets
$ curl "https://api.mapbox.com/datasets/v1/YOUR_MAPBOX_USERNAME?access_token=YOUR_SECRET_MAPBOX_ACCESS_TOKEN"
Response: List datasets
The response to a request to this endpoint is a list of datasets.
Example response: List datasets
[
{
"owner": "{username}",
"id": "{dataset_id}",
"created": "{timestamp}",
"modified": "{timestamp}",
"bounds": [-10, -10, 10, 10],
"features": 100,
"size": 409600,
"name": "{name}",
"description": "{description}"
},
{
"owner": "{username}",
"id": "{dataset_id}",
"created": "{timestamp}",
"modified": "{timestamp}",
"bounds": [-10, -10, 10, 10],
"features": 100,
"size": 409600,
"name": "{name}",
"description": "{description}"
}
]
Supported libraries: List datasets
Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application. The following SDKs support this endpoint:
See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.
Create a dataset
Create a new, empty dataset.
Required parameter | Type | Description |
---|---|---|
username | string | The username of the account to which the new dataset belongs. |
Example request: Create a dataset
$ curl -X POST "https://api.mapbox.com/datasets/v1/YOUR_MAPBOX_USERNAME?access_token=YOUR_SECRET_MAPBOX_ACCESS_TOKEN" \
-d @request.json \
--header "Content-Type:application/json
Example request body: Create a dataset
{
"name": "foo",
"description": "bar"
}
Response: Create a dataset
The response to a successful request to this endpoint will be a new, empty dataset.
Example response: Create a dataset
{
"owner": "{username}",
"id": "{dataset_id}",
"created": "{timestamp}",
"modified": "{timestamp}",
"bounds": [-10, -10, 10, 10],
"features": 100,
"size": 409600,
"name": "foo",
"description": "bar"
}
Supported libraries: Create a dataset
Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application. The following SDKs support this endpoint:
See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.
Retrieve a dataset
Retrieve information about a single existing dataset.
Required parameters | Type | Description |
---|---|---|
username | string | The username of the account to which the dataset belongs. |
dataset_id | string | The ID of the dataset to be retrieved. |
Example request: Retrieve a dataset
$ curl "https://api.mapbox.com/datasets/v1/YOUR_MAPBOX_USERNAME/{dataset_id}?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
Response: Retrieve a dataset
The response to a successful request to this endpoint will be the requested dataset.
Example response: Retrieve a dataset
{
"owner": "{username}",
"id": "{dataset_id}",
"created": "{timestamp}",
"modified": "{timestamp}",
"bounds": [-10, -10, 10, 10],
"features": 100,
"size": 409600,
"name": "{name}",
"description": "{description}"
}
Supported libraries: Retrieve a dataset
Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application. The following SDKs support this endpoint:
See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.
Update a dataset
Update the properties of a specific dataset. The request body must be valid JSON. This endpoint is used to change the name
and description
of the dataset object. To add features to a dataset or edit existing dataset features, use the Insert or update a feature endpoint.
Required parameters | Type | Description |
---|---|---|
username | string | The username of the account to which the dataset belongs. |
dataset_id | string | The ID of the dataset to be updated. |
Example request: Update a dataset
$ curl -X PATCH "https://api.mapbox.com/datasets/v1/YOUR_MAPBOX_USERNAME/{dataset_id}?access_token=YOUR_SECRET_MAPBOX_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d @data.json
Example request body: Update a dataset
{
"name": "foo",
"description": "bar"
}
Response: Update a dataset
The response to a successful request to this endpoint will be the updated dataset.
Example response: Update a dataset
{
"owner": "{username}",
"id": "{dataset_id}",
"created": "{timestamp}",
"modified": "{timestamp}",
"bounds": [-10, -10, 10, 10],
"features": 100,
"size": 409600,
"name": "foo",
"description": "bar"
}
Supported libraries: Update a dataset
Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application. The following SDKs support this endpoint:
See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.
Delete a dataset
Delete a specific dataset. All the features contained in the dataset will be deleted too.
Required parameters | Type | Description |
---|---|---|
username | string | The username of the account to which the dataset belongs. |
dataset_id | string | The ID of the dataset to be deleted. |
Example request: Delete a dataset
$ curl -X DELETE "https://api.mapbox.com/datasets/v1/YOUR_MAPBOX_USERNAME/{dataset_id}?access_token=YOUR_SECRET_MAPBOX_ACCESS_TOKEN"
Response: Delete a dataset
HTTP 204 No Content
Supported libraries: Delete a dataset
Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application. The following SDKs support this endpoint:
See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.
The feature object
A feature is a GeoJSON Feature object representing a feature in the dataset. GeometryCollections and null geometries are not supported. For a full list of GeoJSON Feature properties, see the GeoJSON specification.
Example feature object
{
"id": "{feature_id}",
"type": "Feature",
"properties": {
"prop0": "value0"
},
"geometry": {
"coordinates": [102, 0.5],
"type": "Point"
}
}
List features
List all the features in a dataset.
This endpoint supports pagination so that you can list many features.
Required parameters | Type | Description |
---|---|---|
username | string | The username of the account to which the dataset belongs. |
dataset_id | string | The ID of the dataset for which to retrieve features. |
You can further refine the results from this endpoint with the following optional parameters:
Optional parameters | Type | Description |
---|---|---|
limit | integer | The maximum number of features to return, from 1 to 1000 . The default is 1000 . |
start | string | The ID of the feature after which to start the listing. Find the feature ID in the Link header of a response. See the pagination section for details. |
Example request: List features
$ curl "https://api.mapbox.com/datasets/v1/YOUR_MAPBOX_USERNAME/{dataset_id}/features?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
# Limit results to 50 features
$ curl "https://api.mapbox.com/datasets/v1/YOUR_MAPBOX_USERNAME/{dataset_id}/features?limit=50&access_token=YOUR_MAPBOX_ACCESS_TOKEN"
# Use pagination to start the listing after the feature with ID f6d9
$ curl "https://api.mapbox.com/datasets/v1/YOUR_MAPBOX_USERNAME/{dataset_id}/features?start=f6d9&access_token=YOUR_MAPBOX_ACCESS_TOKEN"
Response: List features
The response body will be a GeoJSON FeatureCollection.
Example response: List features
{
"type": "FeatureCollection",
"features": [
{
"id": "{feature_id}",
"type": "Feature",
"properties": {
"prop0": "value0"
},
"geometry": {
"coordinates": [102, 0.5],
"type": "Point"
}
},
{
"id": "{feature_id}",
"type": "Feature",
"properties": {
"prop0": "value0"
},
"geometry": {
"coordinates": [
[102, 0],
[103, 1],
[104, 0],
[105, 1]
],
"type": "LineString"
}
}
]
}
Supported libraries: List features
Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application. The following SDKs support this endpoint:
See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.
Insert or update a feature
Insert or update a feature in a specified dataset:
- Insert: If a feature with the given
feature_id
does not already exist, a new feature will be created. - Update: If a feature with the given
feature_id
already exists, it will be replaced.
If you are inserting a feature into a dataset, you must add the feature as the body of the PUT
request. This should be one individual GeoJSON feature, not a GeoJSON FeatureCollection. If the GeoJSON feature has a top-level id
property, it must match the feature_id
you use in the URL endpoint.
Required parameters | Type | Description |
---|---|---|
username | string | The username of the account to which the dataset belongs. |
dataset_id | string | The ID of the dataset for which to insert or update features. |
feature_id | string | The ID of the feature to be inserted or updated. |
Example request: Insert or update a feature
$ curl "https://api.mapbox.com/datasets/v1/YOUR_MAPBOX_USERNAME/{dataset_id}/features/{feature_id}?access_token=YOUR_SECRET_MAPBOX_ACCESS_TOKEN" \
-X PUT \
-H "Content-Type: application/json" \
-d @file.geojson
Example request body: Insert or update a feature
{
"id": "{feature_id}",
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[100, 0],
[101, 0],
[101, 1],
[100, 1],
[100, 0]
]
]
},
"properties": {
"prop0": "value0"
}
}
Response: Insert or update a feature
The response to a successful request to this endpoint will be the new or updated feature object.
Example response: Insert or update a feature
{
"id": "{feature_id}",
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[100, 0],
[101, 0],
[101, 1],
[100, 1],
[100, 0]
]
]
},
"properties": {
"prop0": "value0"
}
}
Supported libraries: Insert or update a feature
Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application. The following SDKs support this endpoint:
See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.
Retrieve a feature
Retrieve a specific feature from a dataset.
Required parameters | Type | Description |
---|---|---|
username | string | The username of the account to which the dataset belongs. |
dataset_id | string | The ID of the dataset from which to retrieve a feature. |
feature_id | string | The ID of the feature to be retrieved. |
Example request: Retrieve a feature
$ curl "https://api.mapbox.com/datasets/v1/YOUR_MAPBOX_USERNAME/{dataset_id}/features/{feature_id}?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
Response: Retrieve a feature
The response to a successful request to this endpoint is the requested feature object.