Global Mercator



A set of tools geospatial tools to help with TMS, Google (XYZ) Tiles.

> This library is insipered by GDAL2Tiles, Google Summer of Code 2007 & 2008.

Another great simplistic tile library is tilebelt.

Install

npm

``bash
$ npm install --save global-mercator
`

web

`html

`

Quickstart

`javascript
var globalMercator = require('global-mercator')
var tile = [10, 15, 8] // [x, y, zoom]
globalMercator.tileToBBox(tile)
// [ -165.937, -82.853, -164.531, -82.676 ]
`

Features

| Function | Description |
| --------------------------------------------------------- | :------------------------------------------------------------------- |
| lngLatToMeters(LngLat) | Converts LngLat coordinates to Meters coordinates. |
| metersToLngLat(Meters) | Converts Meters coordinates to LngLat coordinates. |
| metersToPixels(Meters, zoom) | Converts Meters coordinates to Pixels coordinates. |
| lngLatToTile(LngLat, zoom) | Converts LngLat coordinates to TMS Tile. |
| lngLatToGoogle(LngLat, zoom) | Converts LngLat coordinates to Google (XYZ) Tile. |
| metersToTile(Meters, zoom) | Converts Meters coordinates to TMS Tile. |
| pixelsToMeters(Pixels) | Converts Pixels coordinates to Meters coordinates. |
| pixelsToTile(Pixels) | Converts Pixels coordinates to TMS Tile. |
| tileToBBoxMeters(tile) | Converts TMS Tile to bbox in Meters coordinates. |
| tileToBBox(tile) | Converts TMS Tile to bbox in LngLat coordinates. |
| googleToBBoxMeters(google) | Converts Google (XYZ) Tile to bbox in Meters coordinates. |
| googleToBBox(google) | Converts Google (XYZ) Tile to bbox in LngLat coordinates. |
| tileToGoogle(tile) | Converts TMS Tile to Google (XYZ) Tile. |
| googleToTile(google) | Converts Google (XYZ) Tile to TMS Tile. |
| googleToQuadkey(google) | Converts Google (XYZ) Tile to Quadkey. |
| tileToQuadkey(tile) | Converts TMS Tile to QuadKey. |
| quadkeyToTile(quadkey) | Converts Quadkey to TMS Tile. |
| quadkeyToGoogle(quadkey) | Converts Quadkey to Google (XYZ) Tile. |
| hash(tile) | Hash tile for unique id key |
| validateTile(tile) | Validates TMS Tile |
| validateZoom(zoom) | Validates Zoom level |
| validateLngLat(LngLat) | Validates LngLat coordinates |
| validatePixels(Pixels) | Validates Pixels coordinates |
| [maxBBox(BBox\[\])](#maxbbox) | Maximum extent of BBox |
| validTile(tile) | Valid Tile |
| longitude(degree) | Modifies a Longitude to fit within +/-180 degrees. |
| latitude(degree) | Modifies a Latitude to fit within +/-90 degrees. |
| pointToTile(lnglat, zoom) | Get the tile for a point at a specified zoom level |
| pointToTileFraction(lnglat, zoom) | Get the precise fractional tile location for a point at a zoom level |
| wrapTile(tile) | Handles tiles which crosses the 180th meridian |
| bboxToTile(bbox) | Get the smallest tile to cover a bbox |

API

#### Table of Contents

- hash
- Parameters
- Examples
- pointToTile
- Parameters
- Examples
- pointToTileFraction
- Parameters
- Examples
- bboxToCenter
- Parameters
- Examples
- lngLatToMeters
- Parameters
- Examples
- metersToLngLat
- Parameters
- Examples
- metersToPixels
- Parameters
- Examples
- lngLatToTile
- Parameters
- Examples
- lngLatToGoogle
- Parameters
- Examples
- metersToTile
- Parameters
- Examples
- pixelsToMeters
- Parameters
- Examples
- pixelsToTile
- Parameters
- Examples
- tileToBBoxMeters
- Parameters
- Examples
- tileToBBox
- Parameters
- Examples
- googleToBBoxMeters
- Parameters
- Examples
- googleToBBox
- Parameters
- Examples
- tileToGoogle
- Parameters
- Examples
- googleToTile
- Parameters
- Examples
- googleToQuadkey
- Parameters
- Examples
- tileToQuadkey
- Parameters
- Examples
- quadkeyToTile
- Parameters
- Examples
- quadkeyToGoogle
- Parameters
- Examples
- bboxToMeters
- Parameters
- Examples
- validateTile
- Parameters
- Examples
- wrapTile
- Parameters
- Examples
- validateZoom
- Parameters
- Examples
- validateLngLat
- Parameters
- Examples
- maxBBox
- Parameters
- Examples
- validTile
- Parameters
- Examples
- latitude
- Parameters
- Examples
- longitude
- Parameters
- Examples
- bboxToTile
- Parameters
- Examples

$3

Hash tile for unique id key

#### Parameters

- tile Tile [x, y, z]

#### Examples

`javascript
var id = globalMercator.hash([312, 480, 4])
//=5728
`

Returns number hash

$3

Get the tile for a point at a specified zoom level


#### Parameters

- lnglat \[number, number] [Longitude, Latitude]
- zoom number Zoom level
- validate boolean validates LatLng coordinates (optional, default true)

#### Examples

`javascript
var tile = globalMercator.pointToTile([1, 1], 12)
//= [ 2059, 2036, 12 ]
`

Returns Google Google (XYZ) Tile

$3

Get the precise fractional tile location for a point at a zoom level


#### Parameters

- lnglat \[number, number] [Longitude, Latitude]
- zoom number Zoom level
- validate boolean validates LatLng coordinates (optional, default true)

#### Examples

`javascript
var tile = globalMercator.pointToTileFraction([1, 1], 12)
//= [ 2059.3777777777777, 2036.6216445333432, 12 ]
`

Returns Google Google (XYZ) Tile

$3

Converts BBox to Center

#### Parameters

- bbox BBox [west, south, east, north] coordinates
- accurancy Object { enable: true, decimal: 6} (optional, default {enable:true,decimal:6})

#### Examples

`javascript
var center = globalMercator.bboxToCenter([90, -45, 85, -50])
//= [ 87.5, -47.5 ]
`

Returns LngLat center

$3

Converts LngLat coordinates to Meters coordinates.

#### Parameters

- lnglat \[number, number] [Longitude, Latitude]
- validate boolean validates LatLng coordinates (optional, default true)
- accurancy Object { enable: true, decimal: 6} (optional, default {enable:true,decimal:1})

#### Examples

`javascript
var meters = globalMercator.lngLatToMeters([126, 37])
//=[ 14026255.8, 4439106.7 ]
`

Returns Meters Meters coordinates

$3

Converts Meters coordinates to LngLat coordinates.

#### Parameters

- meters Meters Meters in Mercator [x, y]
- accurancy Object { enable: true, decimal: 6} (optional, default {enable:true,decimal:6})

#### Examples

`javascript
var lnglat = globalMercator.metersToLngLat([14026255, 4439106])
//=[ 126, 37 ]
`

Returns LngLat LngLat coordinates

$3

Converts Meters coordinates to Pixels coordinates.

#### Parameters

- meters Meters Meters in Mercator [x, y]
- zoom number Zoom level
- tileSize number Tile size (optional, default 256)

#### Examples

`javascript
var pixels = globalMercator.metersToPixels([14026255, 4439106], 13)
//=[ 1782579.1, 1280877.3, 13 ]
`

Returns Pixels Pixels coordinates

$3

Converts LngLat coordinates to TMS Tile.

#### Parameters

- lnglat \[number, number] [Longitude, Latitude]
- zoom number Zoom level
- validate boolean validates LatLng coordinates (optional, default true)

#### Examples

`javascript
var tile = globalMercator.lngLatToTile([126, 37], 13)
//=[ 6963, 5003, 13 ]
`

Returns Tile TMS Tile

$3

Converts LngLat coordinates to Google (XYZ) Tile.

#### Parameters

- lnglat \[number, number] [Longitude, Latitude]
- zoom number Zoom level
- validate boolean validates LatLng coordinates (optional, default true)

#### Examples

`javascript
var google = globalMercator.lngLatToGoogle([126, 37], 13)
//=[ 6963, 3188, 13 ]
`

Returns Google Google (XYZ) Tile

$3

Converts Meters coordinates to TMS Tile.

#### Parameters

- meters Meters Meters in Mercator [x, y]
- zoom number Zoom level

#### Examples

`javascript
var tile = globalMercator.metersToTile([14026255, 4439106], 13)
//=[ 6963, 5003, 13 ]
`

Returns Tile TMS Tile

$3

Converts Pixels coordinates to Meters coordinates.

#### Parameters

- pixels Pixels Pixels [x, y, zoom]
- tileSize number Tile size (optional, default 256)
- accurancy Object { enable: true, decimal: 6} (optional, default {enable:true,decimal:6})

#### Examples

`javascript
var meters = globalMercator.pixelsToMeters([1782579, 1280877, 13])
//=[ 14026252.0, 4439099.5 ]
`

Returns Meters Meters coordinates

$3

Converts Pixels coordinates to TMS Tile.

#### Parameters

- pixels Pixels Pixels [x, y, zoom]
- tileSize number Tile size (optional, default 256)
- validate boolean validates Pixels coordinates (optional, default true)

#### Examples

`javascript
var tile = globalMercator.pixelsToTile([1782579, 1280877, 13])
//=[ 6963, 5003, 13 ]
`

Returns Tile TMS Tile

$3

Converts TMS Tile to bbox in Meters coordinates.

#### Parameters

- tile Tile Tile [x, y, zoom]
- tileSize number Tile size (optional, default 256)
- validate boolean validates Tile (optional, default true)
- x number TMS Tile X
- y number TMS Tile Y
- zoom number Zoom level

#### Examples

`javascript
var bbox = globalMercator.tileToBBoxMeters([6963, 5003, 13])
//=[ 14025277.4, 4437016.6, 14030169.4, 4441908.5 ]
`

Returns BBox bbox extent in [minX, minY, maxX, maxY] order

$3

Converts TMS Tile to bbox in LngLat coordinates.

#### Parameters

- tile Tile Tile [x, y, zoom]
- validate boolean validates Tile (optional, default true)
- x number TMS Tile X
- y number TMS Tile Y
- zoom number Zoom level

#### Examples

`javascript
var bbox = globalMercator.tileToBBox([6963, 5003, 13])
//=[ 125.991, 36.985, 126.035, 37.020 ]
`

Returns BBox bbox extent in [minX, minY, maxX, maxY] order

$3

Converts Google (XYZ) Tile to bbox in Meters coordinates.

#### Parameters

- google Google Google [x, y, zoom]

#### Examples

`javascript
var bbox = globalMercator.googleToBBoxMeters([6963, 3188, 13])
//=[ 14025277.4, 4437016.6, 14030169.4, 4441908.5 ]
`

Returns BBox bbox extent in [minX, minY, maxX, maxY] order

$3

Converts Google (XYZ) Tile to bbox in LngLat coordinates.

#### Parameters

- google Google Google [x, y, zoom]

#### Examples

`javascript
var bbox = globalMercator.googleToBBox([6963, 3188, 13])
//=[ 125.991, 36.985, 126.035, 37.020 ]
`

Returns BBox bbox extent in [minX, minY, maxX, maxY] order

$3

Converts TMS Tile to Google (XYZ) Tile.

#### Parameters

- tile Tile Tile [x, y, zoom]
- validate boolean validates Tile (optional, default true)

#### Examples

`javascript
var google = globalMercator.tileToGoogle([6963, 5003, 13])
//=[ 6963, 3188, 13 ]
`

Returns Google Google (XYZ) Tile

$3

Converts Google (XYZ) Tile to TMS Tile.

#### Parameters

- google Google Google [x, y, zoom]

#### Examples

`javascript
var tile = globalMercator.googleToTile([6963, 3188, 13])
//=[ 6963, 5003, 13 ]
`

Returns Tile TMS Tile

$3

Converts Google (XYZ) Tile to Quadkey.

#### Parameters

- google Google Google [x, y, zoom]

#### Examples

`javascript
var quadkey = globalMercator.googleToQuadkey([6963, 3188, 13])
//='1321102330211'
`

Returns string Microsoft's Quadkey schema

$3

Converts TMS Tile to QuadKey.

#### Parameters

- tile Tile Tile [x, y, zoom]
- validate boolean validates Tile (optional, default true)

#### Examples

`javascript
var quadkey = globalMercator.tileToQuadkey([6963, 5003, 13])
//='1321102330211'
`

Returns string Microsoft's Quadkey schema

$3

Converts Quadkey to TMS Tile.

#### Parameters

- quadkey string Microsoft's Quadkey schema

#### Examples

`javascript
var tile = globalMercator.quadkeyToTile('1321102330211')
//=[ 6963, 5003, 13 ]
`

Returns Tile TMS Tile

$3

Converts Quadkey to Google (XYZ) Tile.

#### Parameters

- quadkey string Microsoft's Quadkey schema

#### Examples

`javascript
var google = globalMercator.quadkeyToGoogle('1321102330211')
//=[ 6963, 3188, 13 ]
`

Returns Google Google (XYZ) Tile

$3

Converts BBox from LngLat coordinates to Meters coordinates

#### Parameters

- bbox BBox extent in [minX, minY, maxX, maxY] order

#### Examples

`javascript
var meters = globalMercator.bboxToMeters([ 125, 35, 127, 37 ])
//=[ 13914936.3, 4163881.1, 14137575.3, 4439106.7 ]
`

Returns BBox bbox extent in [minX, minY, maxX, maxY] order

$3

Validates TMS Tile.

#### Parameters

- tile Tile Tile [x, y, zoom]
- validate boolean validates Tile (optional, default true)

#### Examples

`javascript
globalMercator.validateTile([60, 80, 12])
//=[60, 80, 12]
globalMercator.validateTile([60, -43, 5])
//= Error: Tile must not be less than 0
globalMercator.validateTile([25, 60, 3])
//= Error: Illegal parameters for tile
`

- Throws Error Will throw an error if TMS Tile is not valid.

Returns Tile TMS Tile

$3

Wrap Tile -- Handles tiles which crosses the 180th meridian or 90th parallel

#### Parameters

- tile \[number, number, number] Tile
- zoom number Zoom Level

#### Examples

`javascript
globalMercator.wrapTile([0, 3, 2])
//= [0, 3, 2] -- Valid Tile X
globalMercator.wrapTile([4, 2, 2])
//= [0, 2, 2] -- Tile 4 does not exist, wrap around to TileX=0
`

Returns \[number, number, number] Wrapped Tile

$3

Validates Zoom level

#### Parameters

- zoom number Zoom level
- validate boolean validates Zoom level (optional, default true)

#### Examples

`javascript
globalMercator.validateZoom(12)
//=12
globalMercator.validateZoom(-4)
//= Error: cannot be less than 0
globalMercator.validateZoom(32)
//= Error: cannot be greater than 30
`

- Throws Error Will throw an error if zoom is not valid.

Returns number zoom Zoom level

$3

Validates LngLat coordinates

#### Parameters

- lnglat \[number, number] [Longitude, Latitude]
- validate boolean validates LatLng coordinates (optional, default true)

#### Examples

`javascript
globalMercator.validateLngLat([-115, 44])
//= [ -115, 44 ]
globalMercator.validateLngLat([-225, 44])
//= Error: LngLat [lng] must be within -180 to 180 degrees
`

- Throws Error Will throw an error if LngLat is not valid.

Returns LngLat LngLat coordinates

$3

Maximum extent of BBox

#### Parameters

- array (BBox | Array<BBox>) BBox [west, south, east, north]

#### Examples

`javascript
var bbox = globalMercator.maxBBox([[-20, -30, 20, 30], [-110, -30, 120, 80]])
//=[-110, -30, 120, 80]
`

Returns BBox Maximum BBox

$3

Valid TMS Tile

#### Parameters

- tile Tile Tile [x, y, zoom]

#### Examples

`javascript
globalMercator.validTile([60, 80, 12])
//= true
globalMercator.validTile([60, -43, 5])
//= false
globalMercator.validTile([25, 60, 3])
//= false
`

Returns boolean valid tile true/false

$3

Modifies a Latitude to fit within +/-90 degrees.

#### Parameters

- lat number latitude to modify

#### Examples

`javascript
globalMercator.latitude(100)
//= -80
`

Returns number modified latitude

$3

Modifies a Longitude to fit within +/-180 degrees.

#### Parameters

- lng number longitude to modify

#### Examples

`javascript
globalMercator.longitude(190)
//= -170
`

Returns number modified longitude

$3

Get the smallest tile to cover a bbox

#### Parameters

- bboxCoords
- bbox Array<number> BBox

#### Examples

`javascript
var tile = bboxToTile([-178, 84, -177, 85])
//=tile
``

Returns Array<number> tile Tile