Mapbox SDK for JavaScript

An MapiResponse is the object returned when an MapiRequest.send() Promise resolves. It contains the parsed API response and metadata.

Key properties and methods:

• MapiResponse.body: The parsed JSON body of the API response.
• MapiResponse.headers: The parsed HTTP headers.
• MapiResponse#hasNextPage(): Returns a boolean indicating if more results are available.
• MapiResponse#nextPage(): Returns a new MapiRequest for the next page of results.

Example: Reading body and pagination

// Read response body
stylesService.getStyle({..})
  .send()
  .then(resp => {
    const style = resp.body;
  });

// Handle pagination
tilesetsService.listTilesets()
  .send()
  .then(resp => {
    if (resp.hasNextPage()) {
      const nextPageReq = resp.nextPage();
      nextPageReq.send().then(..);
    }
  });

An MapiError is returned when an MapiRequest.send() Promise rejects. This happens if the server returns an error or if the request is aborted.

Key properties:

• MapiError.type: The type of error (e.g., 'RequestAbortedError').
• MapiError.statusCode: The HTTP status code (for server errors).
• MapiError.body: The parsed JSON body of the error response.
• MapiError.message: A human-readable error message.

Example: Error handling

stylesService.getStyle({..})
  .send()
  .then(response => { ... }, error => {
    if (error.type === 'RequestAbortedError') {
      return;
    }
    console.error(error.message);
  });

The Uploads service allows you to manage the lifecycle of tileset uploads to Mapbox. The typical workflow involves:

1. createUploadCredentials: Request S3 credentials (access keys, bucket, and key) to upload your files directly to an S3 bucket.
2. Upload to S3: Use the provided credentials to upload your data (e.g., .mbtiles files) to the specified S3 location.
3. createUpload: Notify Mapbox of the upload by providing the tileset ID and the S3 URL of the object you just uploaded.
4. getUpload: Monitor the status of the upload process.
5. listUploads: View the status of all recent uploads.
6. deleteUpload: Remove an upload.

When implementing service methods, follow these naming conventions to ensure consistency:

• Each method name must contain a verb and the object of that verb.
• Use specific verbs based on the HTTP method:
  • get and list for GET requests
  • create for POST requests
  • update for PATCH requests
  • put for PUT requests
  • delete for DELETE requests
• Only use special verbs if a clear title cannot be constructed using the standard verbs above.

Install the Mapbox SDK using npm. If you are targeting older browsers, ensure you provide a Promise polyfill (such as es6-promise).

npm install @mapbox/mapbox-sdk

Using the SDK involves three main steps: 1. Create a client, 2. Create a request via a service, and 3. Send the request.

const mbxClient = require('@mapbox/mapbox-sdk');
const mbxStyles = require('@mapbox/mapbox-sdk/services/styles');
const mbxTilesets = require('@mapbox/mapbox-sdk/services/tilesets');

// 1. Create a base client
const baseClient = mbxClient({ accessToken: MY_ACCESS_TOKEN });

// 2. Create service clients using the base client
const stylesService = mbxStyles(baseClient);
const tilesetsService = mbxTilesets(baseClient);

// 3. Create and send a request
stylesService.createStyle({..})
  .send()
  .then(response => { /* handle success */ }, error => { /* handle error */ });

// Example: List tilesets
tilesetsService.listTilesets()
  .send()
  .then(response => { /* handle success */ }, error => { /* handle error */ });

To view test coverage, run Jest with the --coverage flag.

Single run:

npx jest --coverage

Watch mode:

npx jest --watchAll --coverage

Coverage data is printed to the console and saved to the coverage/ directory. You can view a detailed HTML report by running:

open coverage/index.html