Introduction

The Mapbox web services? APIs allow for programmatic access to Mapbox tools and services. Use these APIs to retrieve information about your account, upload and change resources, and use core Mapbox tools, like geocoding and directions.

This documentation provides examples of six different techniques for accessing Mapbox web services APIs:

• cURL
• Mapbox CLI
• Mapbox JavaScript SDK
• Mapbox Python SDK
• Mapbox Java

• Mapbox Swift/Objective-C libraries:

  • MapboxGeocoder.swift
  • MapboxDirections.swift
  • MapboxStatic.swift

Each library’s documentation provides information on installing the library and how to use it.

This is REST API documentation: it’s the most technical level of documentation for Mapbox’s web services. If you're looking to use a map in an application, you probably want to use a library like Mapbox GL JS or Mapbox Mobile instead. The APIs described in this document are subject to Mapbox's Terms of Service.

Reading this Documentation

This documentation is structured by API, which is a group of related functionality like Geocoding or Uploads, and then by endpoint, which is a specific method within that API that performs one action and is located at a specific URL.

Each endpoint in this documentation is described using several parts:

• The HTTP method: includes GET, POST, PUT, PATCH, DELETE
• The path: for instance, /geocoding/v5/{mode}/{query}.json
• URL parameters: these are the parts of the endpoint path wrapped in brackets, like {mode} in this example.
• Query parameters: contained in a table with an Option header, these are added to the query string part of the request.
• A token scope, if one is required.

All URLs referenced in the documentation have the base path https://api.mapbox.com. This base path goes before the endpoint path. In this example, you'd combine https://api.mapbox.com and /geocoding/v5/{mode}/{query}.json to get the request URL https://api.mapbox.com/geocoding/v5/{mode}/{query}.json.

For this endpoint, {mode} and {query} are the URL parameters. In a request, you replace their placeholders with real values: for instance, you'd choose mapbox.places as your mode and Chester as your query, and get the URL https://api.mapbox.com/geocoding/v5/mapbox.places/Chester.json

Query parameters are added to the end of the URL with query string encoding. If you wanted to add the country query parameter to that Geocoding request, you'd the query string ?country=us to the end of the URL, producing https://api.mapbox.com/geocoding/v5/mapbox.places/Chester.json?country=us.

All endpoints require an access token?, which is provided as a query parameter. So the final geocoding request you would construct would look like https://api.mapbox.com/geocoding/v5/mapbox.places/Chester.json?country=us&access_token=pk.my-token-value The next section covers how you get and use access tokens.

Access tokens

Access to Mapbox web services? requires an access token that connects API requests to your account. The example requests in this documentation don't include an access token?: you will need to supply one using the access_token query option or by specifying the token in the SDK? or library.

Your default access token is available on the right side of your Mapbox Studio home page. You can also manage and create additional tokens on your API access tokens page in Mapbox Studio? or with the Tokens API.

When creating a new access token, you have the option of adding one or more scopes. Each scope adds a different permission to the token, allowing it to be used to access restricted APIs. Throughout the documentation, we specify the scope required to access each endpoint.

Versioning

Each Mapbox API is versioned with a version string specified in the base URL that can be incremented independently from other APIs.

The Maps API and Directions API are the exceptions: their endpoints are prefixed with /v4/{map_id} and /v4/directions instead of putting the version after the API name. This mismatch will be fixed in the next API version.

Using the newest available API is always encouraged.

These changes are considered backwards compatible and will not require the version string to be incremented:

• Adding properties to JSON objects.
• Changing the number of items returned in a single listing request.
• Changing rate limiting thresholds.
• The structure or length of identifiers generated by the API.
• Changing error messages.

These changes are considered backwards incompatible and will require the version string to be incremented:

• Removing properties from JSON objects.
• Changing an API's URL structure

In the event that certain functionality is deprecated, we will give at least 90 days notice via email. You will only receive a deprecation email if we detect you are using part of the API that is being deprecated.

Rate limits

Mapbox APIs have rate limits that cap the number of requests that can be made against an endpoint. If you exceed a rate limit, your request will be throttled and you will receive HTTP 429 Too Many Requests responses from the API.

CORS

Mapbox web services? support Cross-Origin Requests with no domain restrictions. To support Internet Explorer 8 and 9, use a library that falls back to XDomainRequest, like corslite.

Retina

Mapbox supports Retina image output on all APIs that serve images. Add @2x before the file extension on a URL to request an image at double scale. For instance, a map tile that is 256×256 pixels will be 512×512 pixels with @2x, but show the same content. When displayed on a page, the image will be still sized to 256×256 pixels, but 4 pixels of the original will represent 1 pixel in screen units.

