Skip to main content

Datasets API

Additional Developer Resources

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.

Required access token scopes

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 the access token page in your Developer Console.

The dataset object​

The dataset object contains information pertinent to a specific dataset. Each dataset object contains the following properties:

PropertyTypeDescription
ownerstringThe username of the dataset owner.
idstringThe ID for an existing dataset.
createdstringA timestamp indicating when the dataset was created.
modifiedstringA timestamp indicating when the dataset was last modified.
boundsarrayThe extent of features in the dataset in the format [west, south, east, north].
featuresintegerThe number of features in the dataset.
sizeintegerThe size of the dataset in bytes.
namestringOptional. The name of the dataset.
descriptionstringOptional. 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​

get
https://api.mapbox.com/datasets/v1/{username}
datasets:list
token scope

List all the datasets that belong to a particular account. This endpoint supports pagination.

Required parameterTypeDescription
usernamestringThe username of the account for which to list datasets.

You can further refine the results from this endpoint with the following optional parameters:

Optional parametersTypeDescription
limitintegerThe maximum number of datasets to return.
sortbystringSort the results by modified or created dates. modified sorts by the most recently updated dataset, while created sorts by the oldest dataset first.
startstringThe 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​

post
https://api.mapbox.com/datasets/v1/{username}
datasets:write
token scope

Create a new, empty dataset.

Required parameterTypeDescription
usernamestringThe 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​

get
https://api.mapbox.com/datasets/v1/{username}/{dataset_id}
datasets:read
token scope

Retrieve information about a single existing dataset.

Required parametersTypeDescription
usernamestringThe username of the account to which the dataset belongs.
dataset_idstringThe 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​

patch
https://api.mapbox.com/datasets/v1/{username}/{dataset_id}
datasets:write
token scope

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 parametersTypeDescription
usernamestringThe username of the account to which the dataset belongs.
dataset_idstringThe 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
https://api.mapbox.com/datasets/v1/{username}/{dataset_id}
datasets:write
token scope

Delete a specific dataset. All the features contained in the dataset will be deleted too.

Required parametersTypeDescription
usernamestringThe username of the account to which the dataset belongs.
dataset_idstringThe 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​

get
https://api.mapbox.com/datasets/v1/{username}/{dataset_id}/features
datasets:read
token scope

List all the features in a dataset.

This endpoint supports pagination so that you can list many features.

Required parametersTypeDescription
usernamestringThe username of the account to which the dataset belongs.
dataset_idstringThe ID of the dataset for which to retrieve features.

You can further refine the results from this endpoint with the following optional parameters:

Optional parametersTypeDescription
limitintegerThe maximum number of features to return, from 1 to 1000. The default is 1000.
startstringThe 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​

put
https://api.mapbox.com/datasets/v1/{username}/{dataset_id}/features/{feature_id}
datasets:write
token scope

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 parametersTypeDescription
usernamestringThe username of the account to which the dataset belongs.
dataset_idstringThe ID of the dataset for which to insert or update features.
feature_idstringThe 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​

get
https://api.mapbox.com/datasets/v1/{username}/{dataset_id}/features/{feature_id}
datasets:read
token scope

Retrieve a specific feature from a dataset.

Required parametersTypeDescription
usernamestringThe username of the account to which the dataset belongs.
dataset_idstringThe ID of the dataset from which to retrieve a feature.
feature_idstringThe 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.

Example response: Retrieve 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: Retrieve 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.

Delete a feature​

delete
https://api.mapbox.com/datasets/v1/{username}/{dataset_id}/features/{feature_id}
datasets:write
token scope

Remove a specific feature from a dataset.

Required parametersTypeDescription
usernamestringThe username of the account to which the dataset belongs.
dataset_idstringThe ID of the dataset from which to delete a feature.
feature_idstringThe ID of the feature to be deleted.

Example request: Delete a feature​

$curl -X DELETE "https://api.mapbox.com/datasets/v1/YOUR_MAPBOX_USERNAME/{dataset_id}/features/{feature_id}?access_token=YOUR_SECRET_MAPBOX_ACCESS_TOKEN"

Response: Delete a feature​

HTTP 204 No Content

Supported libraries: Delete 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.

Datasets API errors​

Response body messageHTTP status codeDescription
Unauthorized401Check the access token you used in the query.
No such user404Check the username you used in the query.
Not found404The access token used in the query needs the datasets:list scope.
Invalid start key422Check the start key used in the query.
No dataset422Check the dataset ID used in the query (or, if you are retrieving a feature, check the feature ID).

Datasets API restrictions and limits​

  • The Datasets API is limited on a per dataset basis.
  • The default read rate limit is 480 reads per minute. If you require a higher rate limit,contact us.
  • The default write rate limit is 40 writes per minute. If you require a higher rate limit,contact us.
  • If you exceed the rate limit, you will receive an HTTP 429 Too Many Requests response. For information on rate limit headers, see the Rate limit headers section.
  • Dataset names are limited to 60 characters, and dataset descriptions are limited to 300 characters.
  • Each feature cannot exceed 1023 KB compressed. Features are compressed server-side using geobuf.
  • Responses from the Datasets API set both the device and CDN TTLs to 5 minutes.
  • For general information on caching, see the Maps APIs caching troubleshooting guide.
Additional Developer Resources
Was this page helpful?