Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

global-mercator

DenisCarriere10kMIT3.1.0TypeScript support: included

Tools to help with TMS, Quadkey & Google (XYZ) Tiles

gis, geo, geojs, geospatial, geography, geometry, extent, geojson, google, tms, xyz, tile, slippy, map, latlng, lnglat, latitude, longitude, bbox, pixels, meters, quadkey

readme

Global Mercator

Build Status npm version Coverage Status MIT licensed ES5

Standard - JavaScript Style Guide

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

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

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

Examples

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

Returns Array<number> tile Tile

changelog

Changelog

3.0.3 - 2017-09-29

  • Drop strict [number, number] for LngLat inputs

3.0.0 - 2017-09-29

  • Added bboxToTile
  • Support ES modules

2.8.4 - 2017-08-02

2.8.1 - 2017-07-19

  • Add wrapTile method
  • Include tests side by side with tilebelt
  • Fixed issue with tileToQuadkey
  • Drop rollup setup
  • Add Git URL repo to package.json
  • Added longitude & latitude as exposed methods
  • Dropped bbox-dateline from dependencies
  • Remove Jest in favor of a minimalistic test suite (Tap)

2.7.0 - 2017-04-19

  • Add validTile method

2.6.0 - 2017-03-20

  • Fix LatLng validation (issue with lat being a lng)

2.5.0 - 2017-03-18

  • Add minified build using Uglifyjs
  • Improve lat & lng validation
  • Add automated Table of Contents

2.4.0 - 2017-03-10

  • Remove throw Error in Lat & Lng validation process
  • Handle Lat & Lng with +/-180 degrees

2.3.0 - 2017-03-06

  • Add validate as optional false param

2.2.0 - 2017-03-04

  • Bundle to UMD
  • Modify rollup config
  • Output browser bundle to docs/

2.1.0 - 2017-02-21

  • Added maxBBox method
  • Added Benchmark performance testing

2.0.0 - 2017-02.18

  • Convert to ES5
  • Convert project to support Rollup
  • Add tileSize @param
  • Dropped Grid methods (BREAKS backwards compatibility - Major release 2.X)
  • Support browser, nodejs & commonjs

1.9.0 - 2017-02-17

  • Update fixed bbox if zoom level = 0
  • Add validation to latlng
  • Add validation to tiles

1.8.0 - 2017-01-30

  • Publish web browser support for ES6.

1.7.0 - 2017-01-24

  • Refactoring entire codebase to standard Javascript

1.6.0 - 2017-01-05

  • BBox reduced decimal precision to 6
  • bboxToCenter toFixed(6)
  • Lat & Lng decimal toFixed(6)
  • Meters toFixed(1)

1.5.0 - 2016-12-25

  • Add bboxToCenter & hash function
  • Enforce strict [number, number] instead of number[]

1.4.0 - 2016-12-4

  • Replace test tools for Jest
  • Added Circle CI testing

1.3.5 - 2016-10-25

Reduce library size by 430% (350KB to 80KB)

1.3.1 - 2016-10-14

  • Update typings to allow number[]
  • Enforcing validation with validateLngLat, validateMeters & validateTile
  • Reviewed entire documentation
  • Dropped zoom @param from functions with only LatLng & Meters.
lngLatToMeters([lng, lat, zoom])
// Changed to
lngLatToMeters([lng, lat])

metersToLngLat([x, y, zoom])
// Changed to
metersToLngLat([x, y])

1.2.0 - 2016-10-13

Added new features:

  • grid - Creates an Iterator of Tiles from a given BBox
  • gridBulk - Creates a bulk Iterator of Tiles from a given BBox
  • gridLevels - Creates a grid level pattern of arrays
  • gridCount - Counts the total amount of tiles from a given BBox

1.1.0 - 2016-10-03

  • Remove Default export
  • Modules compiles only to ES6

1.0.0 - 2016-10-01

First Stable release was created