The @2x part of the URL goes before the entire format, so a URL that ends in .png would end with @2x.png as a Retina image.

The only assets that are not available at Retina scale are tilesets uploaded from TileMill? or as MBTiles?.

HTTPS

We recommend all access to Mapbox is over HTTPS. Except for the Maps API, requests initiated over HTTP are automatically upgraded to HTTPS.

Pagination

Pagination lets you list many objects from an API by using more than one request. After receiving a page of objects, the next page can be requested using the next link relation in Link header of the response. This process can be repeated until the server sends a response without a Link header or without a next link relation, which signals the end of the collection.

Your application must use the Link header for pagination instead of constructing your own URLs as the specific URLs used for pagination may change at any time. The Python requests library, and the link-header-parser module for JavaScript can parse Link headers. Link headers follow the RFC 5988 specifications.

Pagination is supported on the Datasets, Uploads, Styles, and Tokens list endpoints.

Dates

Most dates and times returned by the API are represented in RFC 3339 format, which can be parsed by the JavaScript Date constructor, the Python arrow library, and many other libraries and languages.

The only exception to this rule is the Retrieve TileJSON metadata endpoint that returns created and modified properties as Unix time.

Coordinates

Where geographic coordinates are provided to a Mapbox API, they should be formatted in the order longitude, latitude and specified as decimal degrees in the WGS84 coordinate system. This pattern matches existing standards, including GeoJSON? and KML?.

Mapbox APIs use GeoJSON formatting wherever possible to represent geospatial data. The Directions, Map Matching, Geocoding, and Datasets APIs all return GeoJSON-formatted responses, and the Upload and Map Matching APIs accept GeoJSON input.

The only exception to longitude, latitude ordering is the polyline format, supported in Static (Classic) overlays and Directions responses. When polyline input or output is specified, the polyline content should follow the Google Encoded Polyline format, which specifies latitude, longitude ordering.

The Mapbox Swift libraries use the Core Location framework’s CLLocationCoordinate2D type to represent geographic coordinates. When initializing a CLLocationCoordinate2D, always specify the latitude before the longitude.

Uploads

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

The upload workflow begins with a file and ends with a tileset?, or if you have invalid data, an error.

1. Retrieve S3 credentials to stage the file
2. Use an S3 client, like the AWS SDK, to upload a file to S3 using those credentials
3. Create an upload using the staged file's URL
4. Retrieve the upload's status as it is processed into a tileset
5. Once the upload is complete, use the tileset ID like you'd use any other tileset

Limits

Uploading Mapbox Datasets is only available to users who are part of the Mapbox Dataset beta.

Retrieve S3 credentials

Mapbox provides an Amazon S3 bucket to stage your file while your upload is processed. Uploads must be staged in this bucket before being uploaded to your Mapbox account. You can retrieve temporary credentials from this endpoint.

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

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.

Create an upload

Once you've used the temporary S3 credentials to transfer your file to Mapbox's staging bucket, you can trigger the generation of a tileset? given the file's URL and a destination tileset ID.

Uploads can only be use files in Mapbox's provided buckets, they cannot request resources from other S3 buckets or URLs.

The request body is a JSON object containing the following properties.

Reuse of a tileset value will replace existing data: use a random value to make sure that a new tileset is created, or check existing tilesets first.

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

Retrieve upload status

Upload processing is fast but not immediate. Once an upload is created, you can track its status. Uploads have a progress property that will 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.

Retrieve recent upload statuses

You can retrieve multiple upload statuses at the same time, sorted by the most recently created. This request returns the same information as individual upload status, but for all recent uploads. The list is limited to 1MB of JSON.

This endpoint supports pagination so that you can list many uploads. Up to 100 items can be requested at a time using the limit parameter. It also supports another parameter, reverse:

Remove an upload

Remove a completed upload status from the upload listing.

Uploads are only statuses: removing an upload from the listing doesn't delete the associated tileset?. Tilesets can only be deleted from within Mapbox Studio?. An upload cannot be removed until it is completed.

Styles

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

If you use Studio, Mapbox GL JS or the Mapbox Mobile SDKs, you're already using the Styles API. This documentation is geared toward software developers who want to programmatically read & write these resources: it isn't necessary to read or understand this reference to design or use maps.

