# @mapbox/mapbox-sdk

> JS SDK for accessing Mapbox APIs

Latest version **0.16.2** (published 2025-09-12) · BSD-2-Clause license · 0 weekly downloads

## Install

```sh
npm install @mapbox/mapbox-sdk
pnpm add @mapbox/mapbox-sdk
yarn add @mapbox/mapbox-sdk
bun add @mapbox/mapbox-sdk
```

## Health

**Score 48/100 (D)** — status: stable.

Positive: has types package; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 0.16.2 |
| Published | 2025-09-12 |
| First published | 2018-06-11 |
| Weekly downloads | 0 |
| License | BSD-2-Clause |
| TypeScript types | separate (@types/mapbox__mapbox-sdk) |
| Module format | CommonJS |
| Node | >=6 |
| Dependencies | 8 |
| Unpacked size | 563.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 768 |
| Author | Mapbox |
| Maintainers | mapbox-npm-01, mapbox-npm-02, mapbox-npm-07, mapbox-npm-03, mapbox-npm-04, mapbox-npm-09, mapbox-npm-05, mapbox-npm-06, mapbox-npm-08, mapbox-npm-advanced-actions, mapbox-npm-ci, mapbox-npm, mapbox-admin, mapbox-machine-user, mbx-npm-ci-staging, mbx-npm-ci-production, mbx-npm-01-production, mbx-npm-02-production, mbx-npm-03-production, mbx-npm-04-production, mbx-npm-05-production, mbx-npm-06-production, mbx-npm-07-production, mbx-npm-08-production, mbx-npm-09-production, mbx-npm-02-staging, mbx-npm-advanced-actions-staging, mbx-npm-advanced-actions-production |
| Keywords | mapbox, sdk, api, map, style, tileset, dataset, search, navigation |

## Links

- npm: https://www.npmjs.com/package/@mapbox/mapbox-sdk
- Repository: https://github.com/mapbox/mapbox-sdk-js
- Homepage: https://github.com/mapbox/mapbox-sdk-js#readme
- Issues: https://github.com/mapbox/mapbox-sdk-js/issues
- npm.io page: https://npm.io/package/@mapbox/mapbox-sdk

## Dependencies (8)

