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 is an exception: its endpoint is prefixed with /v4/{map_id} 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, Tilesets, 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.

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

Retrieve a standalone marker

Request a single marker? image without any background map.

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 Style Specification 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 Style Specification. 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-v10
• mapbox://styles/mapbox/outdoors-v10
• mapbox://styles/mapbox/light-v9
• mapbox://styles/mapbox/dark-v9
• mapbox://styles/mapbox/satellite-v9
• mapbox://styles/mapbox/satellite-streets-v10
• mapbox://styles/mapbox/traffic-day-v2
• mapbox://styles/mapbox/traffic-night-v2

Traffic styles feature coverage in geographies we support.

The style object

The style object conforms to the Mapbox 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 Style 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 Style Specification: invalid styles will produce a descriptive validation error.

Only the most recent version of the Mapbox Style Specification 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 Style Specification.

Sprites are managed on a per-style basis: each sprite belongs to a style, so the sprite limit of 500 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.
• Icon names must be fewer than 255 characters in length.
• Sprites can contain up to 500 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.

Static

The Mapbox Static API returns static maps and raster tiles from styles in the Mapbox Style Specification. See the Static (Classic) API documentation.

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.

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

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.

Overlay

An overlay is data that can be applied on top of the map at request time. These are comma separated and can be a mix of valid GeoJSON, a marker?, a custom marker or path. Overlays cannot consist of more than 100 features. The maximum overlay length is 2083 characters. The order of the features 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).

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 a 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({geojson})

GeoJSON features will be respected and rendered.

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.

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.

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.

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. The goal of this API is to let you manage your geodata using Mapbox. To serve this data at scale, convert your dataset? into a tileset? using the Uploads API.

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

Geocoding

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

Forward geocoding lets you convert location text into geographic coordinates, turning 2 Lincoln Memorial Circle NW into -77.050,38.889.

Reverse geocoding turns geographic coordinates into place names, turning -77.050, 38.889 into 2 Lincoln Memorial Circle NW. These place names can vary from specific addresses to states and countries that contain the given coordinates.

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 supported in each area of the world.

Queries are limited to either a total of 20 words and numbers separated by spacing and punctuation or 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 UTF-8.

The {proximity} parameter biases search results within 5 miles of 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 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 {limit} parameter specifies the maximum number of results to return. 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 a limit other than 1 is used for reverse geocoding, a single types option must also be specified.

The {language} parameter specifies the desired response language for user queries. For forward geocodes, results that match the requested language are favored over results in other languages. If more than one language tag is supplied, text in all requested languages will be returned. For forward geocodes with more than one language tag, only the first language will be used to weight results.

Any valid IETF language tag can be submitted, and a best effort will be made to return results in the requested language or languages, falling back first to similar and then to common languages in the event that text is not available in the requested language. In the event a fallback language is used, the language field will have a different value than the one requested.

Translation availability varies by language and region:

Global coverage: these languages are almost always present for country, region, and prominent place features

Local coverage: these languages may lack global coverage but are almost always present for country, region, and prominent place features where they are widely used

Limited coverage: these languages are sometimes present but coverage tends to be inconsistent or geographically constrained

Response object

Because Mapbox's geocoding? data is constantly updated and improved, the values of properties in the response object are not guaranteed and may change within the same version of the API. Properties may be added to but will not be removed from the response within the same version. Geocoding results are returned in Carmen GeoJSON format.

Feature object

Each feature object in the "features" array may have the properties described below. Forward geocodes return features ordered by relevance. Reverse geocodes return features in order of index hierarchy from most specific features to least specific features that overlap the queried coordinates.

Search for places

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.

Try this in the API Playground.

Retrieve places near a location

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.

Try this in the API Playground.

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 make up to 50 forward or reverse geocoding? queries in a single request. The response is an array of individual geocoder responses. Each query in a batch request counts individually against your account's rate limits.

Directions

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 four different routing profiles:

• mapbox/driving-traffic for automotive routing. This profile factors in current and historic traffic conditions to avoid slowdowns. Traffic is available in these supported geographies
• mapbox/driving for automotive 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. Requests using driving, walking, and cycling profiles can specify up to 25 total waypoints along the route. Requests using the driving-traffic profile can specify up to 3 waypoints.
• Traffic coverage for the driving-traffic profile is available in supported geographies. Requests to this profile revert to driving profile results for areas without traffic coverage.
• Maximum 60 requests per minute
• Computing route alternatives is not supported on the driving-traffic profile.

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.

Instructions languages

The table below shows supported language codes used with the language parameter for turn-by-turn instructions.

If an unsupported language code is used, the language parameter will automatically be set to English.

Directions response object

• 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
• weight: Float indicating the weight in units described by weight_name
• weight_name: String indicating which weight was used. The default is routability which is duration based, with additional penalties for less desirable maneuvers.
• 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)
• summary: Depending on the summary parameter, either a String summarizing the route (true, default) or an empty String (false)
• annotation: An annotations object that contains additional details about each line segment along the route geometry. Each entry in an annotations field corresponds to a coordinate along the route geometry.

congestion is the speed with traffic compared with speed with no traffic. A break down is below:

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

• ref: Any road designations associated with the road or path leading from this step’s maneuver to the next step’s maneuver. Optionally included, if data is available. If multiple road designations are associated with the road, they are separated by semicolons. A road designation typically consists of an alphabetic network code (identifying the road type or numbering system), a space or hyphen, and a route number. You should not assume that the network code is globally unique: for example, a network code of “NH” may appear on a “National Highway” or “New Hampshire”. Moreover, a route number may not even uniquely identify a road within a given network.

• destinations: String with the destinations of the way along which the travel proceeds. Optionally included, if data is available.

• exits: String with the exit numbers or names of the way. Optionally included, if data is available.

• 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

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

  • classes: An array of strings signifying the classes of the road exiting the intersection. Possible values:

    • toll: the road continues on a toll road
    • ferry: the road continues on a ferry
    • restricted: the road continues on with access restrictions
    • motorway: the road continues on a motorway
  • 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.

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
• modifier Optional String indicating the direction change of the maneuver

The list of turns without a modifier is limited to: depart / arrive. If the source? / target location is close enough to the depart / arrive location, no modifier will be given.

The meaning depends on the type property.

New properties (potentially depending on type) may be introduced in the future without an API version change.

Maneuver types

Lane object

Available turn lanes at the intersection. 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.

Directions 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 explanation of the error. If a server error occurs, the HTTP status code will be 500 or higher and the response will not include a code property.

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

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.

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 can negatively impact map-matching quality. We recommend to tidy the trace: remove clusters and provide a uniform sample rate. You can use the tidy=true query parameter or pre-process your traces with external tools like geojson-tidy.
• 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.

Match response object

With clean matches, only one match object is returned. When the the algorithm cannot decide the correct match between two points, it will omit that line and return several sub-matches as match objects. The higher the number of sub-match match objects, the more likely that the input traces are poorly aligned to the road network.

• code: a string depicting the state of the response; see below for options
• matchings: an array of Match objects
• tracepoints: an array of Tracepoint objects representing the location an input point was matched with. Array of Waypoint objects representing all input points of the trace in the order they were matched. If a trace point is omitted by map matching because it is an outlier, the entry will be null.

Match object

A match object is a Route object with an additional confidence field.

• confidence: a number between 0 (low) and 1 (high) indicating level of confidence in the returned match

Refer to the Route object documentation for how the rest of a Match object is structured.

Tracepoint object

A tracepoint object is Waypoint object with two additional fields:

• matchings_index: Index to the match object in matchings the sub-trace was matched to.
• waypoint_index: Index of the waypoint inside the matched route.
• alternatives_count: Number of probable alternative matchings for this trace point. A value of zero indicates that this point was matched unambiguously. Split the trace at these points for incremental map matching.

Map Matching 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. If a server error occurs, the HTTP status code will be 500 or higher and the response will not include a code property.

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

Matrix

The Matrix API returns travel times between many points.

For example, given 3 locations A, B, C, the Matrix API will return a matrix of all travel times in seconds between the locations:

The Matrix API will always return the duration on the fastest route. Durations between points may not be symmetric (for example A to B may have a different duration than B to A), as the routes may differ by direction due to one-way streets or turn restrictions. The Matrix API returns durations in seconds. It does not return route geometries or distances.