You'll want to be familiar with the Mapbox GL Style Spec to use this API: it defines the structure of map styles and is the open standard that helps Studio communicate with APIs and produce maps compatible with our libraries (like GL JS and Mobile). When we refer to style objects, they are objects that fit the Mapbox GL? Style Spec. You can see examples of these styles in our mapbox-gl-styles project, or you can create a new style? using Mapbox Studio.

Limits

• Styles cannot reference more than 15 sources.
• Styles cannot be larger than 5MB. This limit only applies to the style document itself, not the sprites, fonts, tilesets, or other resources it references.
• The number of styles allowed per account varies based on plan level.

Mapbox styles

The following styles are available to all accounts using a valid access token?:

• mapbox://styles/mapbox/streets-v9
• mapbox://styles/mapbox/outdoors-v9
• mapbox://styles/mapbox/light-v9
• mapbox://styles/mapbox/dark-v9
• mapbox://styles/mapbox/satellite-v9
• mapbox://styles/mapbox/satellite-streets-v9

The style object

The style object conforms to the Mapbox GL Style Specification, with these additional account-related properties:

Retrieve a style

Retrieve a style? as a JSON document. The returned style object will be in the Mapbox GL Style Spec format.

List styles

Retrieve a list of styles for an account. This endpoint does not return full styles, but returns style? metadata.

Create a style

Creates a style? in your account. The posted style object must be both valid JSON and aligned to the Mapbox GL Style Spec: invalid styles will produce a descriptive validation error.

Only the most recent version of the Mapbox GL? Style Spec is supported. If the optional "name" property is omitted, it will be automatically set to the style's ID.

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

Update a style

Updates an existing style? in your account with new content.

Requesting a style and then using the same content to update the style will fail: you'll need to remove the created and modified properties before updating a style. The name property, which is optional for style creation, is required when updating a style. Cross-version PATCH requests are rejected.

Delete a style

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

Fonts

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

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

Font limits

• Fonts must be smaller than 30MB.
• Accounts are limited to 100 fonts.

Retrieve font glyph ranges

Glyph ranges are usually not of interest unless you're building a map renderer, but this is the endpoint where you can 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.

Sprites

Sprites are the way that Mapbox GL JS? and Mapbox Mobile efficiently request and show icons. They are collections of icons that can be used in styles as markers or patterns in symbol layers. Icons are SVG? images that can be added and removed 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 icon is positioned.

The sprite? JSON document is specified as part of the the Mapbox GL Style Spec.

Sprites are managed on a per-style basis: each sprite belongs to a style, so the sprite limit of 100 icons is also a per-style limit. All sprite-related API methods will require a {style_id} parameter referring to the style? that sprite belongs to.

Sprite limits

• Each icon must be smaller than 400kB.
• Mapbox supports most, but not all SVG properties. Our SVG troubleshooting document describes these limits.
• Icons can be up to 512px in each dimension.
• Sprites can contain up to 100 icons.

Retrieve a sprite image or JSON

Retrieves a sprite? image or JSON document.

Add new icon to sprite

Adds a new icon to an existing sprite?.

The request body should be raw SVG? data.

Delete icon from sprite

Deletes an icon from an existing sprite?.

Embed a style

Request embeddable HTML suitable for fullscreen map displays or for inserting into blog posts and articles as <iframe> content.

Maps

The Mapbox Maps API supports reading raster tilesets, vector tilesets, and Mapbox Editor? project features. Tilesets can be retrieved as images, TileJSON, or HTML slippy maps for embedding. Mapbox Editor project features can be retrieved as GeoJSON? or KML?.

If you use Mapbox.js, Mapbox GL JS, or another library like Leaflet, you're already using this API. This documentation is geared toward software developers who want to programmatically read these resources: it isn't necessary to read or understand this reference to design or use maps.

Mapbox classic map IDs

The following map IDs are accessible to all accounts using a valid access token?:

• mapbox.streets
• mapbox.light
• mapbox.dark
• mapbox.satellite
• mapbox.streets-satellite
• mapbox.wheatpaste
• mapbox.streets-basic
• mapbox.comic
• mapbox.outdoors
• mapbox.run-bike-hike
• mapbox.pencil
• mapbox.pirates
• mapbox.emerald
• mapbox.high-contrast

Retrieve tiles

Returns a image tile, vector tile, or UTFGrid in the specified format.

The {z}/{x}/{y} parameters are the tile coordinates as described in the Slippy Map Tilenames specification: they specify the tile's zoom level {z} and column {x} and row {y}.

The format of any image request can be replaced by any of the following 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.

You can prefix the format with @2x to request a high DPI version. The @2x is placed after the {z}/{x}/{y} and before the ., like 1/0/[email protected]

