Datasets

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.

The dataset object

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

PropertyDescription
ownerThe username of the dataset owner.
idThe ID for an existing dataset.
createdA timestamp indicating when the dataset was created.
modifiedA timestamp indicating when the dataset was last modified.
boundsThe extent of features in the dataset in the format [west, south, east, north].
featuresThe number of features in the dataset.
sizeThe size of the dataset in bytes.
name
(optional)
The name of the dataset.
description
(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

get
/datasets/v1/{username}
datasets:list

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

Required parameterDescription
usernameThe username of the account for which to list datasets.

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

Optional parametersDescription
limitThe maximum number of datasets to return.
sortbySort the results by modified or created dates. modified sorts by the most recently updated dataset, while created sorts by the oldest dataset first.
startThe ID of the dataset after which to start the listing. The dataset ID is found in the Link header of a response. See the pagination section for details.

Example request: List datasets

$ curl "https://api.mapbox.com/datasets/v1/{username}?access_token=
YOUR MAPBOX ACCESS TOKEN
"
Endpoint support

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.

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}"
  }
]

Create a dataset

post
/datasets/v1/{username}
datasets:write

Create a new, empty dataset.

Required parameterDescription
usernameThe username of the account to which the new dataset belongs.

Example request: Create a dataset

$ curl -X POST "https://api.mapbox.com/datasets/v1/{username}?access_token=
YOUR MAPBOX ACCESS TOKEN
"
\ -d @request.json \ --header "Content-Type:application/json

Example request body: Create a dataset

{
  "name": "foo",
  "description": "bar"
}
Endpoint support

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.

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"
}

Retrieve a dataset

get
/datasets/v1/{username}/{dataset_id}
datasets:read

Retrieve information about a single existing dataset.

Required parametersDescription
usernameThe username of the account to which the dataset belongs.
dataset_idThe ID of the dataset to be retrieved.

Example request: Retrieve a dataset

$ curl "https://api.mapbox.com/datasets/v1/{username}/{dataset_id}?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
Endpoint support

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.

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}"
}

Update a dataset

patch
/datasets/v1/{username}/{dataset_id}
datasets:write

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 parametersDescription
usernameThe username of the account to which the dataset belongs.
dataset_idThe ID of the dataset to be updated.

Example request: Update a dataset

$ curl -X PATCH "https://api.mapbox.com/datasets/v1/{username}/{dataset_id}?access_token=
YOUR MAPBOX ACCESS TOKEN
"
\ -H "Content-Type: application/json" \ -d @data.json

Example request body: Update a dataset

{
  "name": "foo",
  "description": "bar"
}
Endpoint support

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.

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"
}

Delete a dataset

delete
/datasets/v1/{username}/{dataset_id}
datasets:write

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

Required parametersDescription
usernameThe username of the account to which the dataset belongs.
dataset_idThe ID of the dataset to be deleted.

Example request: Delete a dataset

$ curl -X DELETE "https://api.mapbox.com/datasets/v1/{username}/{dataset_id}?access_token=
YOUR MAPBOX ACCESS TOKEN
"
Endpoint support

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.

Response: Delete a dataset

HTTP 204 No Content

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
/datasets/v1/{username}/{dataset_id}/features
datasets:read

List all the features in a dataset.

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

Required parametersDescription
usernameThe username of the account to which the dataset belongs.
dataset_idThe ID of the dataset for which to retrieve features.

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

Optional parametersDescription
limitThe maximum number of features to return, from 1 to 100. The default is 10.
startThe ID of the feature after which to start the listing. The feature ID is found in the Link header of a response. See the pagination section for details.

Example request: List features

$ curl "https://api.mapbox.com/datasets/v1/{username}/{dataset_id}/features?access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Limit results to 50 features

$ curl "https://api.mapbox.com/datasets/v1/{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/{username}/{dataset_id}/features?start=f6d9&access_token=YOUR_MAPBOX_ACCESS_TOKEN"
Endpoint support

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.

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"
      }
    }
  ]
}

Insert or update a feature

put
/datasets/v1/{username}/{dataset_id}/features/{feature_id}
datasets:write

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 parametersDescription
usernameThe username of the account to which the dataset belongs.
dataset_idThe ID of the dataset for which to insert or update features.
feature_idThe ID of the feature to be inserted or updated.

Example request: Insert or update a feature

$ curl "https://api.mapbox.com/datasets/v1/{username}/{dataset_id}/features/{feature_id}?access_token=
YOUR 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"
  }
}
Endpoint support

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.

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"
  }
}

Retrieve a feature

get
/datasets/v1/{username}/{dataset_id}/features/{feature_id}
datasets:read

Retrieve a specific feature from a dataset.

Required parametersDescription
usernameThe username of the account to which the dataset belongs.
dataset_idThe ID of the dataset from which to retrieve a feature.
feature_idThe ID of the feature to be retrieved.

Example request: Retrieve a feature

$ curl "https://api.mapbox.com/datasets/v1/{username}/{dataset_id}/features/{feature_id}?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
Endpoint support

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.

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"
  }
}

Delete a feature

delete
/datasets/v1/{username}/{dataset_id}/features/{feature_id}
datasets:write

Remove a specific feature from a dataset.

Required parametersDescription
usernameThe username of the account to which the dataset belongs.
dataset_idThe ID of the dataset from which to delete a feature.
feature_idThe ID of the feature to be deleted.

Example request: Delete a feature

$ curl -X DELETE "https://api.mapbox.com/datasets/v1/{username}/{dataset_id}/features/{feature_id}?access_token=
YOUR MAPBOX ACCESS TOKEN
"
Endpoint support

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.

Response: Delete a feature

HTTP 204 No Content

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 Dataset 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.