Coordinates - API Client JS

MapTiler API Client JS coordinates functions provide convenient access to the details of 10 thousand coordinate reference systems (CRS) programmatically, as well as transforming coordinates from one system to another. Find more about coordinates systems at epsg.io (created by MapTiler).

Coordinates functions:

The search lets you perform a free form query to find coordinate systems.

// in an async function, or as a 'thenable':
const result = await maptilerClient.coordinates.search('pseudo-mercator');

Parameters

query
string
Can be any kind of CRS by name or code. Query string used to search the catalog. It accepts plain terms such as names of locations and key:value pairs for filtering.
options.apiKey
string?
Custom MapTiler Cloud API key to use instead of the one in global config.
options.exports
boolean?
Show exports in WKT and Proj4 notations (default: false).
options.limit
number?
Maximum number of results returned (default: 10).
options.transformations
boolean?
Show detailed transformations for each CRS (default: false).

Response

Returns a coordinates result object

{
  "results": [
    {
      "id": {
        "authority": "EPSG",
        "code": 3857
      },
      "kind": "CRS-PROJCRS",
      "name": "WGS 84 / Pseudo-Mercator",
      "exports": null,
      "unit": "metre",
      "accuracy": null,
      "area": "World between 85.06°S and 85.06°N.",
      "bbox": [
        -180,
        -85.06,
        180,
        85.06
      ],
      "deprecated": false,
      "default_transformation": null,
      "transformations": [
        9189,
        9690,
        9691,
        15960
      ]
    }
  ],
  "total": 1
}

More examples

Search for coordinate reference systems (CRS) in the specified country:

// in an async function, or as a 'thenable':
const result = await maptilerClient.coordinates.search('United Kingdom');

Search for mercator coordinate reference systems (CRS) with filtering. Only search deprecated definitions:

// in an async function, or as a 'thenable':
const result = await maptilerClient.coordinates.search('mercator deprecated:1');

Search by EPSG code:

// in an async function, or as a 'thenable':
const result = await maptilerClient.coordinates.search('code:4326');

or just the EPSG code number:

// in an async function, or as a 'thenable':
const result = await maptilerClient.coordinates.search('4326');

The transformations options retrieves a lot more details about the CRS that MapTiler API is able to transform to/from than just their IDs:

// in an async function, or as a 'thenable':
const result = await maptilerClient.coordinates.search('code:4326', {transformations: true});

Finding all resources of Finland:

// in an async function, or as a 'thenable':
const result = await maptilerClient.coordinates.search('finland deprecated:* kind:*');

Filtering resources using parameter(s):

// in an async function, or as a 'thenable':
const result = await maptilerClient.coordinates.search('Spain kind:DATUM');

Read more about searching coordinate systems on our official API documentation.

Transforming a couple of coordinates from one system to another can be challenging, for example, most countries have their own official system, yet web mapping tools are more often than not exclusive to WGS84.

If not provided, both the source (sourceCrs) and the destination (targetCrs) are default to EPSG:4326 (in other words, WGS84). Here is how to use this feature:

// in an async function, or as a 'thenable':

// Providing one coordinate to transform, with a target CRS being EPSG:9793 (RGF93 v2 / Lambert-93, France official CRS)
const resultA = await maptilerClient.coordinates.transform([1, 45], {targetCrs: 9793})

// Using the same logic, we can pass up to 50 coordinates to be transformed
const resultB = await maptilerClient.coordinates.transform([[10, 48], [1, 45]], {targetCrs: 9793})

Parameters

positions
(Array<number> | Array<Array<number>>)
Coordinates to transform. A [lon, lat] array or an array of [lon, lat] arrays.
options.apiKey
string?
Custom MapTiler Cloud API key to use instead of the one in global config.
options.operations
(number | Array<number>)?
List of codes of operations.
options.sourceCrs
number?
Source coordinate reference system (default: 4326).
options.targetCrs
number?
arget coordinate reference system (default: 4326).

Response

Returns a transform result object

{
  "transformer_selection_strategy": "auto",
  "results": [
    {
      "x": 542418.1006803319,
      "y": 6435414.747835401,
      "z": 0
    }
  ]
}

More examples

Transforming from ED50 31N to ETRS89 31N:

// in an async function, or as a 'thenable':
const results = await coordinates.transform({lng: 432648.873, lat: 4624697.432}, {sourceCrs: 23031, targetCrs: 25831});

Transforming from S-JTSK to wgs84 (default) with operation:

// in an async function, or as a 'thenable':
const results = await coordinates.transform({lng: -742792.638284, lat: -1044844.906030}, {sourceCrs: 5513, operations: 1623});

Read more about transforming coordinates on our official API documentation.