- [got](https://npm.io/package/got.md) ^11.8.5
- [xtend](https://npm.io/package/xtend.md) ^4.0.1
- [form-data](https://npm.io/package/form-data.md) ^3.0.4
- [is-plain-obj](https://npm.io/package/is-plain-obj.md) ^1.1.0
- [eventemitter3](https://npm.io/package/eventemitter3.md) ^3.1.0
- [@mapbox/fusspot](https://npm.io/package/@mapbox/fusspot.md) ^0.4.0
- [@mapbox/polyline](https://npm.io/package/@mapbox/polyline.md) ^1.0.0
- [@mapbox/parse-mapbox-token](https://npm.io/package/@mapbox/parse-mapbox-token.md) ^0.2.0

## Alternatives

- [express-promise-router](https://npm.io/package/express-promise-router.md) — 736.1K weekly downloads
- [next-usequerystate](https://npm.io/package/next-usequerystate.md) — 29.8K weekly downloads
- [@bitkyc08/opencodex](https://npm.io/package/@bitkyc08/opencodex.md) — 4.6K weekly downloads
- [lynkr](https://npm.io/package/lynkr.md) — 575 weekly downloads
- [baremetal.js](https://npm.io/package/baremetal.js.md) — 42 weekly downloads

## Recent versions

- 0.16.2 (latest) — 2025-09-12
- 0.16.2-dev.1 (dev) — 2025-09-12
- 0.16.1 — 2024-09-13
- 0.16.0 — 2024-05-02
- 0.15.6 — 2024-04-23
- 0.15.5 — 2024-03-13
- 0.15.4 — 2024-03-12
- 0.15.4-dev.1 — 2024-03-11
- 0.15.3 — 2023-08-02
- 0.15.2 — 2023-06-08
- 0.15.1 — 2023-04-27
- 0.15.0 — 2023-02-06
- 0.14.0 — 2022-11-17
- 0.13.7 — 2022-10-26
- 0.13.6 — 2022-10-14
- … 24 more at https://npm.io/package/@mapbox/mapbox-sdk/versions

## README

# @mapbox/mapbox-sdk

[![Build Status](https://travis-ci.com/mapbox/mapbox-sdk-js.svg?branch=main)](https://travis-ci.com/mapbox/mapbox-sdk-js)

A JS SDK for working with [Mapbox APIs](https://docs.mapbox.com/api/).

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

- [Installation](#installation)
- [Usage](#usage)
  - [Creating clients](#creating-clients)
  - [Creating and sending requests](#creating-and-sending-requests)
- [Overview of requests, responses, and errors](#overview-of-requests-responses-and-errors)
  - [MapiRequest](#mapirequest)
  - [MapiResponse](#mapiresponse)
  - [MapiError](#mapierror)
- [Services](#services)
- [Pre-bundled files on unpkg.com](#pre-bundled-files-on-unpkgcom)
- [Development](#development)

## Installation

```
npm install @mapbox/mapbox-sdk
```

**If you are supporting older browsers, you will need a Promise polyfill.**
[es6-promise](https://github.com/stefanpenner/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 unpkg.com"](#pre-bundled-files-on-unpkgcom).

## Usage

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.

```js
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.

```js
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`.

```js
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.
stylesService.createStyle({..})
  .send()
  .then(response => {..}, error => {..});

// List tilesets.
tilesetsService.listTilesets()
  .send()
  .then(response => {..}, error => {..})
```

## Overview of requests, responses, and errors

**For more details, please read [the full classes documentation](./docs/classes.md).**

### `MapiRequest`

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`].

`MapiRequest`s 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](./docs/classes.md#mapirequest).

```js
// Create a request and send it.
stylesService.createStyle({..})
  .send()
  .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.
});
req.abort();

// 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 => {..});
```

### `MapiResponse`

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

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

`MapiResponse`s 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](./docs/classes.md#mapiresponse).

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

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

// Check the headers.
tilesetsService.listTilesets()
  .send()
  .then(resp => {
    console.log(resp.headers);
  }, err => {..});
```

### `MapiError`

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

`MapiError`s 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](./docs/classes.md#mapierror).

```js
// Check the error.
stylesService.getStyle({..})
  .send()
  .then(response => {..}, error => {
    if (err.type === 'RequestAbortedError') {
      return;
    }
    console.error(error.message);
  });
```

## Services

Please read [the full documentation for services](./docs/services.md).

## Pre-bundled files on unpkg.com

If you aren't using a JS module system, you can use a `<script>` tag referencing pre-bundled files on the CDN [unpkg.com](https://unpkg.com/).

```html
<script src="https://unpkg.com/@mapbox/mapbox-sdk/umd/mapbox-sdk.js"></script>
<script src="https://unpkg.com/@mapbox/mapbox-sdk/umd/mapbox-sdk.min.js"></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.

```html
<script src="https://unpkg.com/@mapbox/mapbox-sdk/umd/mapbox-sdk.min.js"></script>
<script>
  var mapboxClient = mapboxSdk({ accessToken: MY_ACCESS_TOKEN });
  mapboxClient.styles.getStyle(..)
    .send()
    .then(..);
  mapboxClient.tilesets.listTilesets(..)
    .send()
    .then(..);
</script>
```

## Development

Please read [`./docs/development.md`](./docs/development.md).

[`got`]: https://github.com/sindresorhus/got

[`http`]: https://nodejs.org/api/http.html

[`xmlhttprequest`]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest

[`mapirequest`]: #mapirequest

[`mapiresponse`]: #mapiresponse

[`mapierror`]: #mapierror

---
_Source: https://npm.io/package/@mapbox/mapbox-sdk · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._