A JavaScript client to Mapbox services, supporting Node, browsers, and React Native





GitHub Stars



Last Commit

2mos ago






Size (min+gzip)




Type Definitions




Average Rating

Read All Reviews

Top Feedback

1Great Documentation
1Easy to Use
1Highly Customizable
1Bleeding Edge



Build Status

A JS SDK for working with Mapbox APIs.

Works in Node, the browser, and React Native.

As of 6/11/18, the codebase has been rewritten and a new npm package released. The mapbox package is deprecated in favor of the new @mapbox/mapbox-sdk package. Please read the documentation and open issues with questions or problems.

Table of contents


npm install @mapbox/mapbox-sdk

If you are supporting older browsers, you will need a Promise polyfill. es6-promise is a good one, if you're uncertain.

The documentation below assumes you're using a JS module system. If you aren't, read "Pre-bundled files on".


There are 3 basic steps to getting an API response:

  1. Create a client.
  2. Create a request.
  3. Send the request.

Creating clients

To create a service client, import the service's factory function from '@mapbox/mapbox-sdk/services/{service}' and provide it with your access token.

The service client exposes methods that create requests.

const mbxStyles = require('@mapbox/mapbox-sdk/services/styles');
const stylesService = mbxStyles({ accessToken: MY_ACCESS_TOKEN });
// stylesService exposes listStyles(), createStyle(), getStyle(), etc.

You can also share one configuration between multiple services. To do that, initialize a base client and then pass that into service factory functions.

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

const baseClient = mbxClient({ accessToken: MY_ACCESS_TOKEN });
const stylesService = mbxStyles(baseClient);
const tilesetsService = mbxTilesets(baseClient);

Creating and sending requests

To create a request, invoke a method on a service client.

Once you've created a request, send the request with its send method. It will return a Promise that resolves with a MapiResponse.

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

const baseClient = mbxClient({ accessToken: MY_ACCESS_TOKEN });
const stylesService = mbxStyles(baseClient);
const tilesetsService = mbxTilesets(baseClient);

// Create a style.
  .then(response => {..}, error => {..});

// List tilesets.
  .then(response => {..}, error => {..})

Overview of requests, responses, and errors

For more details, please read the full classes documentation.


Service methods return MapiRequest objects.

Typically, you'll create a MapiRequest then send it. send returns a Promise that resolves with a MapiResponse or rejects with a MapiError.

MapiRequests also expose other properties and methods that you might use from time to time. For example:

  • MapiRequest#abort aborts the request.
  • MapiRequest#eachPage executes a callback for each page of a paginated API response.
  • MapiRequest.emitter exposes an event emitter that fires events like downloadProgress and uploadProgress.

For more details, please read the full MapiRequest documentation.

// Create a request and send it.
  .then(response => {..}, error => {..});

// Abort a request.
const req = tilesetsService.listTilesets();
req.send().then(response => {..}, error => {
  // Because the request is aborted, an error will be thrown that we can
  // catch and handle.

// Paginate through a response.
tilesetsService.listTilesets().eachPage((error, response, next) => {
  // Do something with the page, then call next() to send the request
  // for the next page.

  // You can check whether there will be a next page using
  // MapiResponse#hasNextPage, if you want to do something
  // different on the last page.
  if (!response.hasNextPage()) {..}

// Listen for uploadProgress events.
const req = stylesService.createStyleIcon({..});
req.on('uploadProgress', event => {
  // Do something with the progress event information.
req.send().then(response => {..}, error => {..});


When you send a MapiRequest, the returned Promise resolves with a MapiResponse.

Typically, you'll use MapiResponse.body to access the parsed API response.

MapiResponses also expose other properties and methods. For example:

  • MapiResponse#hasNextPage indicates if there is another page of results.
  • If there is another page, MapiResponse#nextPage creates a MapiRequest that you can send to get that next page.
  • MapiResponse.headers exposes the parsed HTTP headers from the API response.

For more details, please read the full MapiResponse documentation.

// Read a response body.
  .then(resp => {
    const style = resp.body;
    // Do something with the style.
  }, err => {..});

// Get the next page of results.
  .then(resp => {
    if (resp.hasNextPage()) {
      const nextPageReq = resp.nextPage();
  }, err => {..});

// Check the headers.
  .then(resp => {
  }, err => {..});


If the server responds to your MapiRequest with an error, or if you abort the request, the Promise returned by send will reject with a MapiError.

MapiErrors expose the information you'll need to handle and respond to the error. For example:

  • MapiError.type exposes the type of error, so you'll know if it was an HTTP error from the server or the request was aborted.
  • MapiError.statusCode exposes the status code of HTTP errors.
  • MapiError.body exposes the body of the HTTP response, parsed as JSON if possible.
  • MapiError.message tells you what went wrong.

For more details, please read the full MapiError documentation.

// Check the error.
  .then(response => {..}, error => {
    if (err.type === 'RequestAbortedError') {


Please read the full documentation for services.

Pre-bundled files on

If you aren't using a JS module system, you can use a <script> tag referencing pre-bundled files on the CDN

<script src=""></script>
<script src=""></script>

These files are a UMD build of the package, exposing a global mapboxSdk function that creates a client, initializes all the services, and attaches those services to the client. Here's how you might use it.

<script src=""></script>
  var mapboxClient = mapboxSdk({ accessToken: MY_ACCESS_TOKEN });


Please read ./docs/

Rate & Review

Great Documentation1
Easy to Use1
Highly Customizable1
Bleeding Edge1
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Unwelcoming Community0
RB35Australia26 Ratings31 Reviews
3 months ago
Great Documentation
Easy to Use
Highly Customizable
Bleeding Edge

Mapbox allows you to show map with markers and so much more. Copy and paste 10 lines of code and boom you've got a map! Every thing on the map can have a custom style to fit you website. But it can do much more want to put a image over the top of the map such a weather radar, need to have your app guide you to a destination, show elevation as a 3d map all these things are just the tip of the ice burg for what you can do in map box. The documentation is easy to understand with many different examples. No need to add a credit card until you pass 50,000 map loads a month. I personally have made a website showing all of the public transport in my city with custom images for all kinds of trains, trams and buses. Including a feature coming soon that can guide you to the right platform. All of this relies on mapbox and it has never let me down!



No tutorials found
Add a tutorial