Elevation - API Client JS

src/services/elevation.ts

MapTiler API Client JS elevation functions provide a convenient way to get elevation in meters of any place in the world. It’s possible to look up and compute the elevation:

• At a single location – at
• At multiple different locations – batch
• From a GeoJSON LineString (path) – fromLineString
• From a GeoJSON MultiLineString (composite path) – fromMultiLineString

Under the hood, the elevation feature is powered by our Elevation API and the Terrain RGB tileset:

• Functions at and batch use the Elevation API and compute the elevation on the server side.
• Functions fromLineString and fromMultiLineString fetch tiles from the Terrain RGB tileset and compute the elevation on the client side. LineString and MultiLineString data often comes from a recorded or planned route where the position points are very close to one another, and a single tile can contain elevation data for hundreds of these points. This means that the whole route can be calculated using just a few tiles, which is much more effective than sending indidivual requests to the Elevation API.

This default setup can be changed using the computeOn option, which is available for all the functions, described on this page.

Note for Node.js users

If you have implemented the elevation features in your backend using this Client JS library, we have some useful info for you. To make the library work with Node.js, you must have defined a custom bufferToPixelData function that fetches the RGB tiles and uses them to calculate the elevation. Since Client JS v2.5.0, it’s not necessary to use that function anymore. Here’s your options:

1. Discard the bufferToPixelData function. The client library will then use our Elevation API and calculate the elevation on the server side instead (meaning our MapTiler server that hosts the API endpoint). The usage will be counted in a standard way, per API request.

2. Keep using the bufferToPixelData function. You’ll continue requesting and caching the elevation tiles. The usage will be counted per tile request, unless you manually change it. We’ve added these parameters to give you control over the implementation:

   • canParsePixelData to check if elevation can be computed on the client,
   • computeOn to force elevation processing on the client (via tile requests) or on the server (via Elevation API requests).

Performance of both computation methods is comparable and you shouldn’t notice any remarkable difference if you switch from one to the other.

at

Get the elevation at a given position.

// Not mandatory, but it's to explain where the type comes from:
import { Position } from "geojson";

const montBlancPeak: Position = [6.864884, 45.832743];
const elevatedPosition = await maptilerClient.elevation.at(montBlancPeak);

Parameters

Response

The returned value is also a GeoJSON Position array but with three elements: [lng, lat, elevation].

[6.864884, 45.832743, 4805.700000000001];

More examples

Compute elevation on the client side with a specific zoom level:

// Not mandatory, but it's to explain where the type comes from:
import { Position } from "geojson";

const montBlancPeak: Position = [6.864884, 45.832743];
const elevatedPosition = await maptilerClient.elevation.at(montBlancPeak, {
  zoom: 10,
  computeOn: "client",
});

batch

Perform a batch elevation request.

// Not mandatory, but it's to explain where the type comes from:
import { Position } from "geojson";

const peaks: Position[] = [
  [6.864884, 45.832743], // Mont Blanc, Alps
  [86.925, 27.9881], // Mount Everest, Himalayas
  [-70.0109, -32.6532], // Aconcagua, Andes
  [-151.0064, 63.0695], // Denali, Alaska
  [37.3556, -3.0674], // Mount Kilimanjaro
  [42.4453, 43.3499], // Mount Elbrus, Caucasus
  [137.1595, -4.0784], // Puncak Jaya, Sudirman Range
  [-140.4055, 60.5672], // Mount Logan, Saint Elias Mountains
  [138.73111, 35.358055], // Mount Fuji
];

const elevatedPeaks = await maptilerClient.elevation.batch(peaks);

Parameters

Response

The returned value is also an Array of GeoJSON Position with the elevation: [[lng, lat, elevation], [lng, lat, elevation], ...].

[
  [6.864884, 45.832743, 4805.7],
  [86.925, 27.9881, 8718],
  [-70.0109, -32.6532, 6900.6],
  [-151.0064, 63.0695, 6177.2],
  [37.3556, -3.0674, 5835.5],
  [42.4453, 43.3499, 5409.8],
  [137.1595, -4.0784, 4771.6],
  [-140.4055, 60.5672, 5909.3],
  [138.73111, 35.358055, 3618.9],
];

fromLineString

Creates a clone of a GeoJSON LineString (deep copy with structuredClone) that contains the computed elevation as the third element of each position array ([lng, lat, alt]).

// Not mandatory, but it's to explain where the type comes from:
import { LineString } from "geojson";

const someLineString: LineString = {
  type: "LineString",
  coordinates: [
    [6.864884, 45.832743],
    [86.925, 27.9881],
    [-70.0109, -32.6532],
  ],
};

const someElevatedLineString = await maptilerClient.elevation.fromLineString(
  someLineString
);
// someElevatedLineString is also of type LineString

Parameters

Response

The returned value is also a GeoJSON LineString with the elevation.

{
  "type": "LineString",
  "coordinates": [
    [6.864884, 45.832743, 4805.7],
    [86.925, 27.9881, 8718],
    [-70.0109, -32.6532, 6900.6]
  ]
}

fromMultiLineString

Creates a clone of a GeoJSON MultiLineString (deep copy with structuredClone) that contains the computed elevation as the third element of each position array ([lng, lat, alt]).

// Not mandatory, but it's to explain where the type comes from:
import { MultiLineString } from "geojson";

const someMultiLineString: MultiLineString = {
  type: "MultiLineString",
  coordinates: [
    [
      [6.864884, 45.832743],
      [86.925, 27.9881],
      [-70.0109, -32.6532],
    ],
    [
      [-151.0064, 63.0695],
      [37.3556, -3.0674],
      [42.4453, 43.3499],
    ],
    [
      [137.1595, -4.0784],
      [-140.4055, 60.5672],
      [138.73111, 35.358055],
    ],
  ],
};

const someElevatedMultiLineString =
  await maptilerClient.elevation.fromMultiLineString(someMultiLineString);
// someElevatedMultiLineString is also of type MultiLineString

Parameters

Response

The returned value is also a GeoJSON MultiLineString with the elevation.

{
  "type": "MultiLineString",
  "coordinates": [
    [
      [6.864884, 45.832743, 4805.7],
      [86.925, 27.9881, 8718],
      [-70.0109, -32.6532, 6900.6]
    ],
    [
      [-151.0064, 63.0695, 6177.2],
      [37.3556, -3.0674, 5835.5],
      [42.4453, 43.3499, 5409.8]
    ],
    [
      [137.1595, -4.0784, 4771.6],
      [-140.4055, 60.5672, 5909.3],
      [138.73111, 35.358055, 3618.9]
    ]
  ]
}