@maptiler/client 2.7.0-rc.1 โ 2.8.0-rc.1
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/CHANGELOG.md +13 -5
- package/dist/maptiler-client.cjs +17 -5
- package/dist/maptiler-client.cjs.map +1 -1
- package/dist/maptiler-client.d.ts +11 -6
- package/dist/maptiler-client.min.mjs +1 -1
- package/dist/maptiler-client.mjs +17 -5
- package/dist/maptiler-client.mjs.map +1 -1
- package/package.json +1 -1
- package/readme.md +31 -31
package/package.json
CHANGED
package/readme.md
CHANGED
|
@@ -2,10 +2,10 @@
|
|
|
2
2
|
|
|
3
3
|
# API Client Library for JavaScript / TypeScript
|
|
4
4
|
|
|
5
|
-
The **MapTiler Client JS** exposes a number of handy functions that wrap API
|
|
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
|
- [Geocoding forward and reverse](#-geocoding)
|
|
7
7
|
- [Geolocation from visitor's IP address](#%EF%B8%8F%EF%B8%8F-geolocation)
|
|
8
|
-
- [Coordinate systems search and
|
|
8
|
+
- [Coordinate systems search and transform](#-coordinates)
|
|
9
9
|
- [User data fetching as GeoJSON](#-data)
|
|
10
10
|
- [Static maps of all sorts](#%EF%B8%8F-static-maps)
|
|
11
11
|
- [Elevation lookup with batch features](#-elevation)
|
|
@@ -54,7 +54,7 @@ npm install --save @maptiler/client
|
|
|
54
54
|
```
|
|
55
55
|
|
|
56
56
|
### From NodeJS
|
|
57
|
-
NodeJS includes a stable `fetch()` function only from
|
|
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
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*.
|
|
60
60
|
|
|
@@ -98,7 +98,7 @@ import {
|
|
|
98
98
|
|
|
99
99
|
## ๐ก Related Examples
|
|
100
100
|
|
|
101
|
-
The [examples](examples/) folder includes
|
|
101
|
+
The [examples](examples/) folder includes usages for **NodeJS**, **browser with UMD** and **browser with ES module**.
|
|
102
102
|
|
|
103
103
|
<br>
|
|
104
104
|
|
|
@@ -123,16 +123,16 @@ You want to know the longitude and latitude of a specific place, use the forward
|
|
|
123
123
|
// in an async function, or as a 'thenable':
|
|
124
124
|
const result = await maptilerClient.geocoding.forward('paris');
|
|
125
125
|
```
|
|
126
|
-
You can provide some options such as:
|
|
126
|
+
You can provide some options, such as:
|
|
127
127
|
- the proximity, given a lon-lat position, to sort the results
|
|
128
128
|
- one of more languages to get the results into
|
|
129
129
|
- a bounding geo box, to restrict the search to a given window
|
|
130
130
|
|
|
131
|
-
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/geocoding/#forward).
|
|
131
|
+
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/geocoding/#forward).
|
|
132
132
|
|
|
133
133
|
#### Reverse
|
|
134
134
|
|
|
135
|
-
You
|
|
135
|
+
You want to know the name of a place, given a longitude-latitude? Use the reverse geocoding:
|
|
136
136
|
```ts
|
|
137
137
|
// in an async function, or as a 'thenable':
|
|
138
138
|
const result = await maptilerClient.geocoding.reverse([6.249638, 46.402056]);
|
|
@@ -143,7 +143,7 @@ Read more about reverse geocoding on our [official documentation](https://docs.m
|
|
|
143
143
|
|
|
144
144
|
#### Language
|
|
145
145
|
|
|
146
|
-
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
|
|
146
|
+
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:
|
|
147
147
|
|
|
148
148
|
```ts
|
|
149
149
|
const result = await maptilerClient.geocoding.forward('paris', {language: [maptilerClient.Language.SPANISH, maptilerClient.geocoding.Language.KOREAN]})
|
|
@@ -151,13 +151,13 @@ const result = await maptilerClient.geocoding.forward('paris', {language: [mapti
|
|
|
151
151
|
|
|
152
152
|
The special language `AUTO` will detect the platform/browser preferred language.
|
|
153
153
|
|
|
154
|
-
If the language is not specified as options, MapTiler Cloud will use the `Accept-language` from the HTTP header of the request. The language
|
|
154
|
+
If the language is not specified as options, MapTiler Cloud will use the `Accept-language` from the HTTP header of the request. The language selected this way is generally similar to the `Language.AUTO` mode, but can still differ in some cases ([read more](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language)).
|
|
155
155
|
|
|
156
156
|
### ๐ต๏ธโโ๏ธ Geolocation
|
|
157
157
|
|
|
158
|
-
The geolocation service provides location
|
|
158
|
+
The geolocation service provides location information of a visitor using its IP address.
|
|
159
159
|
|
|
160
|
-
The geolocation uses the IP address of a
|
|
160
|
+
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.
|
|
161
161
|
|
|
162
162
|
There is only a single function:
|
|
163
163
|
```ts
|
|
@@ -169,7 +169,7 @@ Read more about geolocation on our [official documentation](https://docs.maptile
|
|
|
169
169
|
|
|
170
170
|
### ๐ Coordinates
|
|
171
171
|
|
|
172
|
-
If you are already familiar with [epsg.io](https://epsg.io/) (created by MapTiler), then you may find 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!
|
|
172
|
+
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!
|
|
173
173
|
|
|
174
174
|
#### Search
|
|
175
175
|
|
|
@@ -182,15 +182,15 @@ const resultC = await maptilerClient.coordinates.search('france');
|
|
|
182
182
|
const resultD = await maptilerClient.coordinates.search('code:4326', {transformations: true}));
|
|
183
183
|
```
|
|
184
184
|
|
|
185
|
-
The `transformations` options
|
|
185
|
+
The `transformations` options retrieve a lot more details about the CRS that MapTiler API is able to transform to/from than just their IDs.
|
|
186
186
|
|
|
187
|
-
Read more about searching coordinate systems
|
|
187
|
+
Read more about searching coordinate systems in our [official documentation](https://docs.maptiler.com/client-js/coordinates/#search).
|
|
188
188
|
|
|
189
189
|
#### Transform
|
|
190
190
|
|
|
191
191
|
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).
|
|
192
192
|
|
|
193
|
-
If not provided, both the source (`sourceCrs`) and the destination (`targetCrs`) are
|
|
193
|
+
If not provided, both the source (`sourceCrs`) and the destination (`targetCrs`) are defaulted to **EPSG:4326** (in other words, [WGS84](https://epsg.io/4326)). Here is how to use this feature:
|
|
194
194
|
|
|
195
195
|
```ts
|
|
196
196
|
// in an async function, or as a 'thenable':
|
|
@@ -206,7 +206,7 @@ Read more about transforming coordinates on our [official documentation](https:/
|
|
|
206
206
|
|
|
207
207
|
### ๐ฝ Data
|
|
208
208
|
|
|
209
|
-
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
|
|
209
|
+
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:
|
|
210
210
|
|
|
211
211
|
```ts
|
|
212
212
|
// in an async function, or as a 'thenable':
|
|
@@ -222,7 +222,7 @@ Read more about fetching your own data on our [official documentation](https://d
|
|
|
222
222
|
> โ
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) โ๏ธ
|
|
223
223
|
|
|
224
224
|
Maptiler Cloud provides many possibilities for creating static maps as PNG, JPEG or WebP images. They all offer the possibilities to:
|
|
225
|
-
- Choose from one of the MapTiler
|
|
225
|
+
- Choose from one of the MapTiler styles or your own
|
|
226
226
|
- Add markers with a custom icon (or default icon with custom color)
|
|
227
227
|
- Add path or polygon, with a parametric line width and color and a parametric filling color
|
|
228
228
|
|
|
@@ -233,7 +233,7 @@ Three modes are available: `centered`, `bounded` and `automatic`.
|
|
|
233
233
|
|
|
234
234
|
#### Map Styles
|
|
235
235
|
|
|
236
|
-
In the following static map functions, the `option` object features a `style` property that can be a string or one of the built-in style
|
|
236
|
+
In the following static map functions, the `option` object features a `style` property that can be a string or one of the built-in style shorthands. Here is the full list:
|
|
237
237
|
|
|
238
238
|
- `MapStyle.STREETS`, reference style for navigation and city exploration
|
|
239
239
|
- `MapStyle.STREETS.DARK` (variant)
|
|
@@ -321,13 +321,13 @@ const imageLink = maptilerClient.staticMaps.bounded(
|
|
|
321
321
|
height: 2048,
|
|
322
322
|
style: maptilerClient.MapStyle.STREETS.DARK,
|
|
323
323
|
|
|
324
|
-
// Extra space that will
|
|
325
|
-
// (0.1 = 10% is actually the
|
|
324
|
+
// Extra space that will be added around the bounding box, in percentage
|
|
325
|
+
// (0.1 = 10% is actually the default)
|
|
326
326
|
padding: 0.1
|
|
327
327
|
});
|
|
328
328
|
```
|
|
329
329
|
|
|
330
|
-
Since the zoom level cannot be provided, the level of
|
|
330
|
+
Since the zoom level cannot be provided, the level of detail is dictated by the size of the output image. Here is an example:
|
|
331
331
|
|
|
332
332
|
| `2048 x 2048` | `1024 x 1024` |
|
|
333
333
|
| :-----------: | :-----------: |
|
|
@@ -345,7 +345,7 @@ Read more about bounded static maps on our official [API documentation](https://
|
|
|
345
345
|
|
|
346
346
|
#### Automatic static maps
|
|
347
347
|
|
|
348
|
-
As we have seen with centered and bounded maps, providing all the parameters is nice but can be cumbersome for the simplest use cases. This is why MapTiler Cloud also provides static maps that
|
|
348
|
+
As we have seen with centered and bounded maps, providing all the parameters is nice, but it can be cumbersome for the simplest use cases. This is why MapTiler Cloud also provides static maps that fit automatically whatever you need to place inside: path or markers.
|
|
349
349
|
|
|
350
350
|
In the following example, we are going to load a cycling track recorded by one of our team members in Montreal, Canada. The track, originally a GPX file, was pushed to MapTiler Data and is now made available as a GeoJSON:
|
|
351
351
|
|
|
@@ -383,17 +383,17 @@ And voila!
|
|
|
383
383
|
|
|
384
384
|

|
|
385
385
|
|
|
386
|
-
> ๐ฃ *__Note:__* The GeoJSON for this track contains 9380
|
|
386
|
+
> ๐ฃ *__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).
|
|
387
387
|
|
|
388
388
|
Read more about bounded static maps on our official [API documentation](https://docs.maptiler.com/cloud/api/static-maps/#auto-fitted-image).
|
|
389
389
|
|
|
390
390
|
### ๐๏ธ Elevation
|
|
391
391
|
|
|
392
|
-
With the elevation API, it's possible to get the elevation in
|
|
392
|
+
With the elevation API, it's possible to get the elevation in meters from any location. It's possible to lookup and compute elevation for a single location, to provide a batch of points, from a GeoJSON LineString or from a GeoJSON MultiLineString!
|
|
393
393
|
|
|
394
|
-
> โน๏ธ 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,
|
|
394
|
+
> โน๏ธ 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.
|
|
395
395
|
|
|
396
|
-
> ๐ฃ Note for **TypeScript** users:
|
|
396
|
+
> ๐ฃ 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.
|
|
397
397
|
|
|
398
398
|
Let's see how to use it:
|
|
399
399
|
|
|
@@ -435,7 +435,7 @@ Read more about elevation lookup for a batch of locations in our [official docum
|
|
|
435
435
|
|
|
436
436
|
#### From a GeoJSON LineString
|
|
437
437
|
|
|
438
|
-
In the *GeoJSON* LineString case, it clones the entire structure and the positions arrays of the clone will contain three
|
|
438
|
+
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.
|
|
439
439
|
|
|
440
440
|
```ts
|
|
441
441
|
// Not mandatory, but it's to explain where the type comes from:
|
|
@@ -455,7 +455,7 @@ Read more about elevation lookup for a `LineString` in our [official documentati
|
|
|
455
455
|
|
|
456
456
|
#### From a GeoJSON MultiLineString
|
|
457
457
|
|
|
458
|
-
In the *GeoJSON* MultiLineString case, it clones the entire structure and the positions arrays of the clone will contain three
|
|
458
|
+
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.
|
|
459
459
|
|
|
460
460
|
```ts
|
|
461
461
|
// Not mandatory, but it's to explain where the type comes from:
|
|
@@ -483,7 +483,7 @@ In order to increase performance while reducing unnecessary elevation data fetch
|
|
|
483
483
|
|
|
484
484
|
### ๐งฎ Math
|
|
485
485
|
|
|
486
|
-
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
|
|
486
|
+
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!
|
|
487
487
|
|
|
488
488
|
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.
|
|
489
489
|
|
|
@@ -505,7 +505,7 @@ const montBlancPeakMerc = maptilerClient.math.wgs84ToMercator(montBlancPeakWgs84
|
|
|
505
505
|
// From Mercator to WGS84
|
|
506
506
|
const montBlancPeakWgs84Again = maptilerClient.math.mercatorToWgs84(montBlancPeakMerc);
|
|
507
507
|
|
|
508
|
-
// A great-circle distance in
|
|
508
|
+
// A great-circle distance in meters:
|
|
509
509
|
const from: Position = /* ... */;
|
|
510
510
|
const to: Position = /* ... */;
|
|
511
511
|
const distance = maptilerClient.math.haversineDistanceWgs84(from, to);
|
|
@@ -555,7 +555,7 @@ This project is licensed under the BSD 3-Clause License โ see theย [LICENSE](.
|
|
|
555
555
|
|
|
556
556
|
### Terms and usage limitations
|
|
557
557
|
|
|
558
|
-
The data fetched from MapTiler Cloud API, with or without this library, cannot be stored or redistributed in any
|
|
558
|
+
The data fetched from MapTiler Cloud API, with or without this library, cannot be stored or redistributed in any way. If you have any doubt about your specific usecase, please consult our [legal terms](https://www.maptiler.com/cloud/terms/#explicitly-prohibited-use) or contact us.
|
|
559
559
|
|
|
560
560
|
<br>
|
|
561
561
|
|