# @mapbox/sphericalmercator

> Transformations between the Web Mercator projection and Latitude Longitude coordinates

Latest version **2.0.2** (published 2025-09-30) · 337.5K weekly downloads

## Install

```sh
npm install @mapbox/sphericalmercator
pnpm add @mapbox/sphericalmercator
yarn add @mapbox/sphericalmercator
bun add @mapbox/sphericalmercator
```

## Health

**Score 73/100 (B)** — status: stable.

Positive: moderate downloads; has types package; esm support; no vulnerabilities; high quality score.

## Facts

| | |
|---|---|
| Version | 2.0.2 |
| Published | 2025-09-30 |
| First published | 2016-12-02 |
| Weekly downloads | 337.5K |
| TypeScript types | separate (@types/mapbox__sphericalmercator) |
| Module format | ESM |
| Dependencies | 0 |
| Unpacked size | 61.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 288 |
| 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 | map, projection, transformations |

## Links

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

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 2.0.2 (latest) — 2025-09-30
- 2.0.0-dev.1 (dev) — 2024-10-02
- 2.0.1 — 2024-11-06
- 2.0.0 — 2024-10-02
- 1.2.0 — 2021-09-21
- 1.2.0-dev — 2021-09-20
- 1.1.0 — 2018-05-18
- 1.0.5 — 2016-12-02

## README

[![Run tests](https://github.com/mapbox/sphericalmercator/actions/workflows/test.yml/badge.svg)](https://github.com/mapbox/sphericalmercator/actions/workflows/test.yml)

# sphericalmercator

Provides projection math for converting between mercator meters, screen pixels (of 256x256 or configurable-size tiles), and latitude/longitude. Compatible with nodejs packages and in-browser.

See also 

* [tilebelt](https://github.com/mapbox/tilebelt) provides ZXY tile math utilities in javascript
* [mercantile](https://github.com/sgillies/mercantile) provides similar utilities for projection and tile math in Python


## Installation

`npm install @mapbox/sphericalmercator`

## API

Some datatypes are assumed to be arrays: `ll` is `[lon, lat]`, `xy` and `px` are `[x, y]`.

```javascript
import { SphericalMercator } from '@mapbox/sphericalmercator';

// By default, precomputes up to z30
const merc = new SphericalMercator({
  size: 256,
  antimeridian: true
});
```

or, for CommonJS:

```javascript
const { SphericalMercator } = require('@mapbox/sphericalmercator');
```

### `px(ll, zoom)`

Convert lon, lat to screen pixel x, y from 0, 0 origin, at a certain zoom level. The inverse of `ll`. If `antimeridian: true` is passed on initialization of the `SphericalMercator` object, this method will support converting longitude values up to 360°.

### `ll(px, zoom)`

Convert screen pixel value to lon, lat, at a certain zoom level. The inverse of `px`.

### `bbox(x, y, zoom, tmsStyle, srs)`

Convert tile xyz value to bbox of the form `[w, s, e, n]`

* `x` {Number} x (longitude) number.
* `y` {Number} y (latitude) number.
* `zoom` {Number} zoom.
* `tmsStyle` {Boolean} whether to compute using [tms-style](https://en.wikipedia.org/wiki/Tile_Map_Service). (optional, default false)
* `srs` {String} projection for resulting bbox (WGS84|900913). (optional, default WGS84)

Returns bbox array of values in form `[w, s, e, n]`.

### `xyz(bbox, zoom, tmsStyle, srs)`

Convert bbox to xyz bounds

* `bbox` {Number} bbox in the form `[w, s, e, n]`.
* `zoom` {Number} zoom.
* `tmsStyle` {Boolean} whether to compute using [tms-style](https://en.wikipedia.org/wiki/Tile_Map_Service). (optional, default false)
* `srs` {String} projection of input bbox (WGS84|900913). (optional, default WGS84)

Returns {Object} XYZ bounds containing minX, maxX, minY, maxY properties.

### `convert(bbox, to)`

Convert bbox from 900913 to WGS84 or vice versa

* `bbox` {Number} bbox in the form `[w, s, e, n]`.
* `to` {String} projection of resulting bbox (WGS84|900913). (optional, default WGS84)

Returns bbox array of values in form `[w, s, e, n]`.

### `forward(ll)`

Convert lon, lat values to mercator x, y

### `inverse(xy)`

Convert mercator x, y values to lon, lat

## Developing

```sh
npm ci          # install
npm test        # run tests
npm run format  # format files with prettier
```

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