Maps service

The Mapbox Maps service is composed of the following APIs:

    Tilesets

    The Mapbox Tilesets API supports reading metadata for raster and vector tilesets. To request the tiles themselves, use the Vector Tiles API for vector tiles or the Raster Tiles API for raster tiles instead.

    List tilesets

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

    List all the tilesets that belong to a specific account. This endpoint supports pagination.

    Required parameterDescription
    usernameThe username of the account for which to list tilesets

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

    Optional parametersDescription
    typeFilter results by tileset type, either raster or vector.
    visibilityFilter results by visibility, either public or private. Private tilesets require an access token that belong to the owner. Public tilesets can be requested with any user's access token.
    sortbySort the listings by their created or modified timestamps.
    limitThe maximum number of tilesets to return, from 1 to 500. The default is 100.
    startThe tileset after which to start the listing. The key is found in the Link header of a response. See the pagination section for details.

    Example request: List tilesets

    $ curl "https://api.mapbox.com/tilesets/v1/{username}?access_token=
    YOUR_MAPBOX_ACCESS_TOKEN
    "
    # Limit the results to the 25 most recently created vector tilesets $ curl "https://api.mapbox.com/tilesets/v1/{username}?type=vector&limit=25&sortby=created&access_token=
    YOUR_MAPBOX_ACCESS_TOKEN
    "
    # Limit the results to the tilesets after the tileset with a start key of abc123 $ curl "https://api.mapbox.com/tilesets/v1/{username}?start=abc123&access_token=
    YOUR_MAPBOX_ACCESS_TOKEN
    "
    Endpoint support

    Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application. The following SDK supports this endpoint:

    See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.

    Response: List tilesets

    A request to the Tilesets API returns one or more tileset objects. Each tileset object contains the following properties:

    PropertyDescription
    typeThe kind of data contained, either raster or vector.
    centerThe longitude, latitude, and zoom level for the center of the contained data, given in the format [lon, lat, zoom].
    createdA timestamp indicating when the tileset was created.
    descriptionA human-readable description of the tileset.
    filesizeThe storage in bytes consumed by the tileset.
    idThe unique identifier for the tileset.
    modifiedA timestamp indicating when the tileset was last modified.
    nameThe name of the tileset.
    visibilityThe access control for the tileset, either public or private.
    statusThe processing status of the tileset, one of: available, pending, or invalid.

    Example response: List tilesets

    [
      {
        "type": "vector",
        "center": [-0.2680000000000007, 11.7014165, 2],
        "created": "2015-09-09T23:30:17.936Z",
        "description": "",
        "filesize": 17879790,
        "id": "mapbox.05bv6e12",
        "modified": "2015-09-09T23:30:17.906Z",
        "name": "routes.geojson",
        "visibility": "public",
        "status": "available"
      },
      {
        "type": "raster",
        "center": [-110.32479628173822, 44.56501277250615, 8],
        "created": "2016-12-10T01:29:37.682Z",
        "description": "",
        "filesize": 794079,
        "id": "mapbox.4umcnx2j",
        "modified": "2016-12-10T01:29:37.289Z",
        "name": "sample-4czm7e",
        "visibility": "private",
        "status": "available"
      }
    ]
    

    Delete tileset

    delete
    /tilesets/v1/{username.map_id}
    tilesets:write

    Delete a tileset. Note that you can only delete your own tileset.

    Required parameterDescription
    username.map_idThe ID the tileset you want to delete, which is composed of your username followed by a period and the tileset's unique identifier.

    Example request: Delete tileset

    $ curl -X DELETE "https://api.mapbox.com/tilesets/v1/{username.map_id}?access_token=
    YOUR_MAPBOX_ACCESS_TOKEN
    "

    Response: Delete tileset

    HTTP 204
    

    Retrieve TileJSON metadata

    get
    /v4/{map_id}.json

    Given a valid Mapbox tileset ID, returns TileJSON metadata for that tileset.

    Required parametersDescription
    map_idUnique identifier for the tileset in the format username.id.

    This endpoint can be further customized with the optional secure parameter:

    Optional parametersDescription
    secureBy default, resource URLs in the retrieved TileJSON (such as in the "tiles" array) will use the HTTP scheme. Include this query parameter in your request to receive HTTPS resource URLs instead.

    Example request: Retrieve TileJSON metadata

    $ curl "https://api.mapbox.com/v4/examples.civir98a801cq2oo6w6mk1aor-9msik.json?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
    
    # Request HTTPS resource URLs in the retrieved TileJSON
    $ curl "https://api.mapbox.com/v4/examples.civir98a801cq2oo6w6mk1aor-9msik.json?secure&access_token=YOUR_MAPBOX_ACCESS_TOKEN"
    

    Response: Retrieve TileJSON metadata

    Returns TileJSON metadata for a tileset. The TileJSON object describes a map's resources, like tiles, markers, and UTFGrid, as well as its name, description, and centerpoint.

    Example response: Retrieve TileJSON metadata

    {
      "bounds": [
        -87.769775,
        41.715515,
        -87.530221,
        41.940403
      ],
      "center": [
        -87.649998,
        41.82795900000001,
        0
      ],
      "created": 1479169405055,
      "filesize": 3321,
      "format": "pbf",
      "id": "examples.civir98a801cq2oo6w6mk1aor-9msik",
      "mapbox_logo": true,
      "maxzoom": 10,
      "minzoom": 0,
      "modified": 1542143499397,
      "name": "chicago-parks",
      "private": false,
      "scheme": "xyz",
      "tilejson": "2.2.0",
      "tiles": [
        "http://a.tiles.mapbox.com/v4/examples.civir98a801cq2oo6w6mk1aor-9msik/{z}/{x}/{y}.vector.pbf",
        "http://b.tiles.mapbox.com/v4/examples.civir98a801cq2oo6w6mk1aor-9msik/{z}/{x}/{y}.vector.pbf"
      ],
      "vector_layers": [{
        "description": "",
        "fields": {
          "description": "String",
          "id": "String",
          "marker-color": "String",
          "marker-size": "String",
          "marker-symbol": "String",
          "title": "String"
        },
        "id": "chicago-parks",
        "maxzoom": 22,
        "minzoom": 0,
        "source": "examples.civir98a801cq2oo6w6mk1aor-9msik",
        "source_name": "chicago-parks"
      }],
      "version": "1.0.0",
      "webpage": "http://a.tiles.mapbox.com/v4/examples.civir98a801cq2oo6w6mk1aor-9msik/page.html"
    }
    

    Tilesets API errors

    Response body messageHTTP status codeDescription
    Not Authorized - No Token401No token was used in the query.
    Not Authorized - Invalid Token401Check the access token you used in the query.
    This endpoint requires a token with {scope} scope403The access token used in the query needs the specified scope.
    No such user404Check the username you used in the query.
    Cannot find tileset404Check the tileset ID you used in the query.
    The requested url's querystring \"limit\" property contains in invalid value.422The limit specified in the query is larger than 500, or contains non-numeric characters.
    Invalid start key422Check the start key used in the query.

    Tilesets API restrictions and limits

    If you require a higher rate limit, contact us.

    Was this section on Tilesets helpful?

    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.
    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
    "
    \ -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

    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

    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.
    • The default write rate limit is 40 writes per minute.
    • 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.

    If you require a higher rate limit, contact us.

    Was this section on Datasets helpful?

    Static Images

    The Mapbox Static Images API serves standalone, static map images generated from Mapbox Studio styles. These images can be displayed on web and mobile devices without the aid of a mapping library or API. They look like an embedded map, but do not have interactivity or controls. The returned static map will be a PNG file.

    To build a Static Images API request by zooming and panning around an interactive map, use the Static Images API playground.

    Retrieve a static map from a style

    get
    /styles/v1/{username}/{style_id}/static/{overlay}/{lon},{lat},{zoom},{bearing},{pitch}|{auto}/{width}x{height}{@2x}
    styles:tiles

    The position of the map is represented by either the word auto or by five numbers: longitude, latitude, zoom, bearing, and pitch. The last two numbers, bearing and pitch, are optional. If you only specify bearing and not pitch, pitch will default to 0. If you specify neither, they will both default to 0. If you specify "auto", you should not provide any of these numbers.

    Required parametersDescription
    usernameThe username of the account to which the style belongs.
    style_idThe ID of the style from which to create a static map.
    overlayOne or more comma-separated features that can be applied on top of the map at request time. The order of features in an overlay dictates their Z-order on the page. The last item in the list will have the highest Z-order (will overlap the other features in the list), and the first item in the list will have the lowest (will underlap the other features). Format can be a mix of geojson, marker, or path. For more details on each option, see the Overlay options section.
    lonLongitude for the center point of the static map; a number between -180 and 180.
    latLatitude for the center point of the static map; a number between -90 and 90.
    zoomZoom level; a number between 0 and 20. Fractional zoom levels will be rounded to two decimal places.
    autoIf auto is added, the viewport will fit the bounds of the overlay. If used, auto replaces lon, lat, zoom, bearing, and pitch.
    widthWidth of the image; a number between 1 and 1280 pixels.
    heightHeight of the image; a number between 1 and 1280 pixels.

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

    Optional parametersDescription
    bearingBearing rotates the map around its center. A number between 0 and 360, interpreted as decimal degrees. 90 rotates the map 90° clockwise, while 180 flips the map. Defaults to 0.
    pitchPitch tilts the map, producing a perspective effect. A number between 0 and 60, measured in degrees. Defaults to 0 (looking straight down at the map).
    @2xRender the static map at a @2x scale factor for high-density displays.
    attributionA boolean value controlling whether there is attribution on the image. Defaults to true. Note: If attribution=false, the watermarked attribution is removed from the image. You still have a legal responsibility to attribute maps that use OpenStreetMap data, which includes most maps from Mapbox. If you specify attribution=false, you are legally required to include proper attribution elsewhere on the webpage or document.
    logoA boolean value controlling whether there is a Mapbox logo on the image. Defaults to true.
    before_layerA string value for controlling where the overlay is inserted in the style. All overlays will be inserted before the specified layer.

    Example request: Retrieve a static map from a style

    # Retrieve a map at -122.4241 longitude, 37.78 latitude,
    # zoom 14.24, bearing 0, and pitch 60. The map
    # will be 600 pixels wide and 600 pixels high
    $ curl "https://api.mapbox.com/styles/v1/mapbox/streets-v11/static/-122.4241,37.78,14.25,0,60/600x600?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
    
    # Retrieve a map at 0 longitude, 10 latitude, zoom 3,
    # and bearing 20. Pitch will default to 0.
    $ curl "https://api.mapbox.com/styles/v1/mapbox/streets-v11/static/0,10,3,20/600x600?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
    
    # Retrieve a map at 0 longitude, 0 latitude, zoom 2.
    # Bearing and pitch default to 0.
    $ curl "https://api.mapbox.com/styles/v1/mapbox/streets-v11/static/0,0,2/600x600?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
    
    # Retrieve a map with a custom marker overlay
    $ curl "https://api.mapbox.com/styles/v1/mapbox/streets-v11/static/url-https%3A%2F%2Fwww.mapbox.com%2Fimg%2Frocket.png(-76.9,38.9)/-76.9,38.9,15/1000x1000?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
    
    # Retrieve a map with a GeoJSON overlay
    $ curl "https://api.mapbox.com/styles/v1/mapbox/streets-v11/static/geojson(%7B%22type%22%3A%22Point%22%2C%22coordinates%22%3A%5B-73.99%2C40.7%5D%7D)/-73.99,40.70,12/500x300?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
    
    # Retrieve a map with two points and a polyline overlay,
    # with its center point automatically determined with `auto`
    $ curl "https://api.mapbox.com/styles/v1/mapbox/streets-v11/static/pin-s-a+9ed4bd(-122.46589,37.77343),pin-s-b+000(-122.42816,37.75965),path-5+f44-0.5(%7DrpeFxbnjVsFwdAvr@cHgFor@jEmAlFmEMwM_FuItCkOi@wc@bg@wBSgM)/auto/500x300?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.

    Overlay options

    GeoJSON
    geojson({geojson})
    
    ArgumentDescription
    geojsonThe {geojson} argument must be a valid GeoJSON object. simplestyle-spec styles for GeoJSON features will be respected and rendered. Note that # characters must be replaced in the URL with %23 (for example, "fill":"#FF0000" would be "fill":"%23FF0000").
    Marker
    {name}-{label}+{color}({lon},{lat})
    
    ArgumentDescription
    nameMarker shape and size. Options are pin-s and pin-l.
    label
    (optional)
    Marker symbol. Options are an alphanumeric label a through z, 0 through 99, or a valid Maki icon. If a letter is requested, it will be rendered in uppercase only.
    color
    (optional)
    A 3- or 6-digit hexadecimal color code.
    lon, latThe location at which to center the marker. When using an asymmetric marker, make sure that the tip of the pin is at the center of the image.
    Custom marker
    url-{url}({lon},{lat})
    
    ArgumentDescription
    urlA percent-encoded URL for the image. Type can be PNG or JPG.
    lon, latThe location at which to center the marker. When creating an asymmetric marker like a pin, make sure that the tip of the pin is at the center of the image.

    Custom markers are cached according to the Expires and Cache-Control headers. Set at least one of these headers to a proper value to prevent repeated requests for the custom marker image.

    Path
    path-{strokeWidth}+{strokeColor}-{strokeOpacity}+{fillColor}-{fillOpacity}({polyline})
    

    Encoded polylines with a precision of 5 decimal places can be used with the Static API via the path parameter.

    ArgumentDescription
    strokeWidth
    (optional)
    A positive number for the line stroke width
    strokeColor
    (optional)
    A 3- or 6-digit hexadecimal color code for the line stroke
    strokeOpacity
    (optional)
    A number between 0 (transparent) and 1 (opaque) for line stroke opacity
    fillColor
    (optional)
    A 3- or 6-digit hexadecimal color code for the fill
    fillOpacity
    (optional)
    A number between 0 (transparent) and 1 (opaque) for fill opacity
    polylineA valid encoded polyline encoded as a URI component

    Response: Retrieve a static map from a style

    Returns a static map from a specified style as a PNG.

    Static Images API errors

    Response body messageHTTP status codeDescription
    Not Authorized - Invalid Token401Check the access token you used in the query.
    Style not found404Check the style ID used in the query.
    Zoom level must be between 0-20.422The zoom level specified in the query is larger than 20 or contains non-numeric characters.
    Pitch must be between 0-60.422The pitch specified in the query is larger than 60 or contains non-numeric characters.
    {Width}|{Height} must be between 1-1280.422The width or the height specified in the query is larger than 1280 or contains non-numeric characters.

    Static Images API restrictions and limits

    • Use of the Static Images API endpoint is rate limited based on your user plan. The default rate limit is 600 requests per minute. If you require a higher rate limit, contact us.
    • Exceeding this limit will result in an HTTP 429 response. For information on rate limit headers, see the Rate limit headers section.
    Was this section on Static Images helpful?

    Static Tiles

    The Mapbox Static Tiles API serves raster tiles generated from Mapbox Studio styles. Raster tiles can be used in traditional web mapping libraries like Mapbox.js, Leaflet, OpenLayers, and others to create interactive slippy maps. The returned raster tile will be a JPEG, and will be 512 pixels by 512 pixels by default.

    Retrieve raster tiles from styles

    get
    /styles/v1/{username}/{style_id}/tiles/{tilesize}/{z}/{x}/{y}{@2x}

    Retrieve 512x512 pixel or 256x256 pixel raster tiles from a Mapbox Studio style. The returned raster tile will be a JPEG.

    Libraries like Mapbox.js and Leaflet.js use this endpoint to render raster tiles from a Mapbox Studio style with L.mapbox.styleLayer and L.tileLayer.

    Required parametersDescription
    usernameThe username of the account to which the style belongs.
    style_idThe ID of the style from which to return a raster tile.
    {z}/{x}/{y}The tile coordinates as described in the Slippy Map Tilenames specification. They specify the tile's zoom level {z}, column {x}, and row {y}.

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

    Optional parametersDescription
    tilesizeDefault is 512x512 pixels. (512x512 image tiles are offset by one zoom level compared to 256x256 tiles from Mapbox Studio Classic styles. For example, 512x512 tiles at zoom level 4 are equivalent to Mapbox Studio Classic styles tiles at zoom level 5.) 256x256 tiles from the endpoint are one quarter of the size of 512x512 tiles. Therefore, they require 4 times as many API requests and accumulate 4 times as many map views to render the same area.
    @2xRender the raster tile at a @2x scale factor, so tiles are scaled to 1024x1024 pixels.

    Example request: Retrieve raster tiles from styles

    # Returns a default 512x512 pixel tile
    $ curl "https://api.mapbox.com/styles/v1/mapbox/streets-v11/tiles/1/1/0?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
    
    # Returns a 256x256 pixel tile
    $ curl "https://api.mapbox.com/styles/v1/mapbox/streets-v11/tiles/256/1/1/0?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
    
    # Returns a 1024x1024 pixel tile
    $ curl "https://api.mapbox.com/styles/v1/mapbox/streets-v11/tiles/512/1/1/0@2x?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
    

    Response: Retrieve raster tiles from styles

    The returned 512x512 pixel or 256x256 pixel raster tile will be a JPEG.

    Static Tiles API errors

    Response body messageHTTP status codeDescription
    Not Authorized - Invalid Token401Check the access token you used in the query.
    Style not found404Check the style ID used in the query.
    Zoom level must be between 0-20.422The zoom level specified in the query is larger than 20 or contains non-numeric characters.

    Static Tiles API restrictions and limits

    • Use of the Static Tiles API endpoint is rate limited based on your user plan. The default rate limit is 2,000 requests per minute. If you require a higher rate limit, contact us.
    • Exceeding this limit will result in an HTTP 429 response. For information on rate limit headers, see the Rate limit headers section.
    Was this section on Static Tiles helpful?

    Styles

    The Mapbox Styles API lets you read and change map styles, fonts, and images. This API is the basis for Mapbox Studio.

    If you use Studio, Mapbox GL JS, or the Mapbox Mobile SDKs, you are already using the Styles API. This documentation is useful for software developers who want to programmatically read and write these resources. It isn't necessary for you to read or understand this reference to design or use Mapbox maps.

    You will need to be familiar with the Mapbox Style Specification to use the Styles API. The Mapbox Style Specification defines the structure of map styles and is the open standard that helps Studio communicate with APIs and produce maps that are compatible with Mapbox libraries.

    The style object

    A style object is an object that conforms to the Mapbox Style Specification, with some additional account-related properties:

    PropertyDescription
    versionThe style specification version number.
    nameA human-readable name for the style.
    metadataInformation about the style that is used in Mapbox Studio.
    sourcesSources supply the data that will be shown on the map.
    layersLayers will be drawn in the order of this array.
    createdThe date and time the style was created.
    idThe ID of the style.
    modifiedThe date and time the style was last modified.
    ownerThe username of the style owner.
    visibilityAccess control for the style, either public or private. Private styles require an access token belonging to the owner. Public styles may be requested with an access token belonging to any user.
    draftIndicates whether the style is a draft (true) or whether it has been published (false).

    Drafts

    The Styles API supports drafts, so every style can have both published and draft versions. This means that you can make changes to a style without publishing them or deploying them in your app. For each style-related endpoint, you can interact with the draft version of a style by placing draft/ after the style ID, like /styles/v1/{username}/{style_id}/draft/sprite.

    Example style object

    {
      "version": 8,
      "name": "{name}",
      "metadata": "{metadata}",
      "sources": "{sources}",
      "sprite": "mapbox://sprites/{username}/{style_id}",
      "glyphs": "mapbox://fonts/{username}/{fontstack}/{range}.pbf",
      "layers": ["{layers}"],
      "created": "2015-10-30T22:18:31.111Z",
      "id": "{style_id}",
      "modified": "2015-10-30T22:22:06.077Z",
      "owner": "{username}",
      "visibility": "private",
      "draft": true
    }
    

    Retrieve a style

    get
    /styles/v1/{username}/{style_id}
    styles:read

    Retrieve a style as a JSON document.

    Required parametersDescription
    usernameThe username of the account to which the style belongs.
    style_idThe ID of the style to be retrieved.

    Example request: Retrieve a style

    $ curl "https://api.mapbox.com/styles/v1/examples/cjikt35x83t1z2rnxpdmjs7y7?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
    
    Endpoint support

    Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application. The following SDK supports this endpoint:

    See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.

    Response: Retrieve a style

    The returned style object will be in the Mapbox Style format.

    Example response: Retrieve a style

    {
      "version": 8,
      "name": "Meteorites",
      "metadata": {
        "mapbox:origin": "basic-template-v1",
        "mapbox:autocomposite": true,
        "mapbox:type": "template",
        "mapbox:sdk-support": {
          "js": "0.45.0",
          "android": "6.0.0",
          "ios": "4.0.0"
        }
      },
      "center": [
        74.24426803763072,
        -2.2507114487818853
      ],
      "zoom": 0.6851443156248076,
      "bearing": 0,
      "pitch": 0,
      "sources": {
        "composite": {
          "url": "mapbox://mapbox.mapbox-streets-v8,examples.0fr72zt8",
          "type": "vector"
        }
      },
      "sprite": "mapbox://sprites/examples/cjikt35x83t1z2rnxpdmjs7y7",
      "glyphs": "mapbox://fonts/{username}/{fontstack}/{range}.pbf",
      "layers": [
        {
          "id": "background",
          "type": "background",
          "layout": {},
          "paint": {
            "background-color": [ ]
          }
        },
        { }
      ],
      "created": "2015-10-30T22:18:31.111Z",
      "id": "cjikt35x83t1z2rnxpdmjs7y7",
      "modified": "2015-10-30T22:22:06.077Z",
      "owner": "examples",
      "visibility": "public",
      "draft": false
    }
    

    List styles

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

    Retrieve a list of styles for a specific account. This endpoint supports pagination.

    Required parameterDescription
    usernameThe username of the account to which the styles belong.

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

    Optional parametersDescription
    limitThe maximum number of styles to return.
    startThe ID of the style after which to start the listing. The style ID is found in the Link header of a response. See the pagination section for details.

    Example request: List styles

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

    Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application. The following SDK supports this endpoint:

    See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.

    Response: List styles

    This endpoint returns style metadata instead of returning full styles.

    Example response: List styles

    [
      {
        "version": 8,
        "name": "My Awesome Style",
        "created": "{timestamp}",
        "id": "cige81msw000acnm7tvsnxcp5",
        "modified": "{timestamp}",
        "owner": "{username}"
      },
      {
        "version": 8,
        "name": "My Cool Style",
        "created": "{timestamp}",
        "id": "cig9rvfe300009lj9kekr0tm2",
        "modified": "{timestamp}",
        "owner": "{username}"
      }
    ]
    

    Create a style

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

    Creates a style in your account. The posted style object must be both valid JSON and aligned to the most recent version of the Mapbox Style Specification. Invalid styles will produce a descriptive validation error.

    GeoJSON sources are not supported by the Styles API.

    If the optional name property is not used in the request body, the name of the new style will be automatically set to the style's ID.

    Required parameterDescription
    usernameThe username of the account to which the new style will belong.

    Example request: Create a style

    $  -X POST "https://api.mapbox.com/styles/v1/{username}?access_token=
    YOUR_MAPBOX_ACCESS_TOKEN
    "
    \ --data @basic-v9.json \ --header "Content-Type:application/json"

    Example request body: Create a style

    {
      "version": 8,
      "name": "My Awesome Style",
      "metadata": { },
      "sources": {
        "myvectorsource": {
          "url": "mapbox://{map_id}",
          "type": "vector"
        },
        "myrastersource": {
          "url": "mapbox://{map_id}",
          "type": "raster"
        }
      },
      "glyphs": "mapbox://fonts/{username}/{fontstack}/{range}.pbf",
      "layers": [ ]
    }
    
    Endpoint support

    Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application. The following SDK supports this endpoint:

    See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.

    Response: Create a style

    The style you get back from the API will contain new properties that the server has added: created, id, modified, owner, and draft.

    Example response: Create a style

    {
      "version": 8,
      "name": "My Awesome Style",
      "metadata": { },
      "sources": {
        "myvectorsource": {
          "url": "mapbox://{map_id}",
          "type": "vector"
        },
        "myrastersource": {
          "url": "mapbox://{map_id}",
          "type": "raster"
        }
      },
      "sprite": "mapbox://sprites/{username}/{style_id}",
      "glyphs": "mapbox://fonts/{username}/{fontstack}/{range}.pbf",
      "layers": [ ],
      "created": "2015-10-30T22:18:31.111Z",
      "id": "{style_id}",
      "modified": "2015-10-30T22:22:06.077Z",
      "owner": "{username}",
      "draft": true
    }
    

    Update a style

    patch
    /styles/v1/{username}/{style_id}
    styles:write

    Updates an existing style in your account with new content.

    If you request a style and then use the same content to update the style, this action will fail. You must remove the created and modified properties before updating a style. The name property, which is optional for creating a style, is required to update a style.

    Cross-version PATCH requests are rejected.

    Required parametersDescription
    usernameThe username of the account to which the style belongs.
    style_idThe ID of the style to be updated.

    Example request: Update a style

    $  -X PATCH "https://api.mapbox.com/styles/v1/{username}/{style_id}?access_token=
    YOUR_MAPBOX_ACCESS_TOKEN
    "
    \ --data @basic-v9.json \ --header "Content-Type:application/json"

    Example request body: Update a style

    {
      "version": 8,
      "name": "New Style Name",
      "metadata": { },
      "sources": { },
      "sprite": "mapbox://sprites/{username}/{style_id}",
      "glyphs": "mapbox://fonts/{username}/{fontstack}/{range}.pbf",
      "layers": [{
        "id": "new-layer",
        "type": "background",
        "paint": {
          "background-color": "#111"
        },
        "interactive": true
        }],
        "owner": "{username}",
        "draft": true
      }
    
    Endpoint support

    Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application. The following SDK supports this endpoint:

    See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.

    Response: Update a style

    A successful request to this endpoint will return the updated style object.

    Example response: Update a style

    {
      "version": 8,
      "name": "New Style Name",
      "metadata": { },
      "sources": { },
      "sprite": "mapbox://sprites/{username}/{style_id}",
      "glyphs": "mapbox://fonts/{username}/{fontstack}/{range}.pbf",
      "layers": [{
        "id": "new-layer",
        "type": "background",
        "paint": {
          "background-color": "#111"
        },
        "interactive": true
      }],
      "created": "2015-10-30T22:18:31.111Z",
      "id": "{style_id}",
      "modified": "2015-10-30T22:22:06.077Z",
      "owner": "{username}",
      "draft": true
    }
    

    Delete a style

    delete
    /styles/v1/{username}/{style_id}
    styles:write

    Delete a style. All sprites that belong to this style will also be deleted, and the style will no longer be available.

    Required parametersDescription
    usernameThe username of the account to which the style belongs.
    style_idThe ID of the style to be deleted.

    Example request: Delete a style

    $ curl -X DELETE "https://api.mapbox.com/styles/v1/{username}/{style_id}?access_token=
    YOUR_MAPBOX_ACCESS_TOKEN
    "
    Endpoint support

    Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application. The following SDK supports this endpoint:

    See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.

    Response: Delete a style

    HTTP 204

    Request embeddable HTML

    get
    /styles/v1/{username}/{style_id}.html
    styles:read

    Request embeddable HTML.

    Required parametersDescription
    usernameThe username of the account to which the style belongs.
    style_idThe ID of the style to be embedded.

    The embeddable HTML that is returned can be further modified with the following optional query parameters:

    Optional path parametersDescription
    draftIndicates whether the style is a draft (true) or whether it has been published (false). For more information, see the Drafts section.
    Optional query parametersDescription
    zoomwheelWhether to provide a zoomwheel, which enables a viewer to zoom in and out of the map using the mouse (true, default), or not (false).
    titleWhether to display a title box with the map's title and owner in the upper right corner of the map (true) or not (false, default).
    fallbackServe a fallback raster map (true) or not (false, default).
    hashSpecify a zoom level and location for the map to center on, in the format #zoom/lat/lon. Note: This hash is placed after the access_token in the request.

    Example: Request embeddable HTML

    <!-- Map is centered on San Francisco at z15 -->
    <iframe
      src='https://api.mapbox.com/styles/v1/mapbox/streets-v11.html?title=true&zoomwheel=false&access_token=YOUR_MAPBOX_ACCESS_TOKEN#15/37.771/-122.436' />
    
    Endpoint support

    Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application. The following SDK supports this endpoint:

    See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.

    Retrieve a map's WMTS document

    get
    /styles/v1/{username}/{style_id}/wmts

    Mapbox supports access via the WMTS standard, which lets you use maps with desktop and online GIS software like ArcMap and QGIS.

    Required parametersDescription
    usernameThe username of the account to which the style belongs.
    style_idThe ID of the style for which to return a WMTS document.

    Example request: Retrieve a map's WMTS document

    $ curl "https://api.mapbox.com/styles/v1/mapbox/streets-v11/wmts?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
    

    Response: Retrieve a map's WMTS document

    The response to a request to this endpoint will be a map's WMTS document.

    Sprites

    Sprites are the way that Mapbox GL JS and Mapbox Mobile efficiently request and show images. Sprites are collections of images that can be used in styles as icons or patterns in symbol layers. An image in a sprite can be an icon, a pattern, or an illustration. These SVG images can be added and removed from the sprite at will. The Styles API automatically collects these SVG images and renders them into a single PNG image and a JSON document that describes where each image is positioned.

    The sprite JSON document is specified as part of the Mapbox Style Specification.

    Sprites are managed on a per-style basis. Each sprite belongs to a style, so the sprite limit of 500 images is also a per-style limit. All sprite-related API methods require a {style_id} parameter referring to the style to which the sprite belongs.

    Retrieve a sprite image or JSON

    get
    /styles/v1/{username}/{style_id}/sprite{@2x}.{format}
    styles:read

    Retrieve a sprite image or its JSON document from a Mapbox style.

    Required parametersDescription
    usernameThe username of the account to which the style belongs.
    style_idThe ID of the style to which the sprite belongs.

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

    Optional parametersDescription
    @2xRender the sprite at a @2x, @3x, or @4x scale factor for high-density displays.
    formatBy default, this endpoint returns a sprite's JSON document. Specify .png to return the sprite image instead.

    Example request: Retrieve a sprite image or JSON

    # Request the sprite image as a png
    
    $ curl "https://api.mapbox.com/styles/v1/{username}/{style_id}/sprite.png?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
    
    # Request json for a 3x scale sprite
    
    $ curl "https://api.mapbox.com/styles/v1/{username}/{style_id}/sprite@3x?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
    
    Endpoint support

    Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application. The following SDK supports this endpoint:

    See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.

    Response: Retrieve a sprite image or JSON

    The response to a successful request to this endpoint is either a sprite image or its JSON response, depending on which was requested.

    Example response: Retrieve a sprite image or JSON

    {
      "default_marker": {
        "width": 20,
        "height": 50,
        "x": 0,
        "y": 0,
        "pixelRatio": 2
      },
      "secondary_marker": {
        "width": 20,
        "height": 50,
        "x": 20,
        "y": 0,
        "pixelRatio": 2
      }
    }
    

    Add new image to sprite

    put
    /styles/v1/{username}/{style_id}/sprite/{icon_name}
    styles:write

    Add a new image to an existing sprite in a Mapbox style. The request body should be raw SVG data.

    Required parametersDescription
    usernameThe username of the account to which the style belongs.
    style_idThe ID of the style to which the sprite belongs.
    icon_nameThe name of the new image that is being added to the style.

    Example request: Add new image to sprite

    # Add a new image (`aerialway`) to an existing sprite
    
    $ curl -X PUT \
      "https://api.mapbox.com/styles/v1/{username}/{style_id}/sprite/aerialway?access_token=
    YOUR_MAPBOX_ACCESS_TOKEN
    "
    \ --data @aerialway-12.svg
    Endpoint support

    Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application. The following SDK supports this endpoint:

    See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.

    Response: Add new image to sprite

    The response to a successful request to this endpoint will be the updated sprite.

    Example response: Add new image to sprite

    {
      "newsprite": {
        "width": 1200,
        "height": 600,
        "x": 0,
        "y": 0,
        "pixelRatio": 1
      },
      "default_marker": {
        "width": 20,
        "height": 50,
        "x": 0,
        "y": 600,
        "pixelRatio": 1
      }
    }
    

    Delete image from sprite

    delete
    /styles/v1/{username}/{style_id}/sprite/{icon_name}
    styles:write

    Remove an image from an existing sprite.

    Required parametersDescription
    usernameThe username of the account to which the style belongs.
    style_idThe ID of the style to which the sprite belongs.
    icon_nameThe name of the new image to delete from the style.

    Example request: Delete image from sprite

    curl -X DELETE "https://api.mapbox.com/styles/v1/{username}/{style_id}/sprite/{icon_name}?access_token=
    YOUR_MAPBOX_ACCESS_TOKEN
    "
    Endpoint support

    Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application. The following SDK supports this endpoint:

    See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.

    Response: Delete image from sprite

    The response to a successful request to this endpoint will be the modified sprite.

    Example response: Delete image from sprite

    {
      "default_marker": {
        "width": 20,
        "height": 50,
        "x": 0,
        "y": 600,
        "pixelRatio": 1
      },
      "secondary_marker": {
        "width": 20,
        "height": 50,
        "x": 20,
        "y": 600,
        "pixelRatio": 1
      }
    }
    

    Styles API errors

    Response body messageHTTP status codeDescription
    Not Authorized - Invalid Token401Check the access token you used in the query.
    This endpoint requires a token with {scope} scope403The access token used in the query needs the specified scope.
    Forbidden403You do not have permission to view styles for the requested account.
    Style not found404Check the style ID used in the query.
    Failed to create style422Check the syntax of the JSON in your request body when creating a style.

    Styles API restrictions and limits

    • Use of the Mapbox Styles API endpoint is rate limited based on your user plan. The default is 2,000 requests per minute.
    • Styles cannot reference more than 15 sources.
    • Styles cannot be larger than 5 MB. This limit only applies to the style document itself, not the sprites, fonts, tilesets, or other resources it references.
    • An account is allowed to have an unlimited number of styles regardless of its pricing plan.

    Styles API sprites restrictions and limits

    • Each image must be smaller than 400 KB.
    • Mapbox supports most, but not all, SVG properties. These limits are described in our SVG troubleshooting guide.
    • Images can be up to 512 pixels in each dimension.
    • Image names must be fewer than 255 characters in length.
    • Sprites can contain up to 500 images.
    Was this section on Styles helpful?

    Vector Tiles

    The Mapbox Vector Tiles API serves vector tiles generated from Mapbox Studio styles.

    Retrieve vector tiles

    get
    /v4/{map_id}/{zoom}/{x}/{y}{@2x}.{format}
    Required parametersDescription
    map_idUnique identifier for the vector tileset in the format username.id. To composite multiple vector tilesets, use a comma-separated list of up to 15 tileset IDs.
    zoomSpecifies the tile's zoom level, as described in the Slippy Map Tilenames specification.
    {x}/{y}Specifies the tile's column {x} and row {y}, as described in the Slippy Map Tilenames specification.
    formatSpecifies the format of the returned tiles:
    .mvtVector tile
    .vector.pbfVector tile

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

    Optional parametersDescription
    @2xRequest a higher DPI version of the image.
    styleRequired for style-optimized tile requests. The style parameter is broken into two parts, the style ID and the style's recently edited timestamp, in the format <style ID>@<timestamp>. The timestamp parameter comes from the style JSON's modified property, which is included with any style created with Mapbox Studio.
    Retrieve style-optimized vector tiles

    Vector tiles can be further optimized by including the style ID with the tile request. If the style parameter is provided, the sources, filters, minzoom, and maxzoom properties of that style are analyzed, and data that won't be visible on the map is removed from the vector tile. Mapbox GL JS can request style-optimized vector tiles that are hosted on Mapbox with a Mapbox Style JSON.

    Unused layers and features are removed from optimized styles. If you plan to dynamically change the style at runtime using Mapbox GL JS or a Mapbox mobile SDK, broadening filters and zoom ranges won't work the same way since any data that isn't visible with the loaded style also won't be included in the data.

    Example request: Retrieve vector tiles

    $ curl "https://api.mapbox.com/v4/mapbox.mapbox-streets-v8/1/0/0.mvt?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
    
    # Return a style-optimized tile using the style query parameter
    
    $ curl "https://api.mapbox.com/v4/mapbox.mapbox-streets-v8/12/1171/1566.mvt?style=mapbox://styles/mapbox/streets-v11@00&access_token=YOUR_MAPBOX_ACCESS_TOKEN"
    

    Response: Retrieve vector tiles

    The response is a vector tile in the specified format. For performance, image tiles are delivered with a max-age header value set 12 hours in the future.

    Vector Tiles API errors

    Response body messageHTTP status codeDescription
    Not Authorized - No Token401No token was used in the query.
    Not Authorized - Invalid Token401Check the access token you used in the query.
    Tileset {tileset name} does not exist404Check the name of the tileset you used in the query.
    Tile not found404Check the column and row of the tile requested in the query.
    Zoom level must be between 0-30.422The zoom level specified in the query is larger than 30 or contains non-numeric characters.
    Tileset does not reference vector data422The tileset specified in the query is a raster tileset rather than a vector tileset. To retrieve raster tiles, use the Raster Tiles API.

    Vector Tiles API restrictions and limits

    • Use of the Mapbox Vector Tiles API endpoint is rate limited based on your user plan. The default is 100,000 requests per minute. If you require a higher rate limit, contact us.
    • Exceeding your user plan's number requests per minute will result in an HTTP 429 Too Many Requests response.
    • For information on rate limit headers, see the Rate limit headers section.
    Was this section on Vector Tiles helpful?

    Raster Tiles

    The Mapbox Raster Tiles API serves raster tiles generated from satellite imagery tilesets and tilesets generated from raster data uploaded to Mapbox.com.

    Retrieve raster tiles

    get
    /v4/{map_id}/{zoom}/{x}/{y}{@2x}.{format}
    Required parametersDescription
    map_idUnique identifier for the raster tileset in the format username.id. To composite multiple tilesets, use a comma-separated list of up to 15 tileset IDs.
    zoomSpecifies the tile's zoom level, as described in the Slippy Map Tilenames specification.
    {x}/{y}Specifies the tile's column {x} and row {y}, as described in the Slippy Map Tilenames specification.
    formatSpecifies the format of the returned tiles:
    .grid.jsonUTFGrid
    .pngTrue color PNG
    .png3232 color indexed PNG
    .png6464 color indexed PNG
    .png128128 color indexed PNG
    .png256256 color indexed PNG
    .jpg7070% quality JPG
    .jpg8080% quality JPG
    .jpg9090% quality JPG
    The format of any image request can be replaced by any of these formats to adjust image quality for different bandwidth requirements. Higher-compression formats like jpg70 or png32 can be useful to favor performance over image quality.

    Note: Tiles that include mapbox.satellite are always delivered as JPEGs, even if the URL specifies PNG. The PNG format can't efficiently encode photographic images like those used by mapbox.satellite.
    Optional parametersDescription
    @2xRequest a higher DPI version of the image.

    Example request: Retrieve raster tiles

    # Retrieve a 2x tile; this 512x512 tile is appropriate for high-density displays
    
    $ curl "https://api.mapbox.com/v4/mapbox.satellite/1/0/0@2x.jpg90?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
    

    Response: Retrieve raster tiles

    The response is a raster image tile in the specified format. For performance, image tiles are delivered with a max-age header value set 12 hours in the future.

    Raster Tiles API errors

    Response body messageHTTP status codeDescription
    Not Authorized - No Token401No token was used in the query.
    Not Authorized - Invalid Token401Check the access token you used in the query.
    Tileset {tileset name} does not exist404Check the name of the tileset you used in the query.
    Tile not found404Check the column and row of the tile requested in the query.
    Zoom level must be between 0-30.422The zoom level specified in the query is larger than 30 or contains non-numeric characters.
    Invalid quality value {value} for raster format {jpg|png}422The format specified in the query must be one of the formats listed in the Retrieve raster tiles section of this documentation.

    Raster Tiles API restrictions and limits

    • Use of the Mapbox Raster Tiles API endpoint is rate limited based on your user plan. The default is 100,000 requests per minute. If you require a higher rate limit, contact us.
    • Exceeding your user plan's number requests per minute will result in an HTTP 429 Too Many Requests response.
    • For information on rate limit headers, see the Rate limit headers section.
    Was this section on Raster Tiles helpful?

    Tilequery

    The Mapbox Tilequery API allows you to retrieve data about specific features from a vector tileset, based on a given latitude and longitude. The Tilequery API makes it possible to query for features within a radius, do point-in-polygon queries, query for features in multiple composite layers, and augment data from the Mapbox Geocoding API with custom data.

    Mapbox Tilequery API has some functional similarities to the reverse geocoding function of the Mapbox Geocoding API, which accepts a {longitude},{latitude} pair and returns an address. The Tilequery API returns the location and properties of the features within the query radius.

    To create and run sample Tilequery API queries and see the results displayed on a map, use the Tilequery API playground.

    Retrieve features from vector tiles

    get
    /v4/{map_id}/tilequery/{lon},{lat}.json

    Use this endpoint to retrieve features from vector tiles.

    Required parametersDescription
    map_idThe ID of the map being queried. To composite multiple layers, provide a comma-separated list of map IDs.
    {lon},{lat}The longitude and latitude to be queried.

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

    Optional parametersDescription
    radiusThe approximate distance in meters to query for features. Defaults to 0, which performs a point-in-polygon query. Has no upper bound. Required for queries against point and line data. Due to the nature of tile buffering, a query with a large radius made against equally large point or line data may not include all possible features in the results. Queries will use tiles from the maximum zoom of the tileset, and will only include the intersecting tile plus eight surrounding tiles when searching for nearby features.
    limitThe number of features between 1-50 to return. Defaults to 5.
    dedupeDetermines whether the features in the result will be deduplicated (true, default) or not (false). The Tilequery API assumes that features are duplicates if all of the following are true: the features are from the same layer; the features are the same geometry type; and the features have the same ID and the same properties (or just the same properties, if the features do not have IDs).
    geometryReturn only a specific geometry type. Options are polygon, linestring, or point. Defaults to returning all geometry types.
    layersA comma-separated list of layers to query, rather than querying all layers. If a specified layer does not exist, it is skipped. If no layers exist, returns an empty FeatureCollection.

    Point-in-polygon queries

    To perform a point-in-polygon query, do not use the radius parameter, which will leave it set at the default value of 0. A point-in-polygon query will only return polygons that your query point is within. Any query point that exists directly along an edge of a polygon will not be returned.

    Be aware of the number of results you are returning. There may be overlapping polygons in a tile, especially if you are querying multiple layers. If a query point exists within multiple polygons, there is no way to sort results such that they are returned in the order they were queried. If there are more results than you specified with the limit parameter, they will be cut off once the query hits the maximum number of results.

    Example request: Retrieve features from vector tiles

    # Retrieve features within a 10 meter radius of the specified location
    
    $ curl "https://api.mapbox.com/v4/mapbox.mapbox-streets-v8/tilequery/-122.42901,37.80633.json?radius=10&access_token=YOUR_MAPBOX_ACCESS_TOKEN"
    
    # Return at most 20 features
    
    $ curl "https://api.mapbox.com/v4/mapbox.mapbox-streets-v8/tilequery/-122.42901,37.80633.json?limit=20&access_token=YOUR_MAPBOX_ACCESS_TOKEN"
    
    # Query multiple maps
    
    $ curl "https://api.mapbox.com/v4/{map_id_1},{map_id_2},{map_id_3}/tilequery/-122.42901,37.80633.json&access_token=YOUR_MAPBOX_ACCESS_TOKEN"
    
    # Return only results from the poi_label and building layers within a 30 meter radius of the specified location
    
    $ curl "https://api.mapbox.com/v4/mapbox.mapbox-streets-v8/tilequery/-122.42901,37.80633.json?radius=30&layers=poi_label,building&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 features from vector tiles

    A request to the Tilequery API returns a GeoJSON FeatureCollection of features at or near the geographic point described by {longitude},{latitude} and within the distance described by the optional radius parameter.

    The Tilequery API response is ordered based on which features are closest to the queried {longitude},{latitude}. If point-in-polygon query was performed, then all returned features are directly at the query point and proximity does not influence the order in which they are returned.

    Each feature in the response body contains the following properties:

    PropertyDescription
    geometry.typeThis will always be Point. The Tilequery API does not return the full geometry of a feature. Instead, it returns the closest point ({longitude},{latitude}) of a feature.
    geometry.coordinatesThe coordinates of the returned feature.
    propertiesThe properties of the feature.
    properties.tilequery.distanceThe approximate surface distance in meters from the feature result to the queried point. Note that this number represents geographical distance, not distance along the road network. If distance is 0, the query point is within the geometry (point-in-polygon).
    properties.tilequery.geometryThe original geometry type of the feature. This can be ”point”, ”linestring”, or ”polygon”. The actual geometry of the feature is not returned in the result set. The original geometry type of a feature impacts what gets returned:
    Original geometry of featureResult
    polygonIf the query point is within the polygon, the result will be the query point location. If the query point is outside the polygon, the result is the interpolated closest point along the nearest edge of the feature within the radius threshold.
    linestringThe result is the interpolated closest point along the feature within the radius threshold.
    pointThe result is the nearest point within the radius threshold.
    properties.tilequery.layerThe vector tile layer of the feature result.

    Example response: Retrieve features from vector tiles

    {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "geometry": {
            "type": "Point",
            "coordinates": [
              -122.42901,
              37.80633
            ]
          },
          "properties": {
            "class": "national_park",
            "type": "national_park",
            "tilequery": {
              "distance": 0,
              "geometry": "polygon",
              "layer": "landuse_overlay"
            }
          }
        },
        {
          "type": "Feature",
          "geometry": {
            "type": "Point",
            "coordinates": [
              -122.4289919435978,
              37.806283149631255
            ]
          },
          "properties": {
            "localrank": 1,
            "maki": "park",
            "name": "Fort Mason",
            "name_ar": "Fort Mason",
            "name_de": "Fort Mason",
            "name_en": "Fort Mason Center",
            "name_es": "Fort Mason",
            "name_fr": "Fort Mason",
            "name_pt": "Fort Mason",
            "name_ru": "Fort Mason",
            "name_zh": "梅森堡",
            "name_zh-Hans": "梅森堡",
            "ref": "",
            "scalerank": 1,
            "type": "National Park",
            "tilequery": {
              "distance": 5.4376397785894595,
              "geometry": "point",
              "layer": "poi_label"
            }
          }
        }
      ]
    }
    

    Tilequery API errors

    Response body messageHTTP status codeDescription
    Empty FeatureCollection200If an empty FeatureCollection is returned, check whether the specified layer exists.
    Not Authorized - No Token401No token was used in the query.
    Not Authorized - Invalid Token401Check the access token you used in the query.
    Tileset {tileset name} does not exist404Check the name of the tileset you used in the query.
    options.limit must be a number between 1 and 50422The limit specified in the query is larger than 50 or contains non-numeric characters.
    Invalid {lon|lat} value: {value}422Check the latitude and longitude values you used in the query.
    options.geometry must be \"polygon\", \"linestring\", or \"point\"422The geometry parameter must be one of the options described in the Retrieve features from vector tiles section of this documentation.

    Tilequery API restrictions and limits

    • Use of the Tilequery API endpoint is rate limited based on your user plan. The default is 300 requests per minute.
    • Exceeding your user plan's number requests per minute will result in an HTTP 429 Too Many Requests response.
    • For information on rate limit headers, see the Rate limit headers section.

    If you require a higher rate limit, contact us.

    Was this section on Tilequery helpful?

    Uploads

    The Mapbox Uploads API transforms geographic data into tilesets that can be used with maps and geographic applications. Given a wide variety of geospatial formats, it normalizes projections and generates tiles at multiple zoom levels to make data viewable on the web.

    The upload workflow follows these steps:

    1. Request temporary S3 credentials that allow you to stage the file. Jump to the Retrieve S3 credentials section.
    2. Use an S3 client to upload the file to Mapbox's S3 staging bucket using these credentials. Learn more about this process in the Upload to Mapbox using cURL tutorial.
    3. Create an upload using the staged file's URL. Jump to the Create an upload section.
    4. Retrieve the upload's status as it is being processed into a tileset. Jump to the Retrieve upload status section.

    Note: This documentation discusses how to interact with the Mapbox Uploads API programmatically. For a step-by-step guide on how to use the Uploads API to stage a file to Amazon S3 and create an upload, use the Upload to Mapbox using cURL tutorial.

    Retrieve S3 credentials

    post
    /uploads/v1/{username}/credentials
    uploads:write

    Mapbox provides an Amazon S3 bucket to stage your file while your upload is processed. This endpoint allows you to retrieve temporary S3 credentials to use during the staging process.

    Note: This step is necessary before you can stage a file in the Amazon S3 bucket provided by Mapbox. All uploads must be staged in this Amazon S3 bucket before being uploaded to your Mapbox account. To learn more about how to stage an upload to Amazon S3, read the Upload to Mapbox using cURL tutorial.

    Required parameterDescription
    usernameThe username of the account to which you are uploading a tileset.

    Example request: Retrieve S3 credentials

    $ curl -X POST "https://api.mapbox.com/uploads/v1/{username}/credentials?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.

    Example AWS CLI usage

    $ export AWS_ACCESS_KEY_ID={accessKeyId}
    $ export AWS_SECRET_ACCESS_KEY={secretAccessKey}
    $ export AWS_SESSION_TOKEN={sessionToken}
    $ aws s3 cp /path/to/file s3://{bucket}/{key} --region us-east-1
    

    Response: Retrieve S3 credentials

    The response body is a JSON object that contains the following properties:

    PropertyDescription
    accessKeyIdAWS Access Key ID
    bucketS3 bucket name
    keyThe unique key for data to be staged
    secretAccessKeyAWS Secret Access Key
    sessionTokenA temporary security token
    urlThe destination URL of the file

    Use these credentials to store your data in the provided bucket with the provided key using the AWS CLI or AWS SDK of your choice. The bucket is located in AWS region us-east-1.

    Example response: Retrieve S3 credentials

    {
      "accessKeyId": "{accessKeyId}",
      "bucket": "somebucket",
      "key": "hij456",
      "secretAccessKey": "{secretAccessKey}",
      "sessionToken": "{sessionToken}",
      "url": "{url}"
    }
    

    Create an upload

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

    After you have used the temporary S3 credentials to transfer your file to Mapbox's staging bucket, you can trigger the generation of a tileset using the file's URL and a destination tileset ID.

    Uploaded files must be in the bucket provided by Mapbox. Requests for resources from other S3 buckets or URLs will fail.

    Required parameterDescription
    usernameThe username of the account to which you are uploading

    The request body must be a JSON object that contains the following properties:

    Request body propertiesDescription
    tilesetThe map ID to create or replace, in the format username.nameoftileset. Limited to 32 characters. This character limit does not include the username. The only allowed special characters are - and _.
    urlThe HTTPS URL of the S3 object provided in the credential request, or the dataset ID of an existing Mapbox dataset to be uploaded.
    nameOptional. The name of the tileset. Limited to 64 characters.

    If you reuse a tileset value, this action will replace existing data. Use a random value to make sure that a new tileset is created, or check your existing tilesets first.

    Example request: Create an upload

    $ curl -X POST -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{
      "url": "http://{bucket}.s3.amazonaws.com/{key}",
      "tileset": "{username}.{tileset-name}"
    }' 'https://api.mapbox.com/uploads/v1/{username}?access_token=
    YOUR_MAPBOX_ACCESS_TOKEN
    '

    Example request body: Create an upload (AWS S3 bucket not required)

    {
      "tileset": "{username}.mytileset",
      "url": "mapbox://datasets/{username}/{dataset}",
      "name": "example-dataset"
    }
    
    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 an upload

    The response body is a JSON object that contains the following properties:

    PropertyDescription
    completeWhether the upload is complete (true) or not complete (false).
    tilesetThe ID of the tileset that will be created or replaced if upload is successful.
    errorIf null, the upload is in progress or has successfully completed. Otherwise, provides a brief explanation of the error.
    idThe unique identifier for the upload.
    nameThe name of the upload.
    modifiedA timestamp indicating when the upload resource was last modified.
    createdA timestamp indicating when the upload resource was created.
    ownerThe unique identifier for the owner's account.
    progressThe progress of the upload, expressed as a float between 0 (started) and 1 (completed).

    Example response: Create an upload

    {
      "complete": false,
      "tileset": "example.markers",
      "error": null,
      "id": "hij456",
      "name": "example-markers",
      "modified": "{timestamp}",
      "created": "{timestamp}",
      "owner": "{username}",
      "progress": 0
    }
    

    Retrieve upload status

    get
    /uploads/v1/{username}/{upload_id}
    uploads:read

    Once an upload is created, you can track its status. Uploads have a progress property that start at 0 and end at 1 when an upload is complete. If there's an error processing an upload, the error property will include an error message.

    Required parametersDescription
    usernameThe username of the account for which you are requesting an upload status.
    upload_idThe ID of the upload. Provided in the response body to a successful upload request.

    Example request: Retrieve upload status

    $ curl "https://api.mapbox.com/uploads/v1/{username}/{upload_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 upload status

    The response body is a JSON object containing the following properties:

    PropertyDescription
    completeBoolean. Indicates whether the upload is complete (true) or not complete (false).
    tilesetThe ID of the tileset that will be created or replaced if upload is successful.
    errorIf null, the upload is in progress or has successfully completed. Otherwise, provides a brief explanation of the error.
    idThe unique identifier for the upload.
    nameThe name of the upload.
    modifiedThe timestamp for when the upload resource was last modified.
    createdThe timestamp for when the upload resource was created.
    ownerThe unique identifier for the owner's account.
    progressThe progress of the upload, expressed as a float between 0 (started) and 1 (completed).

    Example response: Retrieve upload status

    {
      "complete": true,
      "tileset": "example.markers",
      "error": null,
      "id": "hij456",
      "name": "example-markers",
      "modified": "{timestamp}",
      "created": "{timestamp}",
      "owner": "{username}",
      "progress": 1
    }
    

    Retrieve recent upload statuses

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

    Retrieve multiple upload statuses at the same time, sorted by the most recently created.

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

    Required parameterDescription
    usernameThe username of the account for which you are requesting upload statuses.

    The results from this endpoint can be further modified with the following optional parameters:

    Optional parametersDescription
    reverseSet this parameter to true to reverse the sorting order of the results. By default, the Uploads API returns the most recently created upload statuses first.
    limitThe maximum number of statuses to return, up to 100.

    Example request: Retrieve recent upload statuses

    $ curl "https://api.mapbox.com/uploads/v1/{username}?access_token=
    YOUR_MAPBOX_ACCESS_TOKEN
    "
    # Return at most 10 upload statuses, in chronological order $ curl "https://api.mapbox.com/uploads/v1/{username}?reverse=true&limit=10&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 recent upload statuses

    This request returns the same information as an individual upload status request does, but for all an account's recent uploads. The list is limited to one MB of JSON.

    Example response: Retrieve recent upload statuses

    [{
      "complete": true,
      "tileset": "example.mbtiles",
      "error": null,
      "id": "abc123",
      "name": null,
      "modified": "2014-11-21T19:41:10.000Z",
      "created": "2014-11-21T19:41:10.000Z",
      "owner": "example",
      "progress": 1
    }, {
      "complete": false,
      "tileset": "example.foo",
      "error": null,
      "id": "xyz789",
      "name": "foo",
      "modified": "2014-11-21T19:41:10.000Z",
      "created": "2014-11-21T19:41:10.000Z",
      "owner": "example",
      "progress": 0
    }]
    

    Remove an upload status

    delete
    /uploads/v1/{username}/{upload_id}
    uploads:write

    Remove the status of a completed upload from the upload listing.

    Uploads are only statuses, so removing an upload from the listing doesn't delete the associated tileset. Tilesets can only be deleted from within Mapbox Studio. An upload status cannot be removed from the upload listing until after it has completed.

    Required parametersDescription
    usernameThe username of the associated account.
    upload_idThe ID of the upload. Provided in the response body to a successful upload request.

    Example request: Remove an upload status

    $ curl -X DELETE "https://api.mapbox.com/uploads/v1/{username}/{upload_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: Remove an upload status

    HTTP 204 No content

    Uploads API errors

    To see a list of possible upload errors, visit the Uploads errors page.

    Uploads API restrictions and limits

    • Use of the Mapbox Uploads API endpoint is rate limited based on your user plan. The default is 30 requests per minute.
    • Tileset names are limited to 64 characters.
    • The Uploads API supports different file sizes for various file types:
    File typeSize limit
    TIFF and GeoTIFF10 GB
    MBTiles25 GB
    GeoJSON1 GB
    CSV1 GB
    KML260 MB
    GPX260 MB
    Shapefile (unzipped)260 MB (combined uncompressed size of .shp and .dbf files)
    Shapefiles must be uploaded as compressed .zip files.
    Mapbox Dataset1 GB
    Was this section on Uploads helpful?

    Fonts

    The Mapbox Fonts API accepts fonts as raw binary data, allows those fonts to be deleted, and generates encoded letters for map renderers. Two types of fonts are supported: TrueType fonts, usually with .ttf file extensions, and OpenType fonts, with .otf extensions.

    Fonts are managed on a per-account basis. Styles can use any font from the same account.

    Retrieve font glyph ranges

    get
    /fonts/v1/{username}/{font}/{start}-{end}.pbf
    fonts:read

    While glyph ranges are usually not of interest unless you're building a map renderer, this is the endpoint you can use to access them.

    Font glyph ranges are protocol buffer-encoded signed distance fields. They can be used to show fonts at a variety of scales and rotations. One glyph is used at all scales.

    Required parametersDescription
    usernameThe username of the account to which the font belongs.
    fontThe name of the font. This endpoint supports queries with multiple comma-separated font names.
    startA multiple of 256 between 0 and 65280.
    endThe number indicated by start, plus 255.

    Example request: Retrieve font glyph ranges

    $ curl "https://api.mapbox.com/fonts/v1/{username}/Arial%20Unicode%20MS%20Regular/0-255.pbf?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
    
    Endpoint support

    Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application. The following SDK supports this endpoint:

    See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.

    Response: Retrieve font glyph ranges

    A successful request will return HTTP 200 Success. The response body will be a buffer of the glyphs with Content-Type: application/x-protobuf.

    Fonts API errors

    Response body messageHTTP status codeDescription
    Invalid Range400Check the font glyph range. This error can also occur with empty fonts.
    Not Authorized - No Token401No token was used in the query.
    Not Authorized - Invalid Token401Check the access token you used in the query.
    Not Found404Check the font name or names you used in the query.

    Fonts API restrictions and limits

    • Fonts must be smaller than 30 MB.
    • Accounts are limited to 100 fonts.
    Was this section on Fonts helpful?