@maptiler/client 1.0.2 → 1.1.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.
Files changed (120) hide show
  1. package/.github/workflows/npm-publish.yml +0 -1
  2. package/dist/maptiler-client.cjs +465 -21
  3. package/dist/maptiler-client.cjs.map +1 -1
  4. package/dist/maptiler-client.d.ts +395 -2
  5. package/dist/maptiler-client.min.mjs +1 -1
  6. package/dist/maptiler-client.mjs +461 -22
  7. package/dist/maptiler-client.mjs.map +1 -1
  8. package/dist/maptiler-client.umd.js +465 -21
  9. package/dist/maptiler-client.umd.js.map +1 -1
  10. package/dist/maptiler-client.umd.min.js +1 -1
  11. package/docs/assets/custom.css +118 -0
  12. package/docs/assets/highlight.css +10 -10
  13. package/docs/assets/main.js +56 -52
  14. package/docs/assets/search.js +1 -1
  15. package/docs/assets/style.css +23 -0
  16. package/docs/classes/{ClientConfig.html → config.ClientConfig.html} +34 -24
  17. package/docs/classes/{ServiceError.html → services_ServiceError.ServiceError.html} +26 -16
  18. package/docs/functions/language.getAutoLanguageGeocoding.html +60 -0
  19. package/docs/functions/services_simplify.default.html +65 -0
  20. package/docs/images/maptiler-logo-256.png +0 -0
  21. package/docs/index.html +118 -57
  22. package/docs/modules/config.html +71 -0
  23. package/docs/modules/language.html +71 -0
  24. package/docs/modules/services_ServiceError.html +61 -0
  25. package/docs/modules/services_coordinates.html +84 -0
  26. package/docs/modules/services_data.html +66 -0
  27. package/docs/modules/services_geocoding.html +76 -0
  28. package/docs/modules/services_geolocation.html +68 -0
  29. package/docs/modules/services_simplify.html +61 -0
  30. package/docs/modules/services_staticMaps.html +74 -0
  31. package/docs/modules.html +23 -83
  32. package/docs/types/config.FetchFunction.html +71 -0
  33. package/docs/types/language.LanguageGeocodingString.html +58 -0
  34. package/docs/types/services_coordinates.CoordinateExport.html +71 -0
  35. package/docs/types/services_coordinates.CoordinateGrid.html +69 -0
  36. package/docs/types/services_coordinates.CoordinateId.html +71 -0
  37. package/docs/types/services_coordinates.CoordinateSearch.html +93 -0
  38. package/docs/types/services_coordinates.CoordinateSearchResult.html +75 -0
  39. package/docs/types/services_coordinates.CoordinateTransformResult.html +76 -0
  40. package/docs/types/services_coordinates.CoordinateTransformation.html +89 -0
  41. package/docs/types/services_coordinates.CoordinatesSearchOptions.html +83 -0
  42. package/docs/types/services_coordinates.CoordinatesTransformOptions.html +85 -0
  43. package/docs/types/services_coordinates.XYZ.html +73 -0
  44. package/docs/types/services_data.GetDataOptions.html +64 -0
  45. package/docs/types/services_geocoding.Coordinates.html +60 -0
  46. package/docs/types/services_geocoding.FeatureHierarchy.html +71 -0
  47. package/docs/types/services_geocoding.GeocodingFeature.html +60 -0
  48. package/docs/types/services_geocoding.GeocodingOptions.html +79 -0
  49. package/docs/types/services_geocoding.GeocodingSearchResult.html +77 -0
  50. package/docs/types/services_geocoding.ReverseGeocodingOptions.html +71 -0
  51. package/docs/types/services_geolocation.GeolocationInfoOptions.html +65 -0
  52. package/docs/types/services_geolocation.GeolocationResult.html +128 -0
  53. package/docs/types/services_staticMaps.AutomaticStaticMapOptions.html +61 -0
  54. package/docs/types/services_staticMaps.BoundedStaticMapOptions.html +61 -0
  55. package/docs/types/services_staticMaps.CenteredStaticMapOptions.html +61 -0
  56. package/docs/types/{StaticMapBaseOptions.html → services_staticMaps.StaticMapBaseOptions.html} +26 -45
  57. package/docs/types/services_staticMaps.StaticMapMarker.html +61 -0
  58. package/docs/variables/config.config.html +58 -0
  59. package/docs/variables/{LanguageGeocoding.html → language.LanguageGeocoding.html} +20 -42
  60. package/docs/variables/services_coordinates.coordinates.html +110 -0
  61. package/docs/variables/services_data.data.html +80 -0
  62. package/docs/variables/{geocoding.html → services_geocoding.geocoding.html} +35 -53
  63. package/docs/variables/services_geolocation.geolocation.html +79 -0
  64. package/docs/variables/services_staticMaps.staticMaps.html +128 -0
  65. package/docsmd/README.md +143 -36
  66. package/docsmd/assets/custom.css +118 -0
  67. package/docsmd/classes/ClientConfig.md +5 -5
  68. package/docsmd/classes/MapStyleVariant.md +217 -0
  69. package/docsmd/classes/ReferenceMapStyle.md +169 -0
  70. package/docsmd/classes/ServiceError.md +3 -3
  71. package/examples/test-browser-umd.html +1 -1
  72. package/images/maptiler-logo-256.png +0 -0
  73. package/package.json +5 -5
  74. package/readme.md +65 -5
  75. package/src/index.ts +17 -0
  76. package/src/mapstyle.ts +841 -0
  77. package/src/services/staticMaps.ts +5 -4
  78. package/tsconfig.json +0 -1
  79. package/typedoc.css +118 -0
  80. package/typedoc.json +7 -3
  81. package/docs/types/AutomaticStaticMapOptions.html +0 -80
  82. package/docs/types/BoundedStaticMapOptions.html +0 -80
  83. package/docs/types/CenteredStaticMapOptions.html +0 -80
  84. package/docs/types/CoordinateExport.html +0 -85
  85. package/docs/types/CoordinateGrid.html +0 -83
  86. package/docs/types/CoordinateId.html +0 -85
  87. package/docs/types/CoordinateSearch.html +0 -107
  88. package/docs/types/CoordinateSearchResult.html +0 -89
  89. package/docs/types/CoordinateTransformResult.html +0 -90
  90. package/docs/types/CoordinateTransformation.html +0 -103
  91. package/docs/types/Coordinates.html +0 -78
  92. package/docs/types/CoordinatesSearchOptions.html +0 -97
  93. package/docs/types/CoordinatesTransformOptions.html +0 -99
  94. package/docs/types/FeatureHierarchy.html +0 -89
  95. package/docs/types/FetchFunction.html +0 -93
  96. package/docs/types/GeocodingFeature.html +0 -78
  97. package/docs/types/GeocodingOptions.html +0 -97
  98. package/docs/types/GeocodingSearchResult.html +0 -95
  99. package/docs/types/GeolocationInfoOptions.html +0 -87
  100. package/docs/types/GeolocationResult.html +0 -150
  101. package/docs/types/GetDataOptions.html +0 -87
  102. package/docs/types/LanguageGeocodingString.html +0 -80
  103. package/docs/types/ReverseGeocodingOptions.html +0 -89
  104. package/docs/types/StaticMapMarker.html +0 -80
  105. package/docs/types/XYZ.html +0 -87
  106. package/docs/variables/config.html +0 -80
  107. package/docs/variables/coordinates-1.html +0 -124
  108. package/docs/variables/data.html +0 -103
  109. package/docs/variables/geolocation.html +0 -101
  110. package/docs/variables/staticMaps.html +0 -147
  111. package/docsmd/images/JS-logo.svg +0 -4
  112. package/docsmd/images/TS-logo.svg +0 -6
  113. package/docsmd/images/maptiler-client-logo.afdesign +0 -0
  114. package/docsmd/images/maptiler-client-logo.svg +0 -75
  115. package/docsmd/images/maptiler-logo.svg +0 -23
  116. package/docsmd/images/screenshots/static-bounded-europe-1024.png +0 -0
  117. package/docsmd/images/screenshots/static-bounded-europe-2048.png +0 -0
  118. package/docsmd/images/screenshots/static-bounded-portugal-1024x2048.png +0 -0
  119. package/docsmd/images/screenshots/static-bounded-portugal-2048x2048.png +0 -0
  120. package/docsmd/images/screenshots/static-with-path.png +0 -0
