Skip to content

Latest commit

 

History

History
executable file
·
264 lines (196 loc) · 10.7 KB

topics.md

File metadata and controls

executable file
·
264 lines (196 loc) · 10.7 KB
Raw

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.

https://api.mapbox.com

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 your Account Dashboard. You can also manage and create additional tokens on your Access tokens page or with the Tokens API.

Access token example

https://api.mapbox.com/{endpoint}?access_token={your_access_token}

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.

Versioning example

https://api.mapbox.com/{api}/{version}

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.

Header Description
X-Rate-Limit-Interval Length of rate-limiting interval in seconds.
X-Rate-Limit-Limit Maximum number of requests you may make in the current interval before reaching the limit.
X-Rate-Limit-Reset Unix timestamp of when the current interval will end and the ratelimit counter is reset.

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

# a 400x200 static map
https://api.mapbox.com/v4/mapbox.dark/-76.9,38.9,5/400x200.png?access_token={your_access_token}

# the same static map for Retina
# displays: this image will be 800x400
# pixels, but show the same content
# and look the same when scaled down
https://api.mapbox.com/v4/mapbox.dark/-76.9,38.9,5/[email protected]?access_token={your_access_token}

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

Link: <https://api.mapbox.com/uploads/v1/1454024795582?start=cijywvxlm004rtikohhqf99jv&limit=100>; rel="next"

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.

Query Parameter Description
limit The maximum number of objects to return. The API will attempt to return the requested number of objects, but receiving fewer objects does not necessarily signal the end of the collection. Receiving a response with no Link header or no next link relation is the only way to determine when you are at the end of a collection.

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.

var parsedDate = new Date('2014-11-21T19:41:10.000Z');
import arrow
arrow.get('2014-11-21T19:41:10.000Z')
<Arrow [2014-11-21T19:41:10+00:00]>
@import Foundation;

NSDateFormatter *RFC3339DateFormatter = [[NSDateFormatter alloc] init];
RFC3339DateFormatter.locale = [NSLocale localeWithLocaleIdentifier:@"en_US_POSIX"];
RFC3339DateFormatter.dateFormat = @"yyyy-MM-dd'T'HH:mm:ssZZZZZ";
RFC3339DateFormatter.timeZone = [NSTimeZone timeZoneForSecondsFromGMT:0];

NSDate *date = [RFC3339DateFormatter dateFromString:@"2014-11-21T19:41:10.000Z"];
import Foundation

let rfc3339DateFormatter = DateFormatter()
rfc3339DateFormatter.locale = Locale(identifier: "en_US_POSIX")
rfc3339DateFormatter.dateFormat = "yyyy-MM-dd'T'HH:mm:ssZZZZZ"
rfc3339DateFormatter.timeZone = TimeZone(secondsFromGMT: 0)

let date = rfc3339DateFormatter.date(from: "2014-11-21T19:41:10.000Z")

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

@import Foundation;

NSDate *date = [NSDate dateWithTimeIntervalSince1970:1416598870000];
import Foundation

let date = Date(timeIntervalSince1970: 1_416_598_870_000)

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.

@import CoreLocation;

CLLocationCoordinate2D coord = CLLocationCoordinate2DMake(38.9099711, -77.0361122);
import CoreLocation

let coord = CLLocationCoordinate2D(latitude: 38.9099711, longitude: -77.0361122)