@maptiler/client 2.7.0 โ†’ 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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@maptiler/client",
3
- "version": "2.7.0",
3
+ "version": "2.8.0-rc.1",
4
4
  "description": "Javascript & Typescript wrapper to MapTiler Cloud API",
5
5
  "module": "dist/maptiler-client.mjs",
6
6
  "types": "dist/maptiler-client.d.ts",
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 call to [MapTiler Cloud API services](https://docs.maptiler.com/cloud/api), such as:
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 tranform](#-coordinates)
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 its 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.
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 are featuring usages for **NodeJS**, **browser with UMD** and **browser with ES module**.
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 wan to tknow the name of a place, given a longitude-latitude? Use the reverse geocoding:
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 is an array:
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 seleted this way is generaly 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)).
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 informations of a visitor using its IP address.
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 visitors to provide informations about their location, such as city, region, country, timezone, etc. The precision is lower than GPS but does not require visitors to explicitely enable the location service from their web browser.
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 retrieves a lot more details about the CRS that MapTiler API is able to transform to/from than just their IDs.
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 on our [official documentation](https://docs.maptiler.com/client-js/coordinates/#search).
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 default to **EPSG:4326** (in other words, [WGS84](https://epsg.io/4326)). Here is how to use this feature:
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 to each dataset so that we can later on access it programmatically to retrieve a GeoJSON equivalent of it:
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 style or your own
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 shorthand. Here is the full list:
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 add around the bounding box, in percentage
325
- // (0.1 = 10% is actually the dafault)
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 details is dictated by the size of the output image. here is an example:
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 fits automatically whatever you need to place inside: path or markers.
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
  ![static map with bike path](images/screenshots/static-with-path.png)
385
385
 
386
- > ๐Ÿ“ฃ *__Note:__* The GeoJSON for this track contains 9380 couples 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).
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 metter from any location. It's possible lookup and compute elevation for a single location, to provide a batch of points, from a GeoJSON LineString or from a GeoJSON MultiLineString!
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, currated 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.
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: 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.
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 element: `[lng, lat, elevation]`. The original LineString is not mutated nor pointed at.
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 element: `[lng, lat, elevation]`. The original MultiLineString is not mutated nor pointed at.
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 recurent feature, so that, just like us at MapTiler, you no longer need to copy-paste the same function from your previous project!
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 meter:
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 ways. 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.
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