package/readme.md CHANGED
@@ -1,4 +1,5 @@
1
1
  <p align="center">
2
+ <a href="https://www.maptiler.com/">offcial page →</a><br>
2
3
  <img src="images/maptiler-client-logo.svg" width="400px">
3
4
  </p>
4
5
 
@@ -13,7 +14,10 @@
13
14
  <img src="https://img.shields.io/twitter/follow/maptiler?style=social"></img>
14
15
  </p>
15
16
 
16
- # What and why?
17
+ # API Client Library for JavaScript / TypeScript
18
+
19
+ ## What?
20
+
17
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:
18
22
  - Geocoding forward and reverse
19
23
  - Geolocation from visitor's IP address
@@ -21,8 +25,18 @@ The **MapTiler Client JS** exposes a number of handy functions that wrap API cal
21
25
  - User data fetching as GeoJSON
22
26
  - Static maps of all sorts
23
27
 
28
+ ## Why?
29
+
24
30
  The project is entirely written in TypeScript and all the function arguments are nicely documented and typed.
25
31
 
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
39
+
26
40
  > 📣 *__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!
27
41
 
28
42
  # Install
@@ -31,7 +45,7 @@ npm install --save @maptiler/client
31
45
  ```
32
46
 
33
47
  # API documentation
34
- In addition to the details and examples provided in this readme, check out the [complete API documentation](docs/README.md)).
48
+ In addition to the details and examples provided in this readme, check out the [complete API documentation](https://maptiler.github.io/maptiler-client-js).
35
49
 
36
50
  # Quick start
37
51
  ```ts
