Maps service

The Mapbox Maps service is composed of the following APIs:

    Vector Tiles

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

    For information on how the Vector Tiles API is billed, visit the Pricing by product guide.

    Retrieve vector tiles

    get
    /v4/{tileset_id}/{zoom}/{x}/{y}{@2x}.{format}
    Required parametersDescription
    tileset_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.

    For information on how the Raster Tiles API is billed, visit the Pricing by product guide.

    Retrieve raster tiles

    get
    /v4/{tileset_id}/{zoom}/{x}/{y}{@2x}.{format}
    Required parametersDescription
    tileset_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?

    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.

    • For styles that contain vector layers, the returned static map will be a PNG.
    • For styles that contain raster layers, the returned static map will be a JPEG.

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

    For information on how the Static Images API is billed, visit the Pricing by product guide.

    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"
    
    # Querying a style with raster layers returns a JPEG
    $ curl "https://api.mapbox.com/styles/v1/mapbox/satellite-v9/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.

    Response: Retrieve a static map from a style

    • For styles that contain vector layers, the returned static map will be a PNG.
    • For styles that contain raster layers, the returned static map will be a JPEG.

    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

    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.

    For information on how the Static Tiles API is billed, visit the Pricing by product guide.

    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://{tileset_id}",
          "type": "vector"
        },
        "myrastersource": {
          "url": "mapbox://{tileset_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://{tileset_id}",
          "type": "vector"
        },
        "myrastersource": {
          "url": "mapbox://{tileset_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 or shareable 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 along the bottom of the map (true) or not (false, default).
    fallbackServe a fallback raster map (true) or not (false, default).
    mapboxGLVersionSpecify a version of Mapbox GL JS to use to render the map.
    mapboxGLGeocoderVersionSpecify a version of the Mapbox GL geocoder plugin to use to render the map search box.
    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 the Mapbox mobile SDKs 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. This limit is higher for Enterprise customers.

    All sprite-related API methods require a {style_id} parameter that refers 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. This limit is higher for Enterprise customers.
    Was this section on Styles 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.

    For information on how the Tilequery API is billed, visit the Pricing by product guide.

    Retrieve features from vector tiles

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

    Use this endpoint to retrieve features from vector tiles.

    Required parametersDescription
    tileset_idThe ID of the map being queried. To composite multiple layers, use a comma-separated list of up to 15 tileset 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/{tileset_id_1},{tileset_id_2},{tileset_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

    Beta feature: Upload vector tilesets with the Tilesets API

    The Mapbox Tilesets API has several beta endpoints that allow you to create custom vector tilesets. You can use these endpoints as an alternative to the Uploads API for tiling vector data using custom configuration rules. While these endpoints are in beta, they are subject to potential changes.

    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 tileset 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?

    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.

    Beta support for creating tilesets

    The Mapbox Tilesets API endpoints for creating and interacting with tileset sources and tilesets are in public beta, and are subject to potential changes. The endpoints in public beta are:

    Tileset sources

    Tilesets

    Tileset recipes

    The Tilesets CLI

    Beta

    The Tilesets API endpoints used to create and interact with tileset sources and tilesets are generally accessed using the Tilesets CLI tool. This command-line tool allows you to prepare and upload data for the Tilesets API. These resources will help you learn more about the Tilesets CLI:

    The Tilesets API documentation is useful if you want to use the Tilesets API directly rather than using the Tilesets CLI (for example, if you want to integrate the Tilesets API into an application so that you can make vector tilesets programmatically).

    Creating new tilesets with the Tilesets API

    Beta

    The core workflow for creating and updating tilesets with the Tilesets API is:

    1. Create a tileset source for saving your raw geographic data at Mapbox.

      • For information on how to create a new tileset source using line-delimited GeoJSON, see the Create a tileset source endpoint.
    2. Write a recipe to configure and describe transformation options for converting your tileset sources into vector tiles.

      • For information on how to make sure a recipe document is formatted correctly, see the Validate a recipe endpoint.
    3. Create a new tileset with your recipe.

      • For information on how to use a recipe document to create a new tileset, see the Create a tileset endpoint.
    4. Publish your new tileset.

    These steps can be repeated indefinitely for the same tileset, depending on whether your source data has updated or your recipe requires changes.

    Line-delimited GeoJSON and the Tilesets API

    Beta

    The Tileset API requires that all data used to create a tileset source must be uncompressed line-delimited sequences of GeoJSON features. For example:

    {"type":"Feature","id":1,"geometry":{"type":"Point","coordinates":[115.7,12.2]},"properties":{"name":"cool feature"}}
    {"type":"Feature","id":2,"geometry":{"type":"Point","coordinates":[125.7,12.2]},"properties":{"name":"neat feature"}}
    

    To learn more about line-delimited GeoJSON and how it is used by the Tilesets API, see the Tileset API tileset sources guide.

    Create a tileset source

    Beta
    post
    /tilesets/v1/sources/{username}/{id}
    tilesets:write

    Creates a tileset source. A tileset source is raw geographic data formatted as line-delimited GeoJSON and uploaded to Mapbox.com. (Learn more about how line-delimited GeoJSON is used by the Tilesets API in the Tileset sources troubleshooting guide.)

    Tileset sources are necessary to use the Tilesets API to create a new vector tileset, and they are referenced via a tileset source ID. The same tileset source can be used across multiple tilesets.

    Required parametersDescription
    usernameThe Mapbox username of the account for which to create a tileset source.
    idThe ID for the tileset source to be created. Limited to 32 characters. The only allowed special characters are - and _.

    The request body must be line-delimited GeoJSON. For information about how to convert GeoJSON or other data formats to line-delimited GeoJSON, see the Tileset sources troubleshooting guide.

    Limits
    • Tileset sources can be composed of up to 10 source files.
    • The maximum combined total size of all files that compose a tileset source is 50 GB.

    Example request: Create a tileset source

    $ curl -F file=@/Users/username/data/mts/countries.geojson.ld \
      "https://api.mapbox.com/tilesets/v1/sources/{username}/hello-world?access_token=
    YOUR_MAPBOX_ACCESS_TOKEN
    "

    Response: Create a tileset source

    If the request is successful, the response will contain the following properties:

    PropertyDescription
    file_sizeThe size in bytes of the individual file you have added to your tileset source.
    filesThe total number of files in the tileset source.
    idThe unique identifier for the tileset source.
    source_sizeThe total size in bytes of all the files in the tileset source.
    Example response: Create a tileset source
    {
      "file_size": 10592,
      "files": 2,
      "id": "mapbox://tileset-source/username/hello-world",
      "source_size": 20884
    }
    

    Retrieve tileset source information

    Beta
    get
    /tilesets/v1/sources/{username}/{id}
    tilesets:read

    Get information for a specific tileset source, including the number and total size of the files in the tileset source.

    Required parametersDescription
    usernameThe Mapbox username of the account for which to retrieve tileset source information.
    idThe ID for the tileset source to be retrieved.

    Example request: Retrieve tileset source information

    $ curl "https://api.mapbox.com/tilesets/v1/sources/{username}/hello-world?access_token=
    YOUR_MAPBOX_ACCESS_TOKEN
    "

    Response: Retrieve tileset source information

    If the request is successful, the response will contain the following properties:

    PropertyDescription
    filesThe total number of files in the tileset source.
    idThe unique identifier for the tileset source.
    sizeThe total size in bytes of all files in the tileset source.
    size_niceThe total size of all files in the tileset source, in a human-readable format.
    Example response: Retrieve tileset source information
    {
      "files": 2,
      "id": "mapbox://tileset-source/username/hello-world",
      "size": 20884,
      "size_nice": "20.39KB"
    }
    

    List tileset sources

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

    List all the tileset sources that belong to an account.

    Required parametersDescription
    usernameThe Mapbox username of the account for which to retrieve tileset source information.

    Example request: List tileset sources

    $ curl "https://api.mapbox.com/tilesets/v1/sources/{username}?access_token=
    YOUR_MAPBOX_ACCESS_TOKEN
    "

    Response: List tileset sources

    If the request is successful, the response will be a list of the tileset sources that belong to the specified account.

    Example response: List tileset sources
    [
      {
        "files": 2,
        "id": "mapbox://tileset-source/username/hello-world",
        "size": 20884
      },
      {
        "files": 3,
        "id": "mapbox://tileset-source/username/hola-mundo",
        "size": 650332
      }
    ]
    

    Delete a tileset source

    Beta
    delete
    /tilesets/v1/sources/{username}/{id}
    tilesets:write

    Permanently delete a tileset source and all its files. This is not a recoverable action.

    Required parametersDescription
    usernameThe Mapbox username of the account for which to delete a tileset source.
    idThe ID for the tileset source to be deleted.

    Example request: Delete a tileset source

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

    Response: Delete a tileset source

    If the tileset source is successfully deleted, the response will be HTTP 201.

    Create a tileset

    Beta
    post
    /tilesets/v1/{tileset}
    tilesets:write

    Create a new tileset. This request requires you to write a recipe that defines how to transform the data in a tileset source into vector tiles.

    For guidance on how to format a recipe, see the Recipe reference. For a list of common recipe use-cases, see the Recipe examples guide.

    Required parametersDescription
    tilesetThe ID for the tileset to be created or replaced, which is composed of your username followed by a period and the tileset's unique name (username.tileset_name). Limited to 32 characters. This character limit does not include your username. The only allowed special characters are - and _.

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

    Required request body propertyDescription
    recipeA recipe that describes how the GeoJSON data you uploaded should be transformed into tiles. For more information on how to create and format recipes, see the Recipe reference and Recipe examples.
    nameThe name of the tileset. Limited to 64 characters.

    Additionally, the request body may contain the following optional properties:

    Optional request body propertiesDescription
    privateA boolean that describes whether your tileset is accessible to other Mapbox users and access tokens. Default is false.
    Private tilesets are only available for Enterprise customers.
    descriptionA description of the tileset. Limited to 500 characters.

    Example request: Create a tileset

    $ curl -X POST "https://api.mapbox.com/tilesets/v1/{tileset}?access_token=
    YOUR_MAPBOX_ACCESS_TOKEN
    "
    \ -d @tileset-recipe.json \ --header "Content-Type:application/json"

    Example request body: Create a tileset

    {"recipe":
      {
        "version": 1,
        "layers": {
          "hello_world": {
            "source": "mapbox://tileset-source/username/hello-world",
            "minzoom": 0,
            "maxzoom": 5
          }
        }
      },
      "name": "Hello World"
    }
    

    Response: Create a tileset

    {
      "message": "Successfully created <tileset_id>"
    }
    

    If a tileset with the specified ID already exists, the Tilesets API will return an HTTP 400 status code.

    Publish a tileset

    Beta
    post
    /tilesets/v1/{tileset}/publish
    tilesets:write

    Once you’ve created a tileset, you can request that the data be "published" into vector tiles. This action will start an asynchronous process known as a job that retrieves your data and processes it into vector tiles according to the recipe you have defined.

    This endpoint can also be used to update an existing tileset. Note that a given tileset can only have one active processing publish job at a time. This ensures the data you have staged is processed before any future data you have staged is processed. If your tileset has an active publish request being processed, all later publish requests will be queued to run in the order they were received. You can only have five jobs in the queue per account.

    Note that while a tileset is publishing, inconsistencies are possible for tile reads. While a job is in progress, certain tiles will be updated first while others will be updated later in the process. For the most consistent results, try processing smaller amounts of data more often.

    All jobs are entered into a global Mapbox queue. The larger the queue, the longer it will take your tileset to process. For instructions on how to see the size of the queue, see the View the Tilesets API global queue section.

    Required parametersDescription
    tilesetThe ID of the tileset to be published, which is composed of your username followed by a period and the tileset's unique name (username.tileset_name).
    Limits
    • Publish requests per minute: 30.
    • Size of a single vector tile: 500 KB.

      • If a job drops features due to tile size, this will be noted in the warnings field of the job object.

    Example request: Publish a tileset

    $ curl -X POST "https://api.mapbox.com/tilesets/v1/{tileset}/publish?access_token=
    YOUR_MAPBOX_ACCESS_TOKEN
    "

    Response: Publish a tileset

    {
      "message": "Processing <tileset_id>",  
      "job_id": "<job_id>"
    }
    

    If your recipe references a non-existent tileset source, the Tilesets API will return an HTTP 400 status code.

    Update a tileset

    Beta

    An existing tileset's recipe, source, and tiles can all be updated using the Tilesets API:

    It is not possible to update a tileset’s name or description properties.

    Retrieve the status of a tileset

    Beta
    get
    /tilesets/v1/{tileset}/status
    tilesets:read

    Check whether a tileset has any queued or processing publish commands.

    Note that while a tileset is publishing, inconsistencies are possible for tile reads. While a job is in progress, certain tiles will be updated first while others will be updated later in the process. For the most consistent results, try processing smaller amounts of data more often.

    Required parametersDescription
    tilesetThe ID for the tileset for which to retrieve the status, which is composed of your username followed by a period and the tileset's unique name (username.tileset_name).

    Example request: Retrieve the status of a tileset

    $ curl "https://api.mapbox.com/tilesets/v1/{tileset}/status?access_token=
    YOUR_MAPBOX_ACCESS_TOKEN
    "

    Response: Retrieve the status of a tileset

    The JSON response will include the following properties:

    PropertyDescription
    queuedThe number of upcoming publish commands that have been prepared for this tileset. The value for this field will be 0 if the tileset has no active publish commands. Note that the maximum number of queued jobs per account is 5.
    processingThe value for this field will be 1 if the job has any active publish commands, or 0 if the tileset has no active publish commands.
    successThe number of jobs that have been successfully published for this tileset.
    failedThe number of jobs that have failed to publish for this tileset.
    last_completed_jobThe ID of the last job to generate the tileset.
    idThe tileset's unique identifier.
    Example response: Retrieve the status of a tileset
    {
      "queued": 2,
      "processing": 1,
      "success": 9,
      "failed": 9,
      "last_completed_job": "your_unique_hash",
      "id": "username.id"
    }
    

    Retrieve a single tileset job

    Beta
    get
    /tilesets/v1/{tileset}/jobs/{job_id}
    tilesets:read

    Retrieve a single job associated with a tileset based on its unique job ID.

    Required parametersDescription
    tilesetThe ID for the tileset for which to retrieve the status, which is composed of your username followed by a period and the tileset's unique name (username.tileset_name).
    job_idThe publish job's unique identifier. This identifier is returned in the job_id field of a Publish a tileset response.

    Example request: Retrieve a single tileset job

    $ curl "https://api.mapbox.com/tilesets/v1/{tileset}/jobs/{job_id}?access_token=
    YOUR_MAPBOX_ACCESS_TOKEN
    "

    Response: Retrieve a single tileset job

    A successful request will return a JSON response that contains the following properties:

    PropertyDescription
    idThe publish job's unique identifier.
    stageThe status of the job. Possible values are queued, processing, success, or failed.
    createdTimestamp indicating when the job was created.
    created_niceHuman-readable timestamp indicating when the job was created.
    publishedTimestamp indicating when the job was published.
    tilesetIdThe specified tileset's unique identifier.
    Example response: Retrieve a single tileset job
    {
      "id":"unique_hash",
      "stage":"success",
      "created":1560981902377,
      "created_nice":"Wed Jun 19 2019 22:05:02 GMT+0000 (UTC)",
      "published": 1560982158721,
      "tilesetId": "user.id"
    }
    

    List all jobs for a tileset

    Beta
    get
    /tilesets/v1/{tileset}/jobs
    tilesets:list

    Check all jobs associated with a tileset. You can also query jobs with a particular stage: processing, queued, success, or failed.

    Required parameterDescription
    tilesetThe ID for the tileset for which to list all jobs, which is composed of your username followed by a period and the tileset's unique name (username.tileset_name).

    You can further refine the results from this endpoint with the optional stage parameter:

    Optional parameterDescription
    stageQuery for jobs at a particular stage: processing, queued, success, or failed.

    Example request: List all jobs for a tileset

    # Request all associated jobs
    $ curl "https://api.mapbox.com/tilesets/v1/{tileset}/jobs?access_token=
    YOUR_MAPBOX_ACCESS_TOKEN
    "
    # Request only associated jobs at the success stage $ curl "https://api.mapbox.com/tilesets/v1/{tileset}/jobs?stage=success&access_token=
    YOUR_MAPBOX_ACCESS_TOKEN
    "

    Response: List all jobs for a tileset

    A successful request returns one or more JSON objects that describe a tileset's jobs. Each object will contain the following properties:

    PropertyDescription
    idThe publish job's unique identifier.
    stageThe status of the job. Possible values are queued, processing, success, or failed.
    createdTimestamp indicating when the job was created.
    created_niceHuman-readable timestamp indicating when the job was created.
    publishedTimestamp indicating when the job was published.
    tilesetIdThe specified tileset's unique identifier.
    Example response: List all jobs for a tileset
    [  
      {
        "id": "job_1_id",
        "stage": "success",
        "created": 1560981902377,
        "created_nice": "Wed Jun 19 2019 22:05:02 GMT+0000 (UTC)",
        "published": 1560982158721,
        "tilesetId": "user.id"
      },
      {
        "id": "job_2_id",
        "stage":"processing",
        "created":1560982159327,
        "created_nice":"Wed Jun 19 2019 22:09:19 GMT+0000 (UTC)",
        "published": 1560985238565,
        "tilesetId": "user.id"
      }
    ]
    

    View the Tilesets API global queue

    Beta
    put
    /tilesets/v1/queue
    tilesets:read

    View the number of queued jobs in the global Tilesets API queue, which shows the number of jobs waiting to be processed.

    Example request: View the Tilesets API global queue

    $ curl "https://api.mapbox.com/tilesets/v1/queue?access_token=
    YOUR_MAPBOX_ACCESS_TOKEN
    "

    Response: View the Tilesets API global queue

    A request to this endpoint returns the number of jobs waiting to be processed in the global Mapbox Tilesets API queue.

    PropertyDescription
    totalThe number of queued jobs.
    Example response: View the Tilesets API global queue
    {
      "total": 42
    }
    

    Validate a recipe

    Beta
    put
    /tilesets/v1/validateRecipe
    tilesets:write

    Validate a recipe document before using it to create a new tileset. The entire request body must be the recipe JSON document. For guidance on how to format a recipe, see the Recipe reference.

    Example request: Validate a recipe

    $ curl -X PUT "https://api.mapbox.com/tilesets/v1/validateRecipe?access_token=
    YOUR_MAPBOX_ACCESS_TOKEN
    "
    \ -d @recipe.json \ --header "Content-Type:application/json"

    Response: Validate a recipe

    The response will be a JSON object that tells you whether the recipe document is valid or not. If the recipe document is not valid, the errors property will contain an informational message about the issue.

    Example response: Validate a recipe

    Valid recipe:

    {
        "valid": true
    }
    

    Recipe not valid:

    {
        "valid": false,
        "errors": [
            "minzoom 22 cannot be larger than maxzoom 11"
        ]
    }
    

    Retrieve a tileset's recipe

    Beta
    get
    /tilesets/v1/{tileset}/recipe
    tilesets:list

    Request the recipe body that you used when you created a specific tileset.

    Required parameterDescription
    tilesetThe ID for the tileset for which to retrieve the recipe, which is composed of your username followed by a period and the tileset's unique name (username.tileset_name).

    Example request: Retrieve a tileset's recipe

    $ curl "https://api.mapbox.com/tilesets/v1/{tileset}/recipe?access_token=
    YOUR_MAPBOX_ACCESS_TOKEN
    "

    Response: Retrieve a tileset's recipe

    Returns the recipe body you provided when you originally created the specified tileset.

    Example response: Retrieve a tileset's recipe
    {
      "recipe": {
        "version": 1,
        "layers": {
          "my_layer": {
            "source": "mapbox://tileset-source/my-source-data",
            "minzoom": 0,
            "maxzoom": 4
          }
        }
      },
      "id": "username.id"
    }
    

    Update a tileset's recipe

    Beta
    patch
    /tilesets/v1/{tileset}/recipe
    tilesets:write

    Update a tileset’s recipe. This endpoint performs a validation step on the new recipe.

    Required parameterDescription
    tilesetThe ID for the tileset for which you are updating the recipe, which is composed of your username followed by a period and the tileset's unique name.

    The entire request body must be the recipe JSON document.

    Updates to the layer name

    Updating the layer_name of your recipe will break any downstream styles that reference this tileset. If a style references this tileset and you change the layer_name, you must update your style by deleting the relevant layer and re-adding the tileset’s new layer.

    Example request: Update a tileset's recipe

    $ curl -X PATCH "https://api.mapbox.com/tilesets/v1/{tileset}/recipe?access_token=
    YOUR_MAPBOX_ACCESS_TOKEN
    "
    \ -d @recipe.json \ --header "Content-Type:application/json"

    Response: Update a tileset's recipe

    If the updated recipe is valid, the response will have a status of HTTP 201 with no response body.

    If the updated recipe is not valid, the errors property will contain an informational message about the issue:

    {
        "Message": "Recipe is invalid.",
        "errors": [
            "minzoom 22 cannot be larger than maxzoom 11"
        ]
    }
    

    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.tileset_id}
    tilesets:write

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

    Required parameterDescription
    username.tileset_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.tileset_id}?access_token=
    YOUR_MAPBOX_ACCESS_TOKEN
    "

    Response: Delete tileset

    HTTP 204
    

    Retrieve TileJSON metadata

    get
    /v4/{tileset_id}.json

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

    Required parametersDescription
    tileset_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

    • You must make requests over HTTPS. HTTP is not supported.
    Tilesets API endpointRequests per minute
    List tilesets50
    Delete tileset50
    Retrieve TileJSON metadata100,000
    Create a tileset source
    Beta
    30
    Create a tileset
    Beta
    30
    Publish a tileset
    Beta
    30
    Retrieve tileset source information
    Beta
    50
    Retrieve a tileset's recipe
    Beta
    50
    Update a tileset's recipe
    Beta
    30

    If you require higher rate limits, 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?

    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?