Math - API Client JS
Some operations can be fairly repetitive: WGS84 to Mercator, WGS84 to zxy tile index, distance between two points with Haversine formula, etc. As a result, we have decided to expose a math package providing the most recurent feature, so that, just like us at MapTiler, you no longer need to copy-paste the same function from your previous project!
The math package differs from the others in the sense that it does not call the MapTiler Cloud API, instead it operates fully on the machine it’s running on.
Here are some examples:
// Not mandatory, but it's to explain where the type comes from:
import { Position } from "geojson";
// Some constants
const earthRadius = maptilerClient.math.EARTH_RADIUS;
const earthCircumference = maptilerClient.math.EARTH_CIRCUMFERENCE;
const montBlancPeakWgs84: Position = [6.864884, 45.832743];
// From WGS84 to Mercator
const montBlancPeakMerc = maptilerClient.math.wgs84ToMercator(montBlancPeakWgs84); // also of type Position
// From Mercator to WGS84
const montBlancPeakWgs84Again = maptilerClient.math.mercatorToWgs84(montBlancPeakMerc);
// A great-circle distance in meter:
const from: Position = /* ... */;
const to: Position = /* ... */;
const distance = maptilerClient.math.haversineDistanceWgs84(from, to);
// Full distance of a route made of many positions
const route: Position[] = /* ... */;
const totalDistance = maptilerClient.math.haversineCumulatedDistanceWgs84(route);
// Lon lat to tile index, given a zoom level. An [x, y] array is returned
const tileXY = maptilerClient.math.wgs84ToTileIndex(montBlancPeakWgs84, 14);
// Possible to have floating point tile indices with a third argument to `false`
// and many more!
Math functions:
- Longitude to Mercator X
- Latitude to Mercator Y
- Mercator X to Longitude
- Mercator Y to Latitude
- WGS 84 to Mercator
- Mercator to WGS 84
- Mercator to TileIndex
- WGS 84 to TileIndex
- Haversine distance WGS 84
- Haversine cumulated distance WGS 84
- Haversine intermediate WGS 84
- Wrap WGS 84
- Circumference at Latitude
- To Radians
- To Degrees
Math constants:
Convert a WGS 84 longitude to web Mercator X (west-east axis), where westmost X is 0 and eastmost X is 1.
const x = maptilerClient.math.longitudeToMercatorX(6.864884);
Parameters
| lng | WGS 84 longitude |
|---|
Response
The web Mercator X coordinate.
0.5190691222222222
Convert a WGS 84 latitude to web Mercator Y (north-south axis), where northmost Y is 0 and southmost Y is 1.
const y = maptilerClient.math.latitudeToMercatorY(45.832743);
Parameters
| lat | WGS 84 latitude |
|---|
Response
The web Mercator Y coordinate.
0.35642959038384703
Converts a Mercator X (west-east axis in [0, 1]) to WGS 84 longitude
const lng = maptilerClient.math.mercatorXToLongitude(0.51906);
Parameters
| x | Web Mercator X coordinate |
|---|
Response
The WGS 84 longitude.
6.8615999999999815
Converts a Mercator Y (north-south axis in [0, 1]) to WGS 84 latitude
const lat = maptilerClient.math.mercatorYToLatitude(0.3564295);
Parameters
| y | Web Mercator Y coordinate |
|---|
Response
The WGS 84 latitude.
45.832765671147996
Convert a WGS 84 position into a web Mercator position where north-west is [0, 0] and south-east is [1, 1].
// From WGS 84 to Mercator
const montBlancPeakMercator = maptilerClient.math.wgs84ToMercator([
6.864884, 45.832743,
]);
Parameters
| position | WGS 84 position as [longitude, latitude] |
|---|
Response
Web Mercator position as [X, Y].
[0.5190691222222221, 0.35642959038384703]
Converts a web Mercator position where north-west is [0, 0] and south-east is [1, 1] into a WGS 84.
// From WGS 84 to Mercator
const montBlancPeakMercator = maptilerClient.math.mercatorToWgs84([
0.5190691222222221, 0.35642959038384703,
]);
Parameters
| position | Web Mercator position as [X, Y] |
|---|
Response
WGS 84 position as [longitude, latitude].
[6.864883999999961, 45.832742999999994]
From a given wgs84 coordinate and a zoom level, compute the tile index. Possible to have floating point tile indices with a third argument to false.
// Not mandatory, but it's to explain where the type comes from:
import { Position } from "geojson";
const montBlancPeakWgs84: Position = [6.864884, 45.832743];
// Lon lat to tile index, given a zoom level. An [x, y] array is returned
const tileXY = maptilerClient.math.wgs84ToTileIndex(montBlancPeakWgs84, 14);
Parameters
| position | WGS 84 position as [longitude, latitude] |
|---|---|
| zoom | Zoom level |
| strict | Returns integer tile indices if true or floating-point values if false. Default true |
Response
The tile index.
[8504, 5839]
From a given mercator coordinate and a zoom level, compute the tile index. Possible to have floating point tile indices with a third argument to false.
// Not mandatory, but it's to explain where the type comes from:
import { Position } from "geojson";
const montBlancPeakMercator: Position = [
0.5190691222222221, 0.35642959038384703,
];
// X Y to tile index, given a zoom level. An [x, y] array is returned
const tileXY = maptilerClient.math.mercatorToTileIndex(
montBlancPeakMercator,
14
);
Parameters
| position | Mercator coordinates (north-west is [0, 0], sourth-east is [1, 1]) |
|---|---|
| zoom | Zoom level |
| strict | Returns integer tile indices if true or floating-point values if false. Default true |
Response
The tile index.
[8504, 5839]
Gives the distance in meters between two positions using the Haversine Formula.
// Not mandatory, but it's to explain where the type comes from:
import { Position } from "geojson";
const from: Position = [-73.784351, 40.646522]; //NY JFK
const to: Position = [-0.457907, 51.469943]; //London LHR
const distance = maptilerClient.math.haversineDistanceWgs84(from, to);
Parameters
| from | WGS 84 position as [longitude, latitude] |
|---|---|
| to | WGS 84 position as [longitude, latitude] |
Response
The distance in meters.
5539832.524944868
haversineCumulatedDistanceWgs84
Compute the cumulated distance for each position of an array of positions. For I positions, there are I-1 distance, hence the distance at i corresponds to the distance from the (i-1)th position to ith.
// Not mandatory, but it's to explain where the type comes from:
import { Position } from "geojson";
const jfk: Position = [-73.784351, 40.646522]; //NY JFK
const lhr: Position = [-0.457907, 51.469943]; //London LHR
const cai: Position = [31.413174, 30.115137]; //Cairo CAI
const syd: Position = [151.179192, -33.944357]; //Sydney SYD
const distance = maptilerClient.math.haversineCumulatedDistanceWgs84([
jfk,
lhr,
cai,
syd,
]);
Parameters
Response
Array of cumulated distances in meters.
[0, 5539832.524944868, 9073249.033641862, 23475878.672752075]
Compute an intermediate point between two reference points using the Haversine formula. If the ratio is 0, the returned position is pos1. If the ratio is 1, the returned position is pos2. If the ratio is 0.5, the returned position is halfway pos1 pos2 in distance.
// Not mandatory, but it's to explain where the type comes from:
import { Position } from "geojson";
const pos1: Position = [-73.784351, 40.646522]; //NY JFK
const pos2: Position = [-0.457907, 51.469943]; //London LHR
const point = maptilerClient.math.haversineIntermediateWgs84(pos1, pos2, 0.5);
Parameters
| pos1 | WGS 84 position as [longitude, latitude] |
|---|---|
| pos2 | WGS 84 position as [longitude, latitude] |
| ratio | Ratio distance between two reference points. Values between [0, 1] |
Response
Position between the two reference points.
[-41.30613130024724, 52.21970518469531]
The circumference at a line of latitude in meters.
const circ = maptilerClient.math.circumferenceAtLatitude(40.646522);
Parameters
| lat | WGS 84 latitude |
|---|
Response
The circumference in meters.
30372642.068593252
Returns a position that has longitude in [-180, 180].
// Not mandatory, but it's to explain where the type comes from:
import { Position } from "geojson";
const pos1: Position = [-220.246010,35.686302]; //Tokyo
const point = maptilerClient.math.wrapWgs84(pos1);
Parameters
| position | WGS 84 position as [longitude, latitude] |
|---|
Response
Position with longitude in [-180, 180].
[139.75399, 35.686302]
Converts a degree angle into a radian angle.
const radian = maptilerClient.math.toRadians(40);
Parameters
| degrees | A degree angle |
|---|
Response
A radian angle.
0.6981317007977318
Converts a radian angle to a degree angle.
const degrees = maptilerClient.math.toDegrees(0.6981317007977318);
Parameters
| radians | A radian angle |
|---|
Response
A degree angle.
40
The average radius of the Earth in meters
const earthRadius = maptilerClient.math.EARTH_RADIUS;
The average circumference of the Earth in meters
const earthCircumference = maptilerClient.math.EARTH_CIRCUMFERENCE;
