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

$ npm install --save global-mercator

web

<script src="https://wzrd.in/standalone/global-mercator@latest"></script>

Quickstart

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[]) | 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

hash

Hash tile for unique id key

Parameters

• tile Tile [x, y, z]

Examples

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

Returns number hash

pointToTile

Get the tile for a point at a specified zoom level https://github.com/mapbox/tilebelt

Parameters

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

Examples

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

Returns Google Google (XYZ) Tile

pointToTileFraction

Get the precise fractional tile location for a point at a zoom level https://github.com/mapbox/tilebelt

Parameters

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

Examples

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

Returns Google Google (XYZ) Tile

bboxToCenter

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

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

Returns LngLat center

lngLatToMeters

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

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

Returns Meters Meters coordinates

metersToLngLat

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

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

Returns LngLat LngLat coordinates

metersToPixels

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

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

Returns Pixels Pixels coordinates

lngLatToTile

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

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

Returns Tile TMS Tile

lngLatToGoogle

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

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

Returns Google Google (XYZ) Tile

metersToTile

Converts Meters coordinates to TMS Tile.

Parameters

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

Examples

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

Returns Tile TMS Tile

pixelsToMeters

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

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

Returns Meters Meters coordinates

pixelsToTile

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

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

Returns Tile TMS Tile

tileToBBoxMeters

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

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

tileToBBox

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

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

googleToBBoxMeters

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

Parameters

• google Google Google [x, y, zoom]

Examples

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

googleToBBox

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

Parameters

• google Google Google [x, y, zoom]

Examples

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

tileToGoogle

Converts TMS Tile to Google (XYZ) Tile.

Parameters

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

Examples

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

Returns Google Google (XYZ) Tile

googleToTile

Converts Google (XYZ) Tile to TMS Tile.

Parameters

• google Google Google [x, y, zoom]

Examples

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

Returns Tile TMS Tile

googleToQuadkey

Converts Google (XYZ) Tile to Quadkey.

Parameters

• google Google Google [x, y, zoom]

Examples

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

Returns string Microsoft's Quadkey schema

tileToQuadkey

Converts TMS Tile to QuadKey.

Parameters

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

Examples

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

Returns string Microsoft's Quadkey schema

quadkeyToTile

Converts Quadkey to TMS Tile.

Parameters

• quadkey string Microsoft's Quadkey schema

Examples

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

Returns Tile TMS Tile

quadkeyToGoogle

Converts Quadkey to Google (XYZ) Tile.

Parameters

• quadkey string Microsoft's Quadkey schema

Examples

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

Returns Google Google (XYZ) Tile

bboxToMeters

Converts BBox from LngLat coordinates to Meters coordinates

Parameters

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

Examples

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

validateTile

Validates TMS Tile.

Parameters

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

Examples

globalMercator.validateTile([60, 80, 12])
//=[60, 80, 12]
globalMercator.validateTile([60, -43, 5])
//= Error: Tile <y> 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

wrapTile

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

Parameters

• tile [number, number, number] Tile
• zoom number Zoom Level

Examples

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

validateZoom

Validates Zoom level

Parameters

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

Examples

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

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

Returns number zoom Zoom level

validateLngLat

Validates LngLat coordinates

Parameters

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

Examples

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

maxBBox

Maximum extent of BBox

Parameters

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

Examples

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

Returns BBox Maximum BBox

validTile

Valid TMS Tile

Parameters

• tile Tile Tile [x, y, zoom]

Examples

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

Returns boolean valid tile true/false

latitude

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

Parameters

• lat number latitude to modify

Examples

globalMercator.latitude(100)
//= -80

Returns number modified latitude

longitude

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

Parameters

• lng number longitude to modify

Examples

globalMercator.longitude(190)
//= -170

Returns number modified longitude

bboxToTile

Get the smallest tile to cover a bbox

Parameters

• bboxCoords
• bbox Array<number> BBox

Examples

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

Returns Array<number> tile Tile