Tiles that include mapbox.satellite are always delivered as JPEG, even if the URL specifies PNG. The PNG format can't efficiently encode photographic images like mapbox.satellite.

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

Style-optimized vector tiles

Vector tiles? can be further optimized by including a style ID with the tile request. If the style parameter is provided, we analyze the sources, filters, minzoom, and maxzoom properties of that style? and remove data from the vector tile that won't be visible on the map.

A style-optimized tile request requires a style parameter in the request. This style parameter is broken into two parts, the style ID and the style's recently edited timestamp. The timestamp parameter comes from the style JSON's modified property that is included with any style created with Mapbox Studio?.

Mapbox GL JS? can request style-optimized vector tiles that are hosted on Mapbox with a Mapbox Style JSON.

Optimized tiles remove unused layers and features. If you plan on dynamically modifying the style at runtime using Mapbox GL JS or Mapbox Mobile, broadening filters and zoom ranges won't work the same, since any data that isn't visible with the loaded style also won't be included in the data.

Retrieve an HTML slippy map

Returns an HTML slippy map for sharing or embedding.

The response is HTML of a slippy map.

Retrieve features from Mapbox Editor projects

Retrieve vector features from Mapbox Editor? projects as GeoJSON? or KML?. GeoJSON returns a FeatureCollection with features that conform to the simplestyle-spec.

Retrieve features from vector tiles

Retrieve data about specific vector features at a specified location within a vector tileset?. The response body is a GeoJSON? FeatureCollection of features at or near the geographic point described by {lon},{lat} and within the distance described by the radius parameter. The geometry of the feature is not returned.

The radius parameter has no upper bound and is 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.

Restrictions and limits

Use of this endpoint is rate limited to 600 requests per minute. For a higher rate limit, contact us.

Exceeding the limits above will result in an HTTP 429 response. For information on rate limit headers, see Rate limits.

The original geometry of the result features will not be returned in the resultset. The geometry type in the response will be Point for all features returned in the FeatureCollection:

• For Polygon and MultiPolygon features the geometry is the point at the queried lon,lat
• For LineString and MultiLineString features the geometry is the nearest point on the feature within the radius threshold of lon,lat
• For Point and MultiPoint features the geometry is the nearest point within the radius threshold of lon,lat

Features in the response body will include a tilequery object with the following additional properties:

Retrieve TileJSON metadata

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

Static

The Mapbox Static API returns static maps and raster tiles from styles in the Mapbox GL Style Spec.

Static maps are standalone images that can be displayed on web and mobile devices without the aid of a mapping library or API. They look like an embedded map without interactivity or controls.

Raster tiles can be used in traditional web mapping libraries like Mapbox.js, Leaflet, OpenLayers, and others.

Retrieve a static map from a style

In contrast to the legacy Static API, this API supports pitch, bearing, and decimal zoom levels.

The position of the map is represented by 5 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.

The attribution option removes watermarked attribution from the image, but not the 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.

Tiles and static images returned from this API will be one zoom level offset from tiles and static images returned from the Static (Classic) API. This is due to the size of the individual tiles being created -- this API creates 512px by 512px tiles and the Static Classic API creates 256px by 256px tiles. The offset was introduced to keep zoom level 0 the lowest zoom (one tile for the whole world).

Example: the tile at zoom level 0 from this API covers 512px by 512px. This is the same pixel area as zoom level 1 in the Static (Classic) API, where there are 4 tiles to fill the same space. The features shown in zoom level 0 of the Static API are matched identically to the features shown in zoom level 1 of the Static (Classic) API.

Retrieve raster tiles from styles

Request 256x256 or 512x512 image tiles from a style? that can be arranged and displayed with the help of a mapping library. Normally, you will not need to interact with this API directly, as our SDKs handle this for you.

Mapbox.js? has built-in support for raster tiles from a style with L.mapbox.styleLayer.

256px vs 512px tiles

By default, the API will return 512x512 pixel image tiles. 512x512 image tiles will be offset by 1 zoom level when compared to traditional 256x256 tiles (for example, 512x512 tiles at zoom level 4 are equivalent to traditional tiles at zoom level 5). Tiles are 512x512 pixels unless the @2x parameter is included, in which case they're scaled to 1024x1024 pixels.

If you are using Leaflet? directly, the following options will need to included in the options argument to the L.tileLayer constructor:

{ tileSize: 512, zoomOffset: -1 }

Retrieve a map's WMTS document

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

Static (Classic)

