@maptiler/client 1.0.3 → 1.1.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.
Files changed (72) hide show
  1. package/dist/maptiler-client.cjs +586 -21
  2. package/dist/maptiler-client.cjs.map +1 -1
  3. package/dist/maptiler-client.d.ts +405 -2
  4. package/dist/maptiler-client.min.mjs +1 -1
  5. package/dist/maptiler-client.mjs +582 -22
  6. package/dist/maptiler-client.mjs.map +1 -1
  7. package/dist/maptiler-client.umd.js +586 -21
  8. package/dist/maptiler-client.umd.js.map +1 -1
  9. package/dist/maptiler-client.umd.min.js +1 -1
  10. package/docs/assets/custom.css +28 -1
  11. package/docs/classes/config.ClientConfig.html +9 -9
  12. package/docs/classes/services_ServiceError.ServiceError.html +7 -7
  13. package/docs/functions/language.getAutoLanguageGeocoding.html +5 -5
  14. package/docs/functions/services_simplify.default.html +5 -5
  15. package/docs/index.html +111 -30
  16. package/docs/modules/config.html +5 -5
  17. package/docs/modules/language.html +5 -5
  18. package/docs/modules/services_ServiceError.html +5 -5
  19. package/docs/modules/services_coordinates.html +5 -5
  20. package/docs/modules/services_data.html +5 -5
  21. package/docs/modules/services_geocoding.html +5 -5
  22. package/docs/modules/services_geolocation.html +5 -5
  23. package/docs/modules/services_simplify.html +5 -5
  24. package/docs/modules/services_staticMaps.html +5 -5
  25. package/docs/modules.html +4 -4
  26. package/docs/types/config.FetchFunction.html +5 -5
  27. package/docs/types/language.LanguageGeocodingString.html +5 -5
  28. package/docs/types/services_coordinates.CoordinateExport.html +5 -5
  29. package/docs/types/services_coordinates.CoordinateGrid.html +5 -5
  30. package/docs/types/services_coordinates.CoordinateId.html +5 -5
  31. package/docs/types/services_coordinates.CoordinateSearch.html +5 -5
  32. package/docs/types/services_coordinates.CoordinateSearchResult.html +5 -5
  33. package/docs/types/services_coordinates.CoordinateTransformResult.html +5 -5
  34. package/docs/types/services_coordinates.CoordinateTransformation.html +5 -5
  35. package/docs/types/services_coordinates.CoordinatesSearchOptions.html +5 -5
  36. package/docs/types/services_coordinates.CoordinatesTransformOptions.html +5 -5
  37. package/docs/types/services_coordinates.XYZ.html +5 -5
  38. package/docs/types/services_data.GetDataOptions.html +5 -5
  39. package/docs/types/services_geocoding.Coordinates.html +5 -5
  40. package/docs/types/services_geocoding.FeatureHierarchy.html +5 -5
  41. package/docs/types/services_geocoding.GeocodingFeature.html +5 -5
  42. package/docs/types/services_geocoding.GeocodingOptions.html +5 -5
  43. package/docs/types/services_geocoding.GeocodingSearchResult.html +5 -5
  44. package/docs/types/services_geocoding.ReverseGeocodingOptions.html +5 -5
  45. package/docs/types/services_geolocation.GeolocationInfoOptions.html +5 -5
  46. package/docs/types/services_geolocation.GeolocationResult.html +5 -5
  47. package/docs/types/services_staticMaps.AutomaticStaticMapOptions.html +5 -5
  48. package/docs/types/services_staticMaps.BoundedStaticMapOptions.html +5 -5
  49. package/docs/types/services_staticMaps.CenteredStaticMapOptions.html +5 -5
  50. package/docs/types/services_staticMaps.StaticMapBaseOptions.html +7 -7
  51. package/docs/types/services_staticMaps.StaticMapMarker.html +5 -5
  52. package/docs/variables/config.config.html +5 -5
  53. package/docs/variables/language.LanguageGeocoding.html +5 -5
  54. package/docs/variables/services_coordinates.coordinates.html +5 -5
  55. package/docs/variables/services_data.data.html +5 -5
  56. package/docs/variables/services_geocoding.geocoding.html +5 -5
  57. package/docs/variables/services_geolocation.geolocation.html +5 -5
  58. package/docs/variables/services_staticMaps.staticMaps.html +5 -5
  59. package/docsmd/README.md +145 -36
  60. package/docsmd/assets/custom.css +28 -1
  61. package/docsmd/classes/ClientConfig.md +5 -5
  62. package/docsmd/classes/MapStyleVariant.md +234 -0
  63. package/docsmd/classes/ReferenceMapStyle.md +169 -0
  64. package/docsmd/classes/ServiceError.md +3 -3
  65. package/examples/test-browser-umd.html +1 -1
  66. package/package.json +1 -1
  67. package/readme.md +86 -27
  68. package/src/index.ts +17 -0
  69. package/src/mapstyle.ts +874 -0
  70. package/src/services/staticMaps.ts +5 -4
  71. package/tsconfig.json +0 -1
  72. package/typedoc.css +28 -1
