@maptiler/client 3.2.0-rc.4 → 3.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/readme.md CHANGED
@@ -3,12 +3,14 @@
3
3
  # API Client Library for JavaScript / TypeScript
4
4
 
5
5
  The **MapTiler Client JS** exposes a number of handy functions that wrap API calls to [MapTiler Cloud API services](https://docs.maptiler.com/cloud/api), such as:
6
+
6
7
  - [Geocoding forward and reverse](#-geocoding)
7
8
  - [Geolocation from visitor's IP address](#%EF%B8%8F%E2%80%8D%EF%B8%8F-geolocation)
8
9
  - [Coordinate systems search and transform](#-coordinates)
9
10
  - [User data fetching as GeoJSON](#-data)
10
11
  - [Static maps of all sorts](#%EF%B8%8F-static-maps)
11
12
  - [Elevation lookup with batch features](#%EF%B8%8F-elevation)
13
+ - [Routing directions for car, truck, bicycle and pedestrian](#-routing)
12
14
 
13
15
  The project is entirely written in TypeScript and all the function arguments are nicely documented and typed.
14
16
 
@@ -20,8 +22,7 @@ The project is entirely written in TypeScript and all the function arguments are
20
22
  - Runs: in Node.js or in browser
21
23
  - Open source license
22
24
 
23
- [![](https://img.shields.io/npm/v/@maptiler/client?style=for-the-badge&labelColor=D3DBEC&color=f2f6ff&logo=npm&logoColor=333359)](https://www.npmjs.com/package/@maptiler/client) ![](https://img.shields.io/badge/-white?style=for-the-badge&logo=javascript)![](https://img.shields.io/badge/-white?style=for-the-badge&logo=typescript)
24
- ---
25
+ ## [![](https://img.shields.io/npm/v/@maptiler/client?style=for-the-badge&labelColor=D3DBEC&color=f2f6ff&logo=npm&logoColor=333359)](https://www.npmjs.com/package/@maptiler/client) ![](https://img.shields.io/badge/-white?style=for-the-badge&logo=javascript)![](https://img.shields.io/badge/-white?style=for-the-badge&logo=typescript)
25
26
 
26
27
  📖 [Documentation](https://docs.maptiler.com/cloud/api/)   📦 [NPM Package](https://www.npmjs.com/package/@maptiler/client)   🌐 [Website](https://docs.maptiler.com/client-js/)   🔑 [Get API Key](https://cloud.maptiler.com/account/keys/)
27
28
 
@@ -54,19 +55,20 @@ npm install --save @maptiler/client
54
55
  ```
55
56
 
56
57
  ### From NodeJS
57
- NodeJS includes a stable `fetch()` function only from version *18*, and this client does not contain a polyfill. If the `fetch()` function exists (browser or Node >= 18) then it is going to be resolved automatically. Yet, a custom `fetch()` function can be provided to the `config` object for Node < 18.
58
58
 
59
- In [this NodeJS example](examples/test-node.js), you can see that the package [Node Fetch](https://www.npmjs.com/package/node-fetch) has been `npm install`ed and is passed to the config object of the *MapTiler Client*.
59
+ NodeJS includes a stable `fetch()` function only from version _18_, and this client does not contain a polyfill. If the `fetch()` function exists (browser or Node >= 18) then it is going to be resolved automatically. Yet, a custom `fetch()` function can be provided to the `config` object for Node < 18.
60
+
61
+ In [this NodeJS example](https://github.com/maptiler/maptiler-client-js/blob/main/examples/test-node.js), you can see that the package [Node Fetch](https://www.npmjs.com/package/node-fetch) has been `npm install`ed and is passed to the config object of the _MapTiler Client_.
60
62
 
61
63
  ```js
62
64
  import {
63
65
  config,
64
66
  // ...
65
- } from '@maptiler/client';
67
+ } from "@maptiler/client";
66
68
 
67
69
  // For this example to work, you must bring your own node-compatible fetch,
68
70
  // unles you are using a version of Nodejs that already contains fetch (>=18)
69
- import fetch from 'node-fetch';
71
+ import fetch from "node-fetch";
70
72
 
71
73
  config.fetch = fetch;
72
74
 
@@ -79,7 +81,7 @@ config.fetch = fetch;
79
81
 
80
82
  ```ts
81
83
  // Import the whole library
82
- import * as maptilerClient from '@maptiler/client';
84
+ import * as maptilerClient from "@maptiler/client";
83
85
 
84
86
  // Or import only the bits you need
85
87
  import {
@@ -90,8 +92,9 @@ import {
90
92
  data,
91
93
  staticMaps,
92
94
  elevation,
95
+ routing,
93
96
  math,
94
- } from '@maptiler/client';
97
+ } from "@maptiler/client";
95
98
  ```
96
99
 
97
100
  <br>
@@ -106,7 +109,7 @@ The [examples](examples/) folder includes usages for **NodeJS**, **browser with
106
109
 
107
110
  For detailed guides, API reference, and advanced examples, visit our comprehensive documentation:
108
111
 
109
- [API documentation](https://docs.maptiler.com/cloud/api/)
112
+ [API documentation](https://docs.maptiler.com/client-js/api/)
110
113
 
111
114
  ### Easy access to MapTiler API
112
115
 
@@ -116,35 +119,47 @@ Here is the list of service wrapper functions that are built-in:
116
119
 
117
120
  > ✅ Please, use geocoding functions only from client-side (browser) and do not 🚫 **store** or **redistribute** MapTiler Cloud API data. In case of doubt, consult the [terms](https://www.maptiler.com/cloud/terms/#explicitly-prohibited-use) ⚖️
118
121
 
119
- Read more about geocoding, including forward, reverse, batch, and usage examples, in our [Geocoding API documentation](https://docs.maptiler.com/cloud/api/geocoding/).
120
-
121
122
  #### Forward
122
123
 
123
124
  You want to know the longitude and latitude of a specific place, use the forward geocoding:
125
+
124
126
  ```ts
125
127
  // in an async function, or as a 'thenable':
126
- const result = await maptilerClient.geocoding.forward('paris');
128
+ const result = await maptilerClient.geocoding.forward("paris");
127
129
  ```
130
+
128
131
  You can provide some options, such as:
132
+
129
133
  - the proximity, given a lon-lat position, to sort the results
130
134
  - one of more languages to get the results into
131
135
  - a bounding geo box, to restrict the search to a given window
132
136
 
137
+ Read more about forward geocoding, as well as feature ID query and batch forward geocoding, on our [official documentation](https://docs.maptiler.com/client-js/api/variables/services_geocoding.geocoding/#forward).
138
+
133
139
  #### Reverse
134
140
 
135
141
  You want to know the name of a place, given a longitude-latitude? Use the reverse geocoding:
142
+
136
143
  ```ts
137
144
  // in an async function, or as a 'thenable':
138
145
  const result = await maptilerClient.geocoding.reverse([6.249638, 46.402056]);
139
146
  ```
147
+
140
148
  The same option object as the forward geocoding can be provided.
141
149
 
150
+ Read more about reverse geocoding on our [official documentation](https://docs.maptiler.com/client-js/api/variables/services_geocoding.geocoding/#reverse).
151
+
142
152
  #### Language
143
153
 
144
- For both *forward* and *reverse* geocoding, this library provides a list of supported languages as shorthands that include [ISO language codes](https://en.wikipedia.org/wiki/ISO_639-1). The result will be provided in multiple languages if the `language` options are an array:
154
+ For both _forward_ and _reverse_ geocoding, this library provides a list of supported languages as shorthands that include [ISO language codes](https://en.wikipedia.org/wiki/ISO_639-1). The result will be provided in multiple languages if the `language` options are an array:
145
155
 
146
156
  ```ts
147
- const result = await maptilerClient.geocoding.forward('paris', {language: [maptilerClient.Language.SPANISH, maptilerClient.geocoding.Language.KOREAN]})
157
+ const result = await maptilerClient.geocoding.forward("paris", {
158
+ language: [
159
+ maptilerClient.Language.SPANISH,
160
+ maptilerClient.geocoding.Language.KOREAN,
161
+ ],
162
+ });
148
163
  ```
149
164
 
150
165
  The special language `AUTO` will detect the platform/browser preferred language.
@@ -158,11 +173,14 @@ The geolocation service provides location information of a visitor using its IP
158
173
  The geolocation uses the IP address of a visitor to provide information about their location, such as city, region, country, timezone, etc. The precision is lower than GPS, but it does not require visitors to explicitly enable the location service from their web browser.
159
174
 
160
175
  There is only a single function:
176
+
161
177
  ```ts
162
178
  // in an async function, or as a 'thenable':
163
179
  const result = await maptilerClient.geolocation.info();
164
180
  ```
165
181
 
182
+ Read more about geolocation on our [official documentation](https://docs.maptiler.com/client-js/api/variables/services_geolocation.geolocation/).
183
+
166
184
  ### 🌐 Coordinates
167
185
 
168
186
  If you are already familiar with [epsg.io](https://epsg.io/) (created by MapTiler), then you may find it convenient to access the details of more than 10 thousands of coordinate reference systems (CRS) programmatically, as well as transforming coordinates from one system to another!
@@ -170,6 +188,7 @@ If you are already familiar with [epsg.io](https://epsg.io/) (created by MapTile
170
188
  #### Search
171
189
 
172
190
  The `search` lets you perform a query in a free form fashion. Here are some examples:
191
+
173
192
  ```ts
174
193
  // in an async function, or as a 'thenable':
175
194
  const resultA = await maptilerClient.coordinates.search('mercator');
@@ -180,6 +199,8 @@ const resultD = await maptilerClient.coordinates.search('code:4326', {transforma
180
199
 
181
200
  The `transformations` options retrieve a lot more details about the CRS that MapTiler API is able to transform to/from than just their IDs.
182
201
 
202
+ Read more about searching coordinate systems in our [official documentation](https://docs.maptiler.com/client-js/api/variables/services_coordinates.coordinates/#search).
203
+
183
204
  #### Transform
184
205
 
185
206
  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](https://epsg.io/4326).
@@ -190,35 +211,48 @@ If not provided, both the source (`sourceCrs`) and the destination (`targetCrs`)
190
211
  // in an async function, or as a 'thenable':
191
212
 
192
213
  // Providing one coordinate to transform, with a target CRS being EPSG:9793 (RGF93 v2 / Lambert-93, France official CRS)
193
- const resultA = await maptilerClient.coordinates.transform([1, 45], {targetCrs: 9793})
214
+ const resultA = await maptilerClient.coordinates.transform([1, 45], {
215
+ targetCrs: 9793,
216
+ });
194
217
 
195
218
  // Using the same logic, we can pass up to 50 coordinates to be transformed
196
- const resultB = await maptilerClient.coordinates.transform([[10, 48], [1, 45]], {targetCrs: 9793})
219
+ const resultB = await maptilerClient.coordinates.transform(
220
+ [
221
+ [10, 48],
222
+ [1, 45],
223
+ ],
224
+ { targetCrs: 9793 },
225
+ );
197
226
  ```
198
227
 
228
+ Read more about transforming coordinates on our [official documentation](https://docs.maptiler.com/client-js/api/variables/services_coordinates.coordinates/#transform).
229
+
199
230
  ### 💽 Data
200
231
 
201
- MapTiler Cloud give its users the possibility to [upload and create data](https://cloud.maptiler.com/data/), manually with a user interface or by uploading a GPX, GeoJSON, KML or shp file. A unique ID is associated with each dataset so that we can later on access it programmatically to retrieve a GeoJSON equivalent of it:
232
+ MapTiler Cloud give its users the possibility to [upload and create data](https://cloud.maptiler.com/data/), manually with a user interface or by uploading a GPX, GeoJSON, KML or zipped SHP file. A unique ID is associated with each dataset so that we can later on access it programmatically to retrieve a GeoJSON equivalent of it:
202
233
 
203
234
  ```ts
204
235
  // in an async function, or as a 'thenable':
205
- const result = await maptilerClient.data.get('my-dataset-unique-id')
236
+ const result = await maptilerClient.data.get("my-dataset-unique-id");
206
237
  ```
207
238
 
208
239
  Since the result is a GeoJSON, it can easily be added to a `map` with `.addSource()` and `.addLayer()`.
209
240
 
241
+ Read more about fetching your own data on our [official documentation](https://docs.maptiler.com/client-js/api/variables/services_data.data/).
242
+
210
243
  ### 🗺️ Static maps
211
244
 
212
245
  > ✅ Please, use static maps URLs only from client side `<img>` elements, and do not 🚫 store or redistribute the static map files. In case of doubt, consult the [terms](https://www.maptiler.com/cloud/terms/#explicitly-prohibited-use) ⚖️
213
246
 
214
247
  Maptiler Cloud provides many possibilities for creating static maps as PNG, JPEG or WebP images. They all offer the possibilities to:
248
+
215
249
  - Choose from one of the MapTiler styles or your own
216
250
  - Add markers with a custom icon (or default icon with custom color)
217
251
  - Add path or polygon, with a parametric line width and color and a parametric filling color
218
252
 
219
253
  Three modes are available: `centered`, `bounded` and `automatic`.
220
254
 
221
- > 📣 *__important:__* <span style="text-decoration: underline">only image **URLs** are returned.</span>
255
+ > 📣 _**important:**_ <span style="text-decoration: underline">only image **URLs** are returned.</span>
222
256
  > Contrary to the other functions of this library, the static map functions **do not** perform any query to MapTiler Cloud API, instead they build the image URL for you to use in `<img>` elements.
223
257
 
224
258
  #### Map Styles
@@ -227,39 +261,50 @@ In the following static map functions, the `option` object features a `style` pr
227
261
 
228
262
  - `MapStyle.STREETS`, reference style for navigation and city exploration
229
263
  - `MapStyle.STREETS.DARK` (variant)
230
- - `MapStyle.STREETS.LIGHT` (variant)
231
264
  - `MapStyle.STREETS.PASTEL` (variant)
265
+ - `MapStyle.SATELLITE` reference style satellite and airborne imagery
266
+ - `MapStyle.SATELLITE.DARK` (variant)
267
+ - `MapStyle.HYBRID` reference style satellite and airborne imagery with labels
268
+ - `MapStyle.HYBRID.DARK` (variant)
232
269
  - `MapStyle.OUTDOOR` reference style for adventure
270
+ - `MapStyle.OUTDOOR.DARK` (variant)
271
+ - `MapStyle.WINTER` reference style for winter adventure
272
+ - `MapStyle.WINTER.DARK` (variant)
233
273
  - `MapStyle.DATAVIZ`, the perfect style for data visualization, with very little noise
234
274
  - `MapStyle.DATAVIZ.DARK` (variant)
235
275
  - `MapStyle.DATAVIZ.LIGHT` (variant)
236
- - `MapStyle.BACKDROP`, the perfect style for data visualization, with very little noise
276
+ - `MapStyle.BACKDROP`, great style for data visualization when hillshading matters!
237
277
  - `MapStyle.BACKDROP.DARK` (variant)
238
278
  - `MapStyle.BACKDROP.LIGHT` (variant)
239
- - `MapStyle.WINTER` reference style for winter adventure
240
- - `MapStyle.SATELLITE` reference style satellite and airborne imagery (no variants)
241
- - `MapStyle.HYBRID` reference style satellite and airborne imagery with labels (no variants)
242
- - `MapStyle.BASIC` reference style for minimalist design and general purpose
243
- - `MapStyle.BASIC.DARK` (variant)
244
- - `MapStyle.BASIC.LIGHT` (variant)
245
- - `MapStyle.BRIGHT` reference style for high contrast navigation
279
+ - `MapStyle.BASE` reference style for minimalist design and general purpose
280
+ - `MapStyle.BASE.DARK` (variant)
281
+ - `MapStyle.BASE.LIGHT` (variant)
282
+ - `MapStyle.BRIGHT` reference style for high-contrast navigation
246
283
  - `MapStyle.BRIGHT.DARK` (variant)
247
284
  - `MapStyle.BRIGHT.LIGHT` (variant)
248
285
  - `MapStyle.BRIGHT.PASTEL` (variant)
249
286
  - `MapStyle.TOPO` reference style for topographic study
250
- - `MapStyle.TOPO.SHINY` (variant)
287
+ - `MapStyle.TOPO.DARK` (variant)
251
288
  - `MapStyle.TOPO.PASTEL` (variant)
252
289
  - `MapStyle.TOPO.TOPOGRAPHIQUE` (variant)
253
- - `MapStyle.VOYAGER` reference style for stylish yet minimalist maps
290
+ - `MapStyle.VOYAGER` reference style for stylish yet minimalist maps (deprecated, with all its variants)
254
291
  - `MapStyle.VOYAGER.DARK` (variant)
255
292
  - `MapStyle.VOYAGER.LIGHT` (variant)
256
293
  - `MapStyle.VOYAGER.VINTAGE` (variant)
257
- - `MapStyle.TONER` reference style for very high contrast stylish maps
294
+ - `MapStyle.TONER` reference style for very high contrast stylish maps (deprecated, with all its variants)
258
295
  - `MapStyle.TONER.BACKGROUND` (variant)
259
296
  - `MapStyle.TONER.LITE` (variant)
260
297
  - `MapStyle.TONER.LINES` (variant)
261
- - `MapStyle.OPENSTREETMAP` (reference style, this one does not have any variants)
262
- - `MapStyle.OCEAN` (reference style, this one does not have any variants)
298
+ - `MapStyle.OCEAN` reference style with bathymetric highlights
299
+ - `MapStyle.OCEAN.DARK` (variant)
300
+ - `MapStyle.LANDSCAPE` reference style terrain map for data overlays and visualisations
301
+ - `MapStyle.LANDSCAPE.DARK` (variant)
302
+ - `MapStyle.LANDSCAPE.VIVID` (variant)
303
+ - `MapStyle.AQUARELLE` reference style watercolor map for creative use
304
+ - `MapStyle.AQUARELLE.DARK` (variant)
305
+ - `MapStyle.AQUARELLE.VIVID` (variant)
306
+ - `MapStyle.OPENSTREETMAP` (reference style)
307
+ - `MapStyle.OPENSTREETMAP.DARK` (variant)
263
308
 
264
309
  #### Centered static maps
265
310
 
@@ -269,11 +314,11 @@ Note that if a path or markers are provided, the framing of the map will not aut
269
314
  ```ts
270
315
  const imageLink = maptilerClient.staticMaps.centered(
271
316
  // center position (Boston)
272
- [-71.06080, 42.362114],
317
+ [-71.0608, 42.362114],
273
318
 
274
319
  // zoom level
275
- 12.5,
276
-
320
+ 12.5,
321
+
277
322
  // Options
278
323
  {
279
324
  // Request a hiDPI/Retina image
@@ -285,10 +330,11 @@ const imageLink = maptilerClient.staticMaps.centered(
285
330
 
286
331
  // Map style
287
332
  style: maptilerClient.MapStyle.OUTDOOR,
288
- });
333
+ },
334
+ );
289
335
  ```
290
336
 
291
- Read more about centered static maps in our official [Static maps API documentation](https://docs.maptiler.com/cloud/api/static-maps/#center-based-image).
337
+ Read more about centered static maps on our [official documentation](https://docs.maptiler.com/client-js/api/variables/services_staticMaps.staticMaps/#centered).
292
338
 
293
339
  #### Bounded static maps
294
340
 
@@ -298,10 +344,10 @@ This type of map requires a bounding box made of two points: the south-west boun
298
344
  const imageLink = maptilerClient.staticMaps.bounded(
299
345
  // The bounding box on Europe
300
346
  [
301
- -24, // west bound (min x)
347
+ -24, // west bound (min x)
302
348
  34.5, // south bound (min y)
303
- 32, // east bound (max x)
304
- 71, // north bound (max y)
349
+ 32, // east bound (max x)
350
+ 71, // north bound (max y)
305
351
  ],
306
352
 
307
353
  // Options
@@ -313,25 +359,24 @@ const imageLink = maptilerClient.staticMaps.bounded(
313
359
 
314
360
  // Extra space that will be added around the bounding box, in percentage
315
361
  // (0.1 = 10% is actually the default)
316
- padding: 0.1
317
- });
362
+ padding: 0.1,
363
+ },
364
+ );
318
365
  ```
319
366
 
320
367
  Since the zoom level cannot be provided, the level of detail is dictated by the size of the output image. Here is an example:
321
368
 
322
- | `2048 x 2048` | `1024 x 1024` |
323
- | :-----------: | :-----------: |
324
- | ![](images/screenshots/static-bounded-europe-2048.png) | ![](images/screenshots/static-bounded-europe-1024.png) |
369
+ | `2048 x 2048` | `1024 x 1024` |
370
+ | :-----------------------------------------------------: | :-----------------------------------------------------: |
371
+ | ![](images/screenshots/static-bounded-europe-2048.webp) | ![](images/screenshots/static-bounded-europe-1024.webp) |
325
372
 
326
373
  As you may notice, the geo bounding box could have very different proportions than the output image size. In the following example, we place the very same bounding box around Portugal, which has a this particular strip looking shape. We also add a `path` that repeats exactly the same bounding box to show the difference between the provided bounding box and the final image. We kept the default padding of 10%:
327
374
 
375
+ | `2048 x 2048` | `1024 x 2048` |
376
+ | :------------------------------------------------------------: | :------------------------------------------------------------: |
377
+ | ![](images/screenshots/static-bounded-portugal-2048x2048.webp) | ![](images/screenshots/static-bounded-portugal-1024x2048.webp) |
328
378
 
329
- | `2048 x 2048` | `1024 x 2048` |
330
- | :-----------: | :-----------: |
331
- | ![](images/screenshots/static-bounded-portugal-2048x2048.png) | ![](images/screenshots/static-bounded-portugal-1024x2048.png) |
332
-
333
-
334
- Read more about bounded static maps on our official [API documentation](https://docs.maptiler.com/cloud/api/static-maps/#bounds-based-image).
379
+ Read more about bounded static maps on our [official documentation](https://docs.maptiler.com/client-js/api/variables/services_staticMaps.staticMaps/#bounded).
335
380
 
336
381
  #### Automatic static maps
337
382
 
@@ -341,11 +386,14 @@ In the following example, we are going to load a cycling track recorded by one o
341
386
 
342
387
  ```ts
343
388
  // Fetching the GeoJSON
344
- const bikeTrack = await maptilerClient.data.get('the-id-of-a-bike-track-in-montreal');
389
+ const bikeTrack = await maptilerClient.data.get(
390
+ "the-id-of-a-bike-track-in-montreal",
391
+ );
345
392
 
346
393
  // Extracting the track points with the shape [[lng, lat], [lng, lat], ...]
347
- const trackPoints = bikeTrack.features[0].geometry.coordinates[0]
348
- .map(p => p.slice(0, 2));
394
+ const trackPoints = bikeTrack.features[0].geometry.coordinates[0].map((p) =>
395
+ p.slice(0, 2),
396
+ );
349
397
 
350
398
  const imageLink = maptilerClient.staticMaps.automatic({
351
399
  // hiDPI/Retina precision
@@ -353,29 +401,29 @@ const imageLink = maptilerClient.staticMaps.automatic({
353
401
 
354
402
  // A fairly large output image
355
403
  width: 2048,
356
- height: 1024 ,
404
+ height: 1024,
357
405
 
358
406
  // A grey style on which the track will pop!
359
- style: maptilerClient.MapStyle.STREETS.LIGHT,
407
+ style: maptilerClient.MapStyle.BASE.LIGHT,
360
408
 
361
409
  // Draw a path with the trackpoints
362
410
  path: trackPoints,
363
411
 
364
412
  // Adding a marker for the starting point, with a custom color (array of shape [lng, lat, color])
365
- marker: [trackPoints[0][0], trackPoints[0][1], '#0a0'],
413
+ marker: [trackPoints[0][0], trackPoints[0][1], "#0a0"],
366
414
 
367
415
  // Showing the track in red
368
- pathStrokeColor: 'red',
416
+ pathStrokeColor: "red",
369
417
  });
370
418
  ```
371
419
 
372
420
  And voila!
373
421
 
374
- ![static map with bike path](images/screenshots/static-with-path.png)
422
+ ![static map with bike path](images/screenshots/static-with-path.webp)
375
423
 
376
- > 📣 *__Note:__* The GeoJSON for this track contains 9380 pairs of coordinates, which is a lot! In order to send the track to MapTiler Cloud static maps API, the client simplifies the long paths while keeping a high degree of precision using a very fast [Ramer-Douglas-Peucker algorithm](https://en.wikipedia.org/wiki/Ramer%E2%80%93Douglas%E2%80%93Peucker_algorithm).
424
+ > 📣 _**Note:**_ The GeoJSON for this track contains 9380 pairs of coordinates, which is a lot! In order to send the track to MapTiler Cloud static maps API, the client simplifies the long paths while keeping a high degree of precision using a very fast [Ramer-Douglas-Peucker algorithm](https://en.wikipedia.org/wiki/Ramer%E2%80%93Douglas%E2%80%93Peucker_algorithm).
377
425
 
378
- Read more about bounded static maps on our official [API documentation](https://docs.maptiler.com/cloud/api/static-maps/#auto-fitted-image).
426
+ Read more about automatic bounded static maps on our [official documentation](https://docs.maptiler.com/client-js/api/variables/services_staticMaps.staticMaps/#automatic).
379
427
 
380
428
  ### 🏔️ Elevation
381
429
 
@@ -383,7 +431,7 @@ With the elevation API, it's possible to get the elevation in meters from any lo
383
431
 
384
432
  > ℹ️ 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.
385
433
 
386
- > 📣 Note for **TypeScript** users: internally, the elevation feature relies on some *GeoJSON* type 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.
434
+ > 📣 Note for **TypeScript** users: internally, the elevation feature relies on some _GeoJSON_ type 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.
387
435
 
388
436
  Let's see how to use it:
389
437
 
@@ -396,7 +444,10 @@ import { Position } from "geojson";
396
444
  const montBlancPeak: Position = [6.864884, 45.832743];
397
445
  const elevatedPosition = await maptilerClient.elevation.at(montBlancPeak);
398
446
  ```
399
- The returned value is also a *GeoJSON* `Position` array, but with three elements: `[lng, lat, elevation]`.
447
+
448
+ The returned value is also a _GeoJSON_ `Position` array, but with three elements: `[lng, lat, elevation]`.
449
+
450
+ Read more about elevation lookup for a single location in our [official documentation](https://docs.maptiler.com/client-js/api/variables/services_elevation.elevation/#at).
400
451
 
401
452
  #### Batch mode
402
453
 
@@ -405,67 +456,221 @@ The returned value is also a *GeoJSON* `Position` array, but with three elements
405
456
  import { Position } from "geojson";
406
457
 
407
458
  const peaks: Position[] = [
408
- [6.864884, 45.832743], // Mont Blanc, Alps
409
- [86.9250, 27.9881], // Mount Everest, Himalayas
410
- [-70.0109, -32.6532], // Aconcagua, Andes
411
- [-151.0064, 63.0695], // Denali, Alaska
412
- [37.3556, -3.0674], // Mount Kilimanjaro
413
- [42.4453, 43.3499], // Mount Elbrus, Caucasus
414
- [137.1595, -4.0784], // Puncak Jaya, Sudirman Range
415
- [-140.4055, 60.5672], // Mount Logan, Saint Elias Mountains
416
- [138.73111, 35.358055], // Mount Fuji
459
+ [6.864884, 45.832743], // Mont Blanc, Alps
460
+ [86.925, 27.9881], // Mount Everest, Himalayas
461
+ [-70.0109, -32.6532], // Aconcagua, Andes
462
+ [-151.0064, 63.0695], // Denali, Alaska
463
+ [37.3556, -3.0674], // Mount Kilimanjaro
464
+ [42.4453, 43.3499], // Mount Elbrus, Caucasus
465
+ [137.1595, -4.0784], // Puncak Jaya, Sudirman Range
466
+ [-140.4055, 60.5672], // Mount Logan, Saint Elias Mountains
467
+ [138.73111, 35.358055], // Mount Fuji
417
468
  ];
418
469
 
419
470
  const elevatedPeaks = await maptilerClient.elevation.batch(peaks);
420
471
  ```
421
472
 
473
+ Read more about elevation lookup for a batch of locations in our [official documentation](https://docs.maptiler.com/client-js/api/variables/services_elevation.elevation/#batch).
474
+
422
475
  #### From a GeoJSON LineString
423
476
 
424
- In the *GeoJSON* LineString case, it clones the entire structure and the positions arrays of the clone will contain three elements: `[lng, lat, elevation]`. The original LineString is not mutated nor pointed at.
477
+ In the _GeoJSON_ LineString case, it clones the entire structure and the positions arrays of the clone will contain three elements: `[lng, lat, elevation]`. The original LineString is not mutated nor pointed at.
425
478
 
426
479
  ```ts
427
480
  // Not mandatory, but it's to explain where the type comes from:
428
481
  import { LineString } from "geojson";
429
482
 
430
-
431
483
  const someLineString: LineString = {
432
484
  type: "LineString",
433
- coordinates: [[6.864884, 45.832743], [86.9250, 27.9881], [-70.0109, -32.6532]]
485
+ coordinates: [
486
+ [6.864884, 45.832743],
487
+ [86.925, 27.9881],
488
+ [-70.0109, -32.6532],
489
+ ],
434
490
  };
435
491
 
436
- const someElevatedLineString = await maptilerClient.elevation.fromLineString(someLineString);
492
+ const someElevatedLineString =
493
+ await maptilerClient.elevation.fromLineString(someLineString);
437
494
  // someElevatedLineString is also of type LineString
438
495
  ```
439
496
 
497
+ Read more about elevation lookup for a `LineString` in our [official documentation](https://docs.maptiler.com/client-js/api/variables/services_elevation.elevation/#fromlinestring).
498
+
440
499
  #### From a GeoJSON MultiLineString
441
500
 
442
- In the *GeoJSON* MultiLineString case, it clones the entire structure and the positions arrays of the clone will contain three elements: `[lng, lat, elevation]`. The original MultiLineString is not mutated nor pointed at.
501
+ In the _GeoJSON_ MultiLineString case, it clones the entire structure and the positions arrays of the clone will contain three elements: `[lng, lat, elevation]`. The original MultiLineString is not mutated nor pointed at.
443
502
 
444
503
  ```ts
445
504
  // Not mandatory, but it's to explain where the type comes from:
446
505
  import { MultiLineString } from "geojson";
447
506
 
448
-
449
507
  const someMultiLineString: MultiLineString = {
450
508
  type: "LineString",
451
509
  coordinates: [
452
- [[6.864884, 45.832743], [86.9250, 27.9881], [-70.0109, -32.6532]],
453
- [[-151.0064, 63.0695], [37.3556, -3.0674], [42.4453, 43.3499]],
454
- [[137.1595, -4.0784], [-140.4055, 60.5672], [138.73111, 35.358055]],
455
- ]
510
+ [
511
+ [6.864884, 45.832743],
512
+ [86.925, 27.9881],
513
+ [-70.0109, -32.6532],
514
+ ],
515
+ [
516
+ [-151.0064, 63.0695],
517
+ [37.3556, -3.0674],
518
+ [42.4453, 43.3499],
519
+ ],
520
+ [
521
+ [137.1595, -4.0784],
522
+ [-140.4055, 60.5672],
523
+ [138.73111, 35.358055],
524
+ ],
525
+ ],
456
526
  };
457
527
 
458
- const someElevatedMultiLineString = await maptilerClient.elevation.fromMultiLineString(someMultiLineString);
528
+ const someElevatedMultiLineString =
529
+ await maptilerClient.elevation.fromMultiLineString(someMultiLineString);
459
530
  // someElevatedMultiLineString is also of type MultiLineString
460
531
  ```
461
532
 
533
+ Read more about elevation lookup for a `MultiLineString` in our [official documentation](https://docs.maptiler.com/client-js/api/variables/services_elevation.elevation/#frommultilinestring).
534
+
462
535
  #### Caching
463
536
 
464
537
  In order 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.
465
538
 
539
+ ### 🧭 Routing
540
+
541
+ The `routing` module wraps the MapTiler Routing API, with a set of functions for each of its services. All of them share the same [request options and error handling](#request-options-and-errors).
542
+
543
+ #### Directions
544
+
545
+ The directions service computes a route between two or more locations, by car, truck, bicycle or on foot. The response contains a summary of the route (travel time, distance, bounding box), the geometry of each leg between waypoints and turn-by-turn steps with navigation instructions.
546
+
547
+ Directions are available with both HTTP methods: `directionsPost` supports every feature of the API, and `directionsGet` sends the request as URL query parameters, with a few features left out.
548
+
549
+ ##### Using POST
550
+
551
+ The only mandatory parts are the `profile` (`car`, `truck`, `bicycle` or `pedestrian`) and at least two `locations`:
552
+
553
+ ```ts
554
+ // in an async function, or as a 'thenable':
555
+ const result = await maptilerClient.routing.directionsPost({
556
+ profile: "car",
557
+ locations: [
558
+ { lon: 14.4213, lat: 50.0875 }, // Prague
559
+ { lon: 16.6068, lat: 49.1951 }, // Brno
560
+ ],
561
+ });
562
+
563
+ // Travel time in seconds and distance in the response units
564
+ const { totalTime, totalLength } = result.route.summary;
565
+ ```
566
+
567
+ You can provide many more options, such as:
568
+
569
+ - the `profileOptions` matching the chosen profile, e.g. the car routing mode (fastest, shortest or balanced), the truck dimensions and weight, the bicycle type or the walking speed
570
+ - `avoidances` of toll roads, ferries or highways, as part of the car and truck `profileOptions`
571
+ - either a `departureTime` or an `arrivalTime`
572
+ - a `heading` (preferred direction of travel) and a `waypoint` flag on each location
573
+ - `avoidLocations`, a GeoJSON `MultiPoint` or `MultiPolygon` of places the route must not go through
574
+ - `response` options: distance units (`km` or `mi`), language of the instructions, number of alternate routes (up to 3) and the level of detail (`legs`, `steps` or `instructions`)
575
+
576
+ ```ts
577
+ const result = await maptilerClient.routing.directionsPost({
578
+ profile: "truck",
579
+ profileOptions: {
580
+ height: 4,
581
+ weight: 18,
582
+ hazmat: true,
583
+ avoidances: { tolls: true },
584
+ },
585
+ locations: [
586
+ { lon: 14.4213, lat: 50.0875 },
587
+ { lon: 16.6068, lat: 49.1951 },
588
+ ],
589
+ departureTime: "2026-12-01T08:00",
590
+ response: {
591
+ units: "km",
592
+ language: "en",
593
+ alternates: 2,
594
+ additionalData: { detailLevel: "instructions" },
595
+ },
596
+ });
597
+
598
+ // Turn-by-turn instructions of the first leg
599
+ for (const step of result.route.legs[0].steps ?? []) {
600
+ console.log(step.maneuver?.instruction);
601
+ }
602
+
603
+ // Alternate routes have the same shape as the main route
604
+ const alternateRoutes = result.alternates ?? [];
605
+ ```
606
+
607
+ > 📣 Note for **TypeScript** users: `profileOptions` are typed according to the `profile`, so passing bicycle options to a car route, or setting both `departureTime` and `arrivalTime`, is caught at compile time.
608
+
609
+ <!-- Read more about directions with POST in our [official documentation](https://docs.maptiler.com/client-js/api/variables/services_routing.routing/#directionspost). -->
610
+
611
+ ##### Using GET
612
+
613
+ `directionsGet` accepts the same request as `directionsPost`, except for the fields that cannot be expressed as query parameters: the per-location `heading` and `waypoint`, and `avoidLocations`. Use `directionsPost` if you need any of them.
614
+
615
+ ```ts
616
+ const result = await maptilerClient.routing.directionsGet({
617
+ profile: "pedestrian",
618
+ profileOptions: { walkingSpeed: 4 },
619
+ locations: [
620
+ { lon: 14.4005, lat: 50.0909 }, // Prague Castle
621
+ { lon: 14.4213, lat: 50.0875 }, // Old Town Square
622
+ ],
623
+ });
624
+ ```
625
+
626
+ <!-- Read more about directions with GET in our [official documentation](https://docs.maptiler.com/client-js/api/variables/services_routing.routing/#directionsget). -->
627
+
628
+ ##### Route geometry
629
+
630
+ The geometry of each route leg is decoded by the client into an array of _GeoJSON_ positions `[lng, lat]`, so it can be used right away, for example to build a `LineString` to add to a map, or as the `path` of an [automatic static map](#automatic-static-maps):
631
+
632
+ ```ts
633
+ // Not mandatory, but it's to explain where the type comes from:
634
+ import { LineString } from "geojson";
635
+
636
+ const routeLine: LineString = {
637
+ type: "LineString",
638
+ coordinates: result.route.legs.flatMap((leg) => leg.geometry),
639
+ };
640
+
641
+ const imageLink = maptilerClient.staticMaps.automatic({
642
+ path: routeLine.coordinates,
643
+ pathStrokeColor: "blue",
644
+ });
645
+ ```
646
+
647
+ #### Request options and errors
648
+
649
+ All routing functions accept a second argument with options applying to the request itself:
650
+
651
+ - `apiKey` to use a different API key than the one in `config`
652
+ - `fetchExtras` with extra options for the underlying `fetch()` call, e.g. a `signal` to abort the request
653
+ - `adjustSearchParams`, a callback that can modify the URL search parameters before the request is sent
654
+
655
+ When the API returns an error, a `ServiceError` is thrown. Its message includes the error message from the API, and its `res` property holds the HTTP response, from which you can read the error `code` (see the `ApiErrorCode` type for the known values):
656
+
657
+ ```ts
658
+ const controller = new AbortController();
659
+
660
+ try {
661
+ const result = await maptilerClient.routing.directionsPost(request, {
662
+ fetchExtras: { signal: controller.signal },
663
+ });
664
+ } catch (error) {
665
+ if (error instanceof maptilerClient.ServiceError) {
666
+ const { code } = await error.res.json(); // e.g. "MT_PATH_NOT_FOUND"
667
+ }
668
+ }
669
+ ```
670
+
466
671
  ### 🧮 Math
467
672
 
468
- 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 recurrent feature, so that, just like us at MapTiler, you no longer need to copy-paste the same function from your previous project!
673
+ 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 recurrent feature, so that, just like us at MapTiler, you no longer need to copy-paste the same function from your previous project!
469
674
 
470
675
  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.
471
676
 
@@ -503,6 +708,8 @@ const tileXY = maptilerClient.math.wgs84ToTileIndex(montBlancPeakWgs84, 14);
503
708
  // and many more!
504
709
  ```
505
710
 
711
+ Please find out more about the math package in our [official documentation](https://docs.maptiler.com/client-js/api/variables/services_math.math/).
712
+
506
713
  <br>
507
714
 
508
715
  ## 💬 Support