The classic Mapbox Static API lets you request static maps from tilesets, with the option to add vector data as overlays. Static maps are standalone images that can be displayed on web and mobile devices without the aid of a mapping library or API. They look like an embedded map without any interactivity or controls.

If you've uploaded data to Mapbox, you've already seen the classic Static API in action, powering the images at the top of all tileset? detail pages.

Swift and Objective-C support for the classic Static API is provided by the MapboxStatic.swift library.

Limits

• The maximum size for a static map image is 1280x1280 pixels.
• The URL for a request to this API cannot be longer than 4096 characters.
• Overlays cannot consist of more than 100 features.
• Markers must be fewer than 160,000 pixels square (width multiplied by height).
• Static map images give you design flexibility in how you want to display map attribution. When using Static maps it is your responsibility to add proper attribution for maps in your website or application.

Retrieve a static map image

The support formats are the same as for the Mapbox Maps API:

The {overlay} parameter can specify one or more features to draw on top of the map. The list of features should be comma-separated. Each overlay feature can be in one of three formats: marker, geojson or path.

Marker

{name}-{label}+{color}({lon},{lat})

Custom marker

url-{url}({lon},{lat})

Custom markers are cached according to the Expires and Cache-Control headers. Make sure that at least one of these headers is set to an proper value to prevent repeated requests for the custom marker image.

The marker image is always centered on the specified location. When creating an asymmetric marker like a pin, make sure that the tip of the pin is at the center of the image.

GeoJSON

geojson({geojson})

The {geojson} argument must be a valid GeoJSON object. simplestyle-spec styles for GeoJSON? features will be respected and rendered.

GeoJSON features will be respected and rendered.

Path

