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

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

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)

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]

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)

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