package/readme.md CHANGED
@@ -1,5 +1,5 @@
1
1
  <p align="center">
2
- <a href="https://www.maptiler.com/">offcial page →</a><br>
2
+ <a href="https://docs.maptiler.com/client-js/">offcial page →</a><br>
3
3
  <img src="images/maptiler-client-logo.svg" width="400px">
4
4
  </p>
5
5
 
@@ -14,17 +14,28 @@
14
14
  <img src="https://img.shields.io/twitter/follow/maptiler?style=social"></img>
15
15
  </p>
16
16
 
17
- # What and why?
17
+ # API Client Library for JavaScript / TypeScript
18
+
19
+ ## What?
20
+
18
21
  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:
19
- - Geocoding forward and reverse
20
- - Geolocation from visitor's IP address
21
- - Coordidinate systems search and tranform
22
- - User data fetching as GeoJSON
23
- - Static maps of all sorts
22
+ - [Geocoding forward and reverse](#-geocoding)
23
+ - [Geolocation from visitor's IP address](#%EF%B8%8F%EF%B8%8F-geolocation)
24
+ - [Coordidinate systems search and tranform](#-coordinates)
25
+ - [User data fetching as GeoJSON](#-data)
26
+ - [Static maps of all sorts](#%EF%B8%8F-static-maps)
27
+
28
+ ## Why?
24
29
 
25
30
  The project is entirely written in TypeScript and all the function arguments are nicely documented and typed.
26
31
 
27
- > 📣 *__Note:__* If you need *this* API wrapper **AND** a complete SDK to display beautiful interactive maps, then checkout [MapTiler SDK JS](https://github.com/maptiler/maptiler-sdk-js), it contains it all!
32
+ - Better developer experience of working with APIs in the code editor - with parameter info, quick info, and member lists.
33
+ - Code completion: reducing typos and other common mistakes
34
+ - Content assist and code hinting providing contextual help
35
+ - Type safety - for higher quality code and testing
36
+ - Backward compatibility: guaranteed on changes to API endpoints
37
+ - Runs: in Node.js or in browser
38
+ - Open source license
28
39
 
29
40
  # Install
30
41
  ```shell
@@ -32,7 +43,7 @@ npm install --save @maptiler/client
32
43
  ```
33
44
 
34
45
  # API documentation
35
- In addition to the details and examples provided in this readme, check out the [complete API documentation](docs/README.md)).
46
+ In addition to the details and examples provided in this readme, check out the [complete API documentation](https://maptiler.github.io/maptiler-client-js).
36
47
 
37
48
  # Quick start
38
49
  ```ts
@@ -56,6 +67,8 @@ The [examples](examples/) folder includes are featuring usages for **NodeJS**, *
56
67
  Here is the list of service wrapper functions that are built-in:
57
68
 
58
69
  ## 🔍 Geocoding
70
+ > ✅ 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) ⚖️
71
+
59
72
  ### Forward
60
73
  You want to know the longitude and latitude of a specific place, use the forward geocoding:
61
74
  ```ts
@@ -67,7 +80,7 @@ You can provide some options such as:
67
80
  - one of more languages to get the results into
68
81
  - a bounding geo box, to restrict the search to a given window
69
82
 
70
- Read more about forward geocoding on our official [API documentation](https://docs.maptiler.com/cloud/api/geocoding/#search-by-name-forward).
83
+ Read more about forward geocoding on our [official documentation](https://docs.maptiler.com/client-js/geocoding/#forward).
71
84
 
72
85
  ### Reverse
73
86
  You wan to tknow the name of a place, given a longitude-latitude? Use the reverse geocoding:
@@ -77,7 +90,7 @@ const result = await maptilerClient.geocoding.reverse([6.249638, 46.402056]);
77
90
  ```
78
91
  The same option object as the forward geocoding can be provided.
79
92
 
80
- Read more about reverse geocoding on our official [API documentation](https://docs.maptiler.com/cloud/api/geocoding/#search-by-coordinates-reverse).
93
+ Read more about reverse geocoding on our [official documentation](https://docs.maptiler.com/client-js/geocoding/#reverse).
81
94
 
82
95
  ### Language
83
96
  For both *forward* and *reverse* geocoding, this library provides a list of supported languages as shorthands to [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:
@@ -86,10 +99,12 @@ For both *forward* and *reverse* geocoding, this library provides a list of supp
86
99
  const result = await maptilerClient.geocoding.forward('paris', {language: [maptilerClient.geocoding.languages.SPANISH, maptilerClient.geocoding.languages.KOREAN]})
87
100
  ```
88
101
 
89
- The special language `AUTO` will detect the plateform/browser prefered language.
102
+ The special language `AUTO` will detect the platform/browser preferred language.
90
103
 
91
104
  ## 🕵️‍♂️ Geolocation
92
- The geolocation service provides an accurate location insight of a website visitor using its IP address.
105
+ The geolocation service provides location informations of a visitor using its IP address.
106
+
107
+ 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.
93
108
 
94
109
  There is only a single function:
95
110
  ```ts
@@ -97,7 +112,7 @@ There is only a single function:
97
112
  const result = await maptilerClient.geolocation.info();
98
113
  ```
99
114
 
100
- Read more about geolocation on our official [API documentation](https://docs.maptiler.com/cloud/api/geolocation/).
115
+ Read more about geolocation on our [official documentation](https://docs.maptiler.com/client-js/geolocation/).
101
116
 
102
117
  ## 🌐 Coordinates
103
118
  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!
@@ -114,7 +129,7 @@ const resultD = await maptilerClient.coordinates.search('code:4326', {transforma
114
129
 
115
130
  The `transformations` options retrieves a lot more details about the CRS that MapTiler API is able to transform to/from than just their IDs.
116
131
 
117
- Read more about searching coordinate systems on our official [API documentation](https://docs.maptiler.com/cloud/api/coordinates/#search-coordinate-systems).
132
+ Read more about searching coordinate systems on our [official documentation](https://docs.maptiler.com/client-js/coordinates/#search).
118
133
 
119
134
  ### Transform
120
135
  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).
@@ -131,7 +146,7 @@ const resultA = await maptilerClient.coordinates.transform([1, 45], {targetCrs:
131
146
  const resultB = await maptilerClient.coordinates.transform([[10, 48], [1, 45]], {targetCrs: 9793})
132
147
  ```
133
148
 
134
- Read more about transforming coordinates on our official [API documentation](https://docs.maptiler.com/cloud/api/coordinates/#transform-coordinates).
149
+ Read more about transforming coordinates on our [official documentation](https://docs.maptiler.com/client-js/coordinates/#transform).
135
150
 
136
151
  ## 💽 Data
137
152
  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:
@@ -143,7 +158,11 @@ const result = await maptilerClient.data.get('my-dataset-unique-id')
143
158
 
144
159
  Since the result is a GeoJSON, it can easily be added to a `map` with `.addSource()` and `.addLayer()`.
145
160
 
161
+ Read more about fetching your own data on our [official documentation](https://docs.maptiler.com/client-js/data/).
162
+
146
163
  ## 🗺️ Static maps
164
+ > ✅ 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) ⚖️
165
+
147
166
  Maptiler Cloud provides many possibilities for creating static maps as PNG, JPEG or WebP images. They all offer the possibilities to:
148
167
  - Choose from one of the MapTiler style or your own
149
168
  - Add markers with a custom icon (or default icon with custom color)
@@ -151,14 +170,51 @@ Maptiler Cloud provides many possibilities for creating static maps as PNG, JPEG
151
170
 
152
171
  Three modes are available: `centered`, `bounded` and `automatic`.
153
172
 
154
- > 📣 *__important:__* Contrary to the geolocation/geocoding/coordinates/data service wrappers, the static maps function **does not** perform any query to the MapTiler API, instead they build the image URL. We took this decision because images are most likely going to be displayed in `<img src="path.png"></img>` markups and will naturaly be fetched by the web browser.
173
+ > 📣 *__important:__* <span style="text-decoration: underline">only image **URLs** are returned.</span>
174
+ > 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.
175
+
176
+
177
+ ### Map Styles
178
+ 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:
179
+
180
+ - `MapStyle.STREETS`, reference style for navigation and city exploration
181
+ - `MapStyle.STREETS.DARK` (variant)
182
+ - `MapStyle.STREETS.LIGHT` (variant)
183
+ - `MapStyle.STREETS.PASTEL` (variant)
184
+ - `MapStyle.OUTDOOR` reference style for adventure
185
+ - `MapStyle.WINTER` reference style for winter adventure
186
+ - `MapStyle.SATELLITE` reference style satellite and airborne imagery (no variants)
187
+ - `MapStyle.HYBRID` reference style satellite and airborne imagery with labels (no variants)
188
+ - `MapStyle.BASIC` reference style for minimalist design and general purpose
189
+ - `MapStyle.BASIC.DARK` (variant)
190
+ - `MapStyle.BASIC.LIGHT` (variant)
191
+ - `MapStyle.BRIGHT` reference style for high contrast navigation
192
+ - `MapStyle.BRIGHT.DARK` (variant)
193
+ - `MapStyle.BRIGHT.LIGHT` (variant)
194
+ - `MapStyle.BRIGHT.PASTEL` (variant)
195
+ - `MapStyle.TOPO` reference style for topographic study
196
+ - `MapStyle.TOPO.SHINY` (variant)
197
+ - `MapStyle.TOPO.PASTEL` (variant)
198
+ - `MapStyle.TOPO.TOPOGRAPHIQUE` (variant)
199
+ - `MapStyle.VOYAGER` reference style for stylish yet minimalist maps
200
+ - `MapStyle.VOYAGER.DARK` (variant)
201
+ - `MapStyle.VOYAGER.LIGHT` (variant)
202
+ - `MapStyle.VOYAGER.VINTAGE` (variant)
203
+ - `MapStyle.TONER` reference style for very high contrast stylish maps
204
+ - `MapStyle.TONER.BACKGROUND` (variant)
205
+ - `MapStyle.TONER.LITE` (variant)
206
+ - `MapStyle.TONER.LINES` (variant)
207
+ - `MapStyle.OPENSTREETMAP` (reference style, this one does not have any variants)
208
+ - `MapStyle.STAGE`, the perfect style for data visualization, with very little noise
209
+ - `MapStyle.STAGE.DARK` (variant)
210
+ - `MapStyle.STAGE.LIGHT` (variant)
155
211
 
156
212
  ### Centered static maps
157
213
  This type of map is centered on a longitude-latitude coordinate and the zoom level must also be provided (from `0`: very zoomed out, to `22`: very zoomed in).
158
214
  Note that if a path or markers are provided, the framing of the map will not automatically adapt to include those (use the `automatic` mode for that).
159
215
 
160
216
  ```ts
161
- const imageLink = maptiler.staticMaps.centered(
217
+ const imageLink = maptilerClient.staticMaps.centered(
162
218
  // center position (Boston)
163
219
  [-71.06080, 42.362114],
164
220
 
@@ -175,7 +231,7 @@ const imageLink = maptiler.staticMaps.centered(
175
231
  height: 1000,
176
232
 
177
233
  // Map style
178
- style: 'streets-v2',
234
+ style: maptilerClient.MapStyle.OUTDOOR,
179
235
  });
180
236
  ```
181
237
 
@@ -186,7 +242,7 @@ Read more about centered static maps on our official [API documentation](https:/
186
242
  This type of map requires a bounding box made of two points: the south-west bound and the north-east bound. The zoom level cannot be provided and is automatically deduced from the size of the bounding box.
187
243
 
188
244
  ```ts
189
- const imageLink = maptiler.staticMaps.bounded(
245
+ const imageLink = maptilerClient.staticMaps.bounded(
190
246
  // The bounding box on Europe
191
247
  [
192
248
  -24, // west bound (min x)
@@ -200,7 +256,7 @@ const imageLink = maptiler.staticMaps.bounded(
200
256
  hiDPI: true,
201
257
  width: 2048,
202
258
  height: 2048,
203
- style: 'streets-v2',
259
+ style: maptilerClient.MapStyle.STREETS.DARK,
204
260
 
205
261
  // Extra space that will add around the bounding box, in percentage
206
262
  // (0.1 = 10% is actually the dafault)
@@ -214,7 +270,7 @@ Since the zoom level cannot be provided, the level of details is dictated by the
214
270
  | :-----------: | :-----------: |
215
271
  | ![](images/screenshots/static-bounded-europe-2048.png) | ![](images/screenshots/static-bounded-europe-1024.png) |
216
272
 
217
- 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 exactely the same bounding box to show the difference between the provided bounding box and the final image. We kept the default padding of 10%:
273
+ 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%:
218
274
 
219
275
 
220
276
  | `2048 x 2048` | `1024 x 2048` |
@@ -227,7 +283,7 @@ Read more about bounded static maps on our official [API documentation](https://
227
283
  ### Automatic static maps
228
284
  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.
229
285
 
230
- 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 avalable as a GeoJSON:
286
+ 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:
231
287
 
232
288
  ```ts
233
289
  // Fetching the GeoJSON
@@ -237,16 +293,16 @@ const bikeTrack = await maptilerClient.data.get('the-id-of-a-bike-track-in-montr
237
293
  const trackPoints = bikeTrack.features[0].geometry.coordinates[0]
238
294
  .map(p => p.slice(0, 2));
239
295
 
240
- const imageLink = maptiler.staticMaps.automatic({
296
+ const imageLink = maptilerClient.staticMaps.automatic({
241
297
  // hiDPI/Retina precision
242
298
  hiDPI: true,
243
299
 
244
- // A farily large output image
300
+ // A fairly large output image
245
301
  width: 2048,
246
302
  height: 1024 ,
247
303
 
248
304
  // A grey style on which the track will pop!
249
- style: 'streets-v2-light',
305
+ style: maptilerClient.MapStyle.STREETS.LIGHT,
250
306
 
251
307
  // Draw a path with the trackpoints
252
308
  path: trackPoints,
@@ -263,7 +319,7 @@ And voila!
263
319
 
264
320
  ![static map with bike path](images/screenshots/static-with-path.png)
265
321
 
266
- > 📣 *__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 keeing 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).
322
+ > 📣 *__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).
267
323
 
268
324
  Read more about bounded static maps on our official [API documentation](https://docs.maptiler.com/cloud/api/static-maps/#auto-fitted-image).
269
325
 
@@ -286,3 +342,6 @@ config.fetch = fetch;
286
342
 
287
343
  // ...
288
344
  ```
345
+
346
+ # Terms and usage limitations
347
+ 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.
package/src/index.ts CHANGED
@@ -44,6 +44,16 @@ import type {
44
44
 
45
45
  import { ServiceError } from "./services/ServiceError";
46
46
 
47
+ import type { MapStylePreset, MapStyleType } from "./mapstyle";
48
+
49
+ import {
50
+ MapStyleVariant,
51
+ ReferenceMapStyle,
52
+ mapStylePresetList,
53
+ MapStyle,
54
+ expandMapStyle,
55
+ } from "./mapstyle";
56
+
47
57
  // Exporting types
48
58
  export type {
49
59
  Position,
@@ -74,6 +84,8 @@ export type {
74
84
  GetDataOptions,
75
85
  GeolocationInfoOptions,
76
86
  GeolocationResult,
87
+ MapStylePreset,
88
+ MapStyleType,
77
89
  };
78
90
 
79
91
  // Exporting classes, objects, functions, etc.
@@ -87,4 +99,9 @@ export {
87
99
  data,
88
100
  staticMaps,
89
101
  LanguageGeocoding,
102
+ MapStyleVariant,
103
+ ReferenceMapStyle,
104
+ mapStylePresetList,
105
+ MapStyle,
106
+ expandMapStyle,
90
107
  };