path-{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.

Retrieve a standalone marker

Request a single marker image without any background map.

Datasets

A dataset is an editable collection of GeoJSON features. The Datasets API offers persistent storage for custom geographic data and supports reading, creating, updating, and removing features.

Using the Datasets API involves interacting with two types of resources: datasets and features. Datasets contain a collection of features.

The dataset object

A dataset contains information about the dataset. Each dataset contains the following properties:

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.

Limits

• Each feature cannot exceed 1023KB compressed. Features are compressed server side using geobuf.
• The Dataset API is limited by per dataset id. Each dataset can receive 40 writes and 8 reads per second.

List datasets

Lists all datasets for a particular account.

Create dataset

Creates a new, empty dataset.

Retrieve a dataset

Returns a single dataset.

Retrieve information about an existing dataset.

Update a dataset

Updates the properties of a particular dataset.

Delete a dataset

Deletes a dataset, including all features it contains.

List features

List features in a dataset. The response body will be a GeoJSON? FeatureCollection.

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

Insert or update a feature

Inserts or updates a feature in a dataset. If there's already a feature with the given ID in the dataset, it will be replaced. If there isn't a feature with that ID, a new feature is created.

If you are inserting a feature, you must add the feature as the body of the PUT request. This should be one individual GeoJSON? feature and 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.

Retrieve a feature

Retrieves a feature in a dataset.

Delete a feature

Removes a feature from a dataset.

Tokens

An access token, referred to hereafter as 'token', grants access to Mapbox resources on behalf of a user. All accounts have a public token by default. Additional tokens can be created to grant additional, or more limited, privileges.

To create additional tokens using this API you will first need to create an initial token. This initial token must contain the tokens:write scope and all scopes you want to add to the created token. To create the initial token visit your Mapbox Studio API access tokens page, and click Create a new token.

The token format

Mapbox uses JSON Web Tokens (JWT) as the token format. Each token is a string delimited by dots into three parts: header, payload, and signature.

The header is a literal value of either pk (public token), sk (secret token), or tk (temporary token).

The payload is a base64-encoded JSON object containing the identity and authorities of the token. pk and sk tokens contain a reference to an authorization which holds the rights granted for the token. tk tokens contain the content of the authorization directly in the payload.

The signature is signed by Mapbox and used to verify the token has not been tampered with.

The actions allowed by a token are based on scopes. A scope is a string that often is a resource type and action separated by a colon. For example, the styles:read scope allows read access to styles. Tokens will have access to different scopes depending on their account level and other features of their account.

The authorization object

An authorization contains information about the capabilities of a token. Each authorization contains the following properties:

Limits

• Requests must be made over HTTPS. HTTP is not supported.
• The Tokens API is limited to 120 requests per minute per account.

List tokens

Lists all tokens for an account.

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

Note: The token property will not be included for sk tokens.

Create token

Creates a new token.

Every requested scope must be present in the access token? used to allow the request. It is not possible to create a token with access to more scopes than the token that created it.

The scopes included in the token decide whether the token is public or secret. A public token may only contains public scopes.

Create temporary token

Creates a new temporary token that automatically expires at a fixed time.

The expires property for a temporary token cannot be in the past or more than 1 hour in the future. If the authorizing token is temporary, the expires cannot be later than that of the authorizing token.

Every requested scope must be present in the authorizing token used to allow the request. It is not possible to create a token with access to more scopes than the token that created it.

Unlike public and secret tokens, a temporary token contains the authorization inside the payload of the token instead of referencing an authorization persisted on the server. Temporary tokens cannot be updated or revoked after they are created.

Update a token's authorization

Update the authorization's note or scopes.

A public, pk, token may only be updated to include other public scopes. A secret, sk, token may be updated to contain public and secret scopes.

When updating scopes for an existing token, the token sent along with the request must also have the scopes you're requesting. It is not possible to create a token with access to more scopes than the token that updated it.

Delete an authorization

Revoke an authorization, removing access to Mapbox APIs. This is the same as deleting a token. Applications using the revoked token will need to get a new access token? before they can access Mapbox APIs.

Note: Cached resources may continue to be accessible for a short period after a token is revoked. No new or updated resources will be accessible with the revoked token.

Retrieve a token

Check if a token is valid. If the token is invalid an explanation of why is returned as the code property.

The body of the token is parsed and included as the token property in object form.

List scopes

List scopes for a user. All potential scopes a user has access to are listed.

Public tokens may only contain scopes with the public property set to true. Secret tokens may contain any scope.

Directions

This documentation is for the v5 API. See the documentation for the legacy v4 API.

The Mapbox Directions API will show you how to get where you're going. With the Directions API, you can:

• calculate optimal driving, walking, and cycling routes
• produce turn-by-turn instructions
• produce routes with up to 25 coordinates anywhere on earth

This API supports three different routing profiles:

• mapbox/driving for car and motorcycle routing. This profile shows the fastest routes by preferring high-speed roads, like highways.
• mapbox/walking for pedestrian and hiking routing. This profile shows the shortest path by using sidewalks and trails.
• mapbox/cycling for bicycle routing. This profile shows routes that are short and safer for cyclists by avoiding highways and preferring streets with bike lanes.

Swift and Objective-C support for Directions is provided by the MapboxDirections.swift library.

Restrictions and limits

• Directions requests must specify at least two waypoints as starting & ending points, and can specify up to 25 total waypoints along the route.

Retrieve directions

Try this in API Playground

The response may be altered with optional query parameters:

Unrecognized options in the query string result in an InvalidInput error.

• code: String indicating the state of the response. This is a separate code than the HTTP status code. On normal valid responses, the value will be Ok.
• waypoints: Array of waypoint objects. Each waypoints is an input coordinate snapped to the road and path network. The waypoints appear in the array in the order of the input coordinates.
• routes: Array of route objects ordered by descending recommendation rank. May contain at most two routes.

Waypoint object

An input coordinate snapped to the roads network.

• name: String with the name of the way the coordinate snapped to
• location: Array of [ longitude, latitude ] for the snapped coordinate

Route object

A route through (potentially multiple) waypoints.

• distance: Float indicating the distance traveled in meters
• duration: Float indicating the estimated travel time in seconds
• geometry: Depending on the geometries parameter this is a GeoJSON LineString or a Polyline string. Depending on the overview parameter this is the complete route geometry (full), a simplified geometry to the zoom level at which the route can be displayed in full (simplified), or is not included (false).
• legs: Array of RouteLeg objects

RouteLeg object

A route between only two waypoints.

• distance: Number indicating the distance traveled in meters
• duration: Number indicating the estimated travel time in seconds
• steps: Depending on the steps parameter, either an Array of RouteStep objects (true, default) or an empty array (false)

RouteStep object

Includes one StepManeuver object and travel to the following RouteStep.

• distance: Number indicating the distance traveled in meters from the maneuver to the next RouteStep.

• duration: Number indicating the estimated time traveled time in seconds from the maneuver to the next RouteStep.

• geometry: Depending on the geometries parameter this is a GeoJSON LineString or a Polyline string representing the full route geometry from this RouteStep to the next RouteStep

• name: String with the name of the way along which the travel proceeds

• mode: String indicating the mode of transportation. Possible values:

  • For mapbox/driving: driving, ferry, unaccessible
  • For mapbox/walking: walking, ferry, unaccessible
  • For mapbox/cycling: cycling, walking, ferry, train, unaccessible

• maneuver: One StepManeuver object

StepManeuver object

• location: Array of [ longitude, latitude ] coordinates for the point of the maneuver
• bearing_before: Number between 0 and 360 indicating the clockwise angle from true north to the direction of travel right before the maneuver
• bearing_after: Number between 0 and 360 indicating the clockwise angle from true north to the direction of travel right after the maneuver
• instruction: A human-readable instruction of how to execute the returned maneuver
• type: String indicating the type of maneuver
• pronunciation: String The pronunciation hint of the way name. Will be undefined if no pronunciation is hit.

• intersections: Array of objects representing all intersections along the step.

  • location: A [longitude, latitude] pair describing the location of the turn.
  • bearings: A list of bearing values (for example [0,90,180,270]) that are available at the intersection. The bearings describe all available roads at the intersection.
  • entry: A list of entry flags, corresponding in a 1:1 relationship to the bearings. A value of true indicates that the respective road could be entered on a valid route. false indicates that the turn onto the respective road would violate a restriction.
  • in: Index into bearings/entry array. Used to calculate the bearing before the turn. Namely, the clockwise angle from true north to the direction of travel before the maneuver/passing the intersection. To get the bearing in the direction of driving, the bearing has to be rotated by a value of 180. The value is not supplied for departure maneuvers.
  • out: Index into the bearings/entry array. Used to extract the bearing after the turn. Namely, The clockwise angle from true north to the direction of travel after the maneuver/passing the intersection. The value is not supplied for arrive maneuvers.

  • lanes: Array of lane objects that represent the available turn lanes at the intersection. If no lane information is available for an intersection, the lanes property will not be present. Lanes are provided in their order on the street, from left to right.

    • valid: Boolean value for whether this lane can be taken to complete the maneuver. For instance, if the lane array has four objects and the first two are marked as valid, then the driver can take either of the left lanes and stay on the route.
    • indications: Array of signs for each turn lane. There can be multiple signs. For example, a turning lane can have a sign with an arrow pointing left and another sign with an arrow pointing straight.

Maneuver types

If the API returns a value for type that the client does not recognize, it should be treated like a turn.

* Note on type notification: Notification is only returned as a the maneuver type when the only turn type to be reported is a mode change. Otherwise, mode changes can go with every type and will not be announced except by the mode field value change.

• modifier: String indicating the mode of the maneuver. If type is of turn, the modifier indicates the change in direction accomplished through the turn. If the type is of depart/arrive, the modifier indicates the position of waypoint from the current direction of travel.

For uturn modifiers, you can derive the turn directions (left/right), by using the before and after bearings of the maneuver:

• A bearing difference of more than 180 degrees indicates a uturn to the left.
• A bearing difference of less than 180 degrees indicates a uturn to the right.

Errors

On error, the server responds with different HTTP status codes. For responses with HTTP status codes lower than 500, the JSON response body includes the code property, which may be used by client programs to manage control flow. The response body may also include a message property, with a human-readable explaination of the error.

Map Matching

The Mapbox Map Matching API snaps fuzzy, inaccurate traces from a GPS unit or a phone to the OpenStreetMap? road and path network using the Directions API. This produces clean paths that can be displayed on a map or used for other analysis.

Limits

• Maximum 60 requests per minute
• Maximum 100 coordinates per request
• Results must be displayed on a Mapbox map using one of our libraries or SDKs

For high volume or other use cases, contact us.

Retrieve a match

Returns a path on the road and path network closest to the input traces.

Request body must be one GeoJSON Feature with a LineString geometry. The LineString may have up to 100 positions.

If your traces are in GPX or KML format, you can use toGeoJSON to transform them to GeoJSON?.

It is recommended to include timestamps, since they help improve the quality of the matching. The timestamps must be ascending. For best results, your timestamps should have a sample rate of about 5 seconds.

Some pre-processing tips to achieve the best results:

• The Map Matching API is limited to processing traces with up to 100 coordinates. If you need to process longer traces, you can split the trace and make multiple requests.
• Clusters of points (like a person waiting at a train crossing for a few minutes) often don't add more information to a trace and should be removed.
• Map matching works best with a sample rate of 5 seconds between points. If your trace has a higher sample rate, you may want to downsample your trace.
• geojson-tidy removes clusters and re-samples traces, which can be useful for preprocessing.

The response is a GeoJSON FeatureCollection aligned with the OpenStreetMap? road/path network. It may include one or more GeoJSON Features; on clean matches, only one feature is returned, but when the matching algorithm cannot decide the correct match between two points, it will omit that line and create several sub-matches, each as a feature. The higher the number of features, the more likely that the input traces are poorly aligned to the road network.

All routing responses will include a code property that describes the type of result. If a server error occurs, the HTTP status code will be 500 or higher and the response will not include a code property.

Geocoding

The Mapbox Geocoding API does two things: geocoding and reverse geocoding.

Geocoding lets you convert location text into geographic coordinates: turning 1600 Pennsylvania Ave NW into -77.0366, 38.8971.

Reverse geocoding turns geographic coordinates into place names: from -77.036, 38.897 to 1600 Pennsylvania Ave NW. These place names can vary from specific addresses to states and countries that contain the given coordinate.

Swift and Objective-C support for Geocoding is provided by the MapboxGeocoder.swift library.

Restrictions and limits

Use of the geocoding API is rate limited by access token?. These limits vary by plan.

Exceeding the limits above will result in an HTTP 429 response. For information on rate limit headers, see Rate limits.

Batch geocoding is only available with an Enterprise plan. On all other plan levels, one geocode is permitted per request.

The results from geocoding with the mapbox.places mode must be displayed on a Mapbox map and cannot be stored permanently. The mapbox.places-permanent mode, available with an Enterprise plan, does not have these licensing restrictions.

The Mapbox Geocoding API coverage map lists the types of geocoding results support in each area of the world.

Queries are limited to a total of 20 words and numbers, separated by spacing or punctuation. They also can't be longer than 256 characters.

If you use the optional bounding box? parameter to filter results, note that the bounding box cannot cross the 180th meridian.

Request format

Both geocoding and reverse geocoding requests have the same basic format. Since the {query} parameter can contain any value, it should be URL-encoded.

The {country} parameter limits results to a set of one or more countries, specified with ISO 3166 alpha 2 country codes and separated by commas.

The {proximity} parameter biases search results around a specific location given in {longitude},{latitude} coordinates. Results will not be filtered by location or ordered by distance, but location will be considered along with textual relevance and other criteria when scoring and sorting results.

The {autocomplete} parameter controls whether autocomplete results are included. Autocomplete results can partially match the query: for example, searching for washingto could include washington even though only the prefix matches. Autocomplete is useful for offering fast type-ahead or autocomplete results in user interfaces. If your queries represent complete addresses or place names, you can disable this behavior and exclude partial matches by setting the {autocomplete} parameter to false.

The {bbox} parameter limits search results to those falling within a bounding box? given in minX,minY,maxX,maxY coordinates.

The {limit} parameter specifies the maximum number of results to be returned. For forward geocoding, the default is 5 and the maximum is 10. For reverse geocoding, the default is 1 and the maximum is 5. If limit is used for reverse geocoding, a single types must also be specified.

Response format

Our geocoding data is updated and improved constantly and responses for a given query may change. Geocoding results are returned in Carmen GeoJSON format. This format declares the types and existence of properties, but not their specific values: their values can change as our data improves.

Feature IDs are formatted like {type}.{id}. {type} is one of the types listed above. Additional feature types may be added in the future, but the current types will stay the same. The numeric part of a feature ID may change between data updates.

The {properties} property of the feature is unstable: only what is specified in Carmen GeoJSON is part of the stable API. But a response feature may include the following additional information in its properties or context sections. Your implementation should check for the presence of these values in a response before it attempts to use them.

Results are returned in order of relevance. They also have a relevance property that is based on how much of the query matched text in the result. You can use the relevance property to remove rough results if you require a response that matches your whole query.

Search for places

Try this in API Playground

This is often called forward geocoding. Request feature data that best matches the input {query} text. The response includes one or more results ordered by relevance.

This API is used by the Mapbox.js L.mapbox.geocoderControl and the mapbox-gl-geocoder user interfaces.

Retrieve places near a location

Try this in API Playground

This is often called reverse geocoding. Request feature data located at the input {longitude},{latitude} coordinates. The response includes at most one result from each type, unless using the limit option.

Batch requests

This feature is only available with the mapbox.places-permanent mode

Batch requests have the same parameters as normal requests, but can include more than one query by separating queries with the ; character. Each query should be URL encoded, but the ; character should not be encoded: it should be included verbatim.

With the mapbox.places-permanent mode, you can do up to 50 forward or reverse geocoding queries in a single request. The response is an array of individual geocoder responses formatted the same as individual results. Each query in a batch request counts individually against your account's rate limits.