Gcoord

English | 简体中文

gcoord (geographic coordinates) is a lightweight JavaScript library for transforming coordinates between common web map coordinate reference systems. It helps normalize coordinates from GPS, Baidu Maps, AMap, Google China Maps, and other map providers.

gcoord supports coordinate arrays and GeoJSON objects, has no runtime dependencies, and works in Node.js, modern browsers, and React Native. The browser global build is about 3 KB after gzip.

For background reading, see Geographic Coordinate Systems.

Legal Notice

Before publishing, displaying, distributing, or otherwise using map data, make sure you comply with the laws and regulations that apply to your use case.

Surveying and mapping activities may not use an international coordinate system without approval.

• Surveying and Mapping Law of the People's Republic of China, Article 40 (1)

Navigation electronic maps must undergo spatial position technical processing before public publication, sale, distribution, display, or use.

• GB 20263-2006, Basic Requirements for Security Processing of Navigation Electronic Maps, 4.1

Installation

Install from npm:

npm install gcoord

Or load the browser global build with a script tag:

<script src="https://unpkg.com/gcoord@1.0.7/dist/gcoord.global.prod.js"></script>

When using a script tag, always pin an exact package version.

Import

CommonJS:

const gcoord = require('gcoord');

ES module:

import gcoord from 'gcoord';

Browser global:

window.gcoord.transform([116.403988, 39.914266], gcoord.WGS84, gcoord.BD09);

Usage

If you receive a GPS coordinate from a phone and need to display it on Baidu Maps, convert it from WGS-84 to BD-09:

const result = gcoord.transform(
  [116.403988, 39.914266], // coordinate: [longitude, latitude]
  gcoord.WGS84, // source CRS
  gcoord.BD09, // target CRS
);

console.log(result); // [116.41661560068297, 39.92196580126834]

gcoord can also transform GeoJSON objects. See the API section for details.

API

transform(input, from, to)

Transforms coordinates from one CRS to another.

Parameters

• input GeoJSON | string | Array<number>: a GeoJSON object, a GeoJSON string, or a coordinate array.
• from CRS: the source coordinate reference system.
• to CRS: the target coordinate reference system.

Returns

GeoJSON | Array<number>

Examples

// Convert a GCJ-02 coordinate to WGS-84.
const result = gcoord.transform([123, 45], gcoord.GCJ02, gcoord.WGS84);
console.log(result); // [122.99395597, 44.99804071]

// Transform coordinates inside a GeoJSON object.
const geojson = {
  type: 'Point',
  coordinates: [123, 45],
};

gcoord.transform(geojson, gcoord.GCJ02, gcoord.WGS84);
console.log(geojson.coordinates); // [122.99395597, 44.99804071]

The return type matches the input type. When the input is a GeoJSON object, transform mutates the input object in place.

CRS

The following coordinate reference systems are supported:

CRS	Coordinate format	Description
gcoord.WGS84	[lng, lat]	WGS-84, the longitude and latitude coordinates returned by GPS devices.
gcoord.GCJ02	[lng, lat]	GCJ-02, used by AMap, Google China Maps, Soso Maps, Aliyun Maps, and MapABC.
gcoord.BD09	[lng, lat]	BD-09, used by Baidu Maps.
gcoord.BD09LL	[lng, lat]	Alias of BD-09.
gcoord.BD09MC	[x, y]	BD-09 meter coordinates, used by Baidu Maps. Unit: meter.
gcoord.BD09Meter	[x, y]	Alias of BD09MC.
gcoord.Baidu	[lng, lat]	Alias of BD-09.
gcoord.BMap	[lng, lat]	Alias of BD-09.
gcoord.AMap	[lng, lat]	Alias of GCJ-02.
gcoord.WebMercator	[x, y]	Web Mercator projection, alias of EPSG3857. Unit: meter.
gcoord.WGS1984	[lng, lat]	Alias of WGS-84.
gcoord.EPSG4326	[lng, lat]	Alias of WGS-84.
gcoord.EPSG3857	[x, y]	Web Mercator projection. Unit: meter.
gcoord.EPSG900913	[x, y]	Alias of Web Mercator.

Development

npm ci
npm run lint
npm run typecheck
npm test
npm run build

The package is built with tsup, tests run with vitest, and published files are emitted to dist/.

Need More Coordinate Systems?

gcoord focuses on coordinate systems commonly used by web maps. The supported CRS list covers most web map scenarios while keeping the package small. For more specialized geodesy work, consider using proj4js.

License

MIT