@@ -55,6 +69,8 @@ The [examples](examples/) folder includes are featuring usages for **NodeJS**, *
55
69
  Here is the list of service wrapper functions that are built-in:
56
70
 
57
71
  ## 🔍 Geocoding
72
+ > ✅ Please, use geocoding responses in the context of server-side rendering, hydration or client-side rendering, but 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) ⚖️
73
+
58
74
  ### Forward
59
75
  You want to know the longitude and latitude of a specific place, use the forward geocoding:
60
76
  ```ts
@@ -88,6 +104,8 @@ const result = await maptilerClient.geocoding.forward('paris', {language: [mapti
88
104
  The special language `AUTO` will detect the plateform/browser prefered language.
89
105
 
90
106
  ## 🕵️‍♂️ Geolocation
107
+ > ✅ Please, use geolocation responses in the context of server-side rendering, hydration or client-side rendering, but 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) ⚖️
108
+
91
109
  The geolocation service provides an accurate location insight of a website visitor using its IP address.
92
110
 
93
111
  There is only a single function:
@@ -99,6 +117,8 @@ const result = await maptilerClient.geolocation.info();
99
117
  Read more about geolocation on our official [API documentation](https://docs.maptiler.com/cloud/api/geolocation/).
100
118
 
101
119
  ## 🌐 Coordinates
120
+ > ✅ Please, use coordinate responses in the context of server-side rendering, hydration or client-side rendering, but 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) ⚖️
121
+
102
122
  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!
103
123
 
104
124
  ### Search
@@ -143,6 +163,8 @@ const result = await maptilerClient.data.get('my-dataset-unique-id')
143
163
  Since the result is a GeoJSON, it can easily be added to a `map` with `.addSource()` and `.addLayer()`.
144
164
 
145
165
  ## 🗺️ Static maps
166
+ > ✅ 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) ⚖️
167
+
146
168
  Maptiler Cloud provides many possibilities for creating static maps as PNG, JPEG or WebP images. They all offer the possibilities to:
147
169
  - Choose from one of the MapTiler style or your own
148
170
  - Add markers with a custom icon (or default icon with custom color)
@@ -152,6 +174,41 @@ Three modes are available: `centered`, `bounded` and `automatic`.
152
174
 
153
175
  > 📣 *__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.
154
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)
211
+
155
212
  ### Centered static maps
156
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).
157
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).
@@ -174,7 +231,7 @@ const imageLink = maptiler.staticMaps.centered(
174
231
  height: 1000,
175
232
 
176
233
  // Map style
177
- style: 'streets-v2',
234
+ style: maptilerClient.MapStyle.OUTDOOR,
178
235
  });
179
236
  ```
180
237
 
@@ -199,7 +256,7 @@ const imageLink = maptiler.staticMaps.bounded(
199
256
  hiDPI: true,
200
257
  width: 2048,
201
258
  height: 2048,
202
- style: 'streets-v2',
259
+ style: maptilerClient.MapStyle.STREETS.DARK,
203
260
 
204
261
  // Extra space that will add around the bounding box, in percentage
205
262
  // (0.1 = 10% is actually the dafault)
@@ -245,7 +302,7 @@ const imageLink = maptiler.staticMaps.automatic({
245
302
  height: 1024 ,
246
303
 
247
304
  // A grey style on which the track will pop!
248
- style: 'streets-v2-light',
305
+ style: maptilerClient.MapStyle.STREETS.LIGHT,
249
306
 
250
307
  // Draw a path with the trackpoints
251
308
  path: trackPoints,
@@ -285,3 +342,6 @@ config.fetch = fetch;
285
342
 
286
343
  // ...
287
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/) or contact us at **sales@maptiler.com** .
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
+ styleToStyle,
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
+ styleToStyle,
90
107
  };