This API allows you to build tools that efficiently check the reachability of coordinates from each other, filter? points by travel time, or run your own algorithms for solving optimization problems.

Limits

• Maximum 60 requests per minute
• Maximum 25 input coordinates

For example you can request a symmetric 25x25 matrix, an asymmetric 1x24 matrix with distinct coordinates or a 12x24 where sources and destinations share some coordinates.

For higher volumes, contact us.

Retrieve a matrix

Returns a duration matrix showing travel times between coordinates.

The {profile} parameter of your request should be a Mapbox Directions routing profile? ID. The following IDs are supported:

• mapbox/driving for car travel times
• mapbox/walking for pedestrian and hiking travel times
• mapbox/cycling for bicycle travel times

The mapbox/driving-traffic profile is not supported.

The {coordinates} parameter is a semicolon-separated list of {longitude},{latitude} coordinates. There must be between 2 and 25 coordinates.

In the default case, the matrix returns a symmetric matrix, using all input coordinates as sources and destinations. You may also generate an asymmetric matrix, with only some coordinates as sources or destinations:

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

Matrix response format

• 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. See the errors section below for more information.
• durations: Durations as array of arrays representing the matrix in row-major order. durations[i][j] gives the travel time from the i-th source to the j-th destination. All values are in seconds. The duration between the same coordinate is always 0. If a duration can not be found, the result is null.
• destinations:: 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, or in the order as specified in the destinations query parameter.
• sources: 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, or in the order as specified in the sources query parameter.

Matrix 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 explanation of the error. If a server error occurs, the HTTP status code will be 500 or higher and the response will not include a code property.

Note that in cases where no route is found between a source? and destination, no error will be returned, but instead the respective value in the durations matrix will be null.

The earlier Mapbox Distance API is deprecated. See the documentation.

Optimization

The Optimization API returns a duration-optimized route between the input coordinates. This is also known as solving the Traveling Salesperson Problem. A typical use case for this API is planning the route for deliveries in a city. Route can be retrieved for car driving, bicycling and walking or hiking.

Limits

• Maximum 12 coordinates
• Maximum 25 distributions per requests
• Maximum 60 requests per minute

For higher volumes, contact us.

Retrieve an optimization

The {profile} parameter of your request should be a Mapbox Directions routing profile? ID. The following IDs are supported:

• mapbox/driving for car trips
• mapbox/walking for pedestrian and hiking trips
• mapbox/cycling for bicycle trips

The mapbox/driving-traffic profile is not supported.

The {coordinates} parameter is a semicolon-separated list of {longitude},{latitude} coordinates. There must be between 2 and 12 coordinates. The first coordinate is the start and end point of the trip.

The response may be altered with optional query parameters:

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

Note that routes returned by the Optimization API will behave as if continue_straight=false was set at each waypoint. See the continue\straight parameter for more details on what this means for the route.

Fixing Start and End Points

It is possible to explicitly set the start or end coordinate of the trip. When source? is set to first, the first coordinate is used as the start coordinate of the trip in the output. When destination is set to last, the last coordinate will be used as destination of the trip in the returned output. If you specify any, any of the coordinates can be used as the first or last coordinate in the output.

If source=any&destination=any the returned roundtrip will still start at the first input coordinate by default.

Not all combinations of roundtrip, source and destination are supported. Right now, the following combinations are possible:

Optimization response format

• 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. See the errors section below for more information.
• waypoints: Array of waypoint objects. Each waypoint is an input coordinate snapped to the road and path network. The waypoints appear in the array in the order of the input coordinates.
• trips: Array of trip objects. Will have zero or one trip.

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
• trips_index: Index to the trip object in the trips array that contains this waypoint
• waypoint_index: Index of position of the waypoint within the trip

Trip object

A trip object is a route through (potentially multiple) waypoints. It follows the exact same format as the Route object in the Directions API. Please refer to the Directions API documentation.

Optimization 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 explanation of the error. If a server error occurs, the HTTP status code will be 500 or higher and the response will not include a code property.

All other properties might be undefined.

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.

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.