Elevation - API Client JS

MapTiler API Client JS elevation functions provide convenient access to get the elevation in meters from any location. It’s possible to look up and compute the elevation from: a single location, provide a batch of points, a GeoJSON LineString or a GeoJSON MultiLineString.

Under the hood, the elevation API is fueled by MapTiler Cloud's RGB Terrain raster tileset, which is a composite of many high-resolution DEMs from all over the world, curated and processed by our geodata team! The same dataset is also fueling our SDK's elevation (3D terrain) and the hillshading we use in many of our styles.
Note for TypeScript users: internaly, the elevation feature relies on some GeoJSON types definitions that can be found in this NPM package: @types/geojson. Namely LineString, MultiLineString and Position. It may improve your developer experience to also use these types.

Geocoding functions:

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

position
Position
WGS 84 position as [longitude, latitude]
options.apiKey
string?
Custom MapTiler Cloud API key to use instead of the one in global config.
options.zoom
number?
Zoom level to use for the terrain RGB tileset. If not provided, the highest zoom level will be used.

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

Search for results in the specified 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};

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

positions
Array<Position>
WGS 84 position as [longitude, latitude]
options.apiKey
string?
Custom MapTiler Cloud API key to use instead of the one in global config.
options.zoom
number?
Zoom level to use for the terrain RGB tileset. If not provided, the highest zoom level will be used.
options.smoothingKernelSize
number?
If provided, a median kernel of the given size will smooth the elevation to reduce very small local variations.

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],
];

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

ls
LineString
A GeoJSON LineString feature
options.apiKey
string?
Custom MapTiler Cloud API key to use instead of the one in global config.
options.zoom
number?
Zoom level to use for the terrain RGB tileset. If not provided, the highest zoom level will be used.
options.smoothingKernelSize
number?
If provided, a median kernel of the given size will smooth the elevation to reduce very small local variations.

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]
  ]
}

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

ls
MultiLineString
A GeoJSON MultiLineString feature
options.apiKey
string?
Custom MapTiler Cloud API key to use instead of the one in global config.
options.zoom
number?
Zoom level to use for the terrain RGB tileset. If not provided, the highest zoom level will be used.
options.smoothingKernelSize
number?
If provided, a median kernel of the given size will smooth the elevation to reduce very small local variations.

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]
    ]
  ]
}

To increase performance while reducing unnecessary elevation data fetching, the elevation tiles are cached. This is particularly important for the LineString and MultiLineString lookups because GeoJSON data are likely to come from a recorded or planned route, where position points are very close to one another.