@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.
- package/.github/workflows/npm-publish.yml +0 -1
- package/dist/maptiler-client.cjs +465 -21
- package/dist/maptiler-client.cjs.map +1 -1
- package/dist/maptiler-client.d.ts +395 -2
- package/dist/maptiler-client.min.mjs +1 -1
- package/dist/maptiler-client.mjs +461 -22
- package/dist/maptiler-client.mjs.map +1 -1
- package/dist/maptiler-client.umd.js +465 -21
- package/dist/maptiler-client.umd.js.map +1 -1
- package/dist/maptiler-client.umd.min.js +1 -1
- package/docs/assets/custom.css +118 -0
- package/docs/assets/highlight.css +10 -10
- package/docs/assets/main.js +56 -52
- package/docs/assets/search.js +1 -1
- package/docs/assets/style.css +23 -0
- package/docs/classes/{ClientConfig.html → config.ClientConfig.html} +34 -24
- package/docs/classes/{ServiceError.html → services_ServiceError.ServiceError.html} +26 -16
- package/docs/functions/language.getAutoLanguageGeocoding.html +60 -0
- package/docs/functions/services_simplify.default.html +65 -0
- package/docs/images/maptiler-logo-256.png +0 -0
- package/docs/index.html +118 -57
- package/docs/modules/config.html +71 -0
- package/docs/modules/language.html +71 -0
- package/docs/modules/services_ServiceError.html +61 -0
- package/docs/modules/services_coordinates.html +84 -0
- package/docs/modules/services_data.html +66 -0
- package/docs/modules/services_geocoding.html +76 -0
- package/docs/modules/services_geolocation.html +68 -0
- package/docs/modules/services_simplify.html +61 -0
- package/docs/modules/services_staticMaps.html +74 -0
- package/docs/modules.html +23 -83
- package/docs/types/config.FetchFunction.html +71 -0
- package/docs/types/language.LanguageGeocodingString.html +58 -0
- package/docs/types/services_coordinates.CoordinateExport.html +71 -0
- package/docs/types/services_coordinates.CoordinateGrid.html +69 -0
- package/docs/types/services_coordinates.CoordinateId.html +71 -0
- package/docs/types/services_coordinates.CoordinateSearch.html +93 -0
- package/docs/types/services_coordinates.CoordinateSearchResult.html +75 -0
- package/docs/types/services_coordinates.CoordinateTransformResult.html +76 -0
- package/docs/types/services_coordinates.CoordinateTransformation.html +89 -0
- package/docs/types/services_coordinates.CoordinatesSearchOptions.html +83 -0
- package/docs/types/services_coordinates.CoordinatesTransformOptions.html +85 -0
- package/docs/types/services_coordinates.XYZ.html +73 -0
- package/docs/types/services_data.GetDataOptions.html +64 -0
- package/docs/types/services_geocoding.Coordinates.html +60 -0
- package/docs/types/services_geocoding.FeatureHierarchy.html +71 -0
- package/docs/types/services_geocoding.GeocodingFeature.html +60 -0
- package/docs/types/services_geocoding.GeocodingOptions.html +79 -0
- package/docs/types/services_geocoding.GeocodingSearchResult.html +77 -0
- package/docs/types/services_geocoding.ReverseGeocodingOptions.html +71 -0
- package/docs/types/services_geolocation.GeolocationInfoOptions.html +65 -0
- package/docs/types/services_geolocation.GeolocationResult.html +128 -0
- package/docs/types/services_staticMaps.AutomaticStaticMapOptions.html +61 -0
- package/docs/types/services_staticMaps.BoundedStaticMapOptions.html +61 -0
- package/docs/types/services_staticMaps.CenteredStaticMapOptions.html +61 -0
- package/docs/types/{StaticMapBaseOptions.html → services_staticMaps.StaticMapBaseOptions.html} +26 -45
- package/docs/types/services_staticMaps.StaticMapMarker.html +61 -0
- package/docs/variables/config.config.html +58 -0
- package/docs/variables/{LanguageGeocoding.html → language.LanguageGeocoding.html} +20 -42
- package/docs/variables/services_coordinates.coordinates.html +110 -0
- package/docs/variables/services_data.data.html +80 -0
- package/docs/variables/{geocoding.html → services_geocoding.geocoding.html} +35 -53
- package/docs/variables/services_geolocation.geolocation.html +79 -0
- package/docs/variables/services_staticMaps.staticMaps.html +128 -0
- package/docsmd/README.md +143 -36
- package/docsmd/assets/custom.css +118 -0
- package/docsmd/classes/ClientConfig.md +5 -5
- package/docsmd/classes/MapStyleVariant.md +217 -0
- package/docsmd/classes/ReferenceMapStyle.md +169 -0
- package/docsmd/classes/ServiceError.md +3 -3
- package/examples/test-browser-umd.html +1 -1
- package/images/maptiler-logo-256.png +0 -0
- package/package.json +5 -5
- package/readme.md +65 -5
- package/src/index.ts +17 -0
- package/src/mapstyle.ts +841 -0
- package/src/services/staticMaps.ts +5 -4
- package/tsconfig.json +0 -1
- package/typedoc.css +118 -0
- package/typedoc.json +7 -3
- package/docs/types/AutomaticStaticMapOptions.html +0 -80
- package/docs/types/BoundedStaticMapOptions.html +0 -80
- package/docs/types/CenteredStaticMapOptions.html +0 -80
- package/docs/types/CoordinateExport.html +0 -85
- package/docs/types/CoordinateGrid.html +0 -83
- package/docs/types/CoordinateId.html +0 -85
- package/docs/types/CoordinateSearch.html +0 -107
- package/docs/types/CoordinateSearchResult.html +0 -89
- package/docs/types/CoordinateTransformResult.html +0 -90
- package/docs/types/CoordinateTransformation.html +0 -103
- package/docs/types/Coordinates.html +0 -78
- package/docs/types/CoordinatesSearchOptions.html +0 -97
- package/docs/types/CoordinatesTransformOptions.html +0 -99
- package/docs/types/FeatureHierarchy.html +0 -89
- package/docs/types/FetchFunction.html +0 -93
- package/docs/types/GeocodingFeature.html +0 -78
- package/docs/types/GeocodingOptions.html +0 -97
- package/docs/types/GeocodingSearchResult.html +0 -95
- package/docs/types/GeolocationInfoOptions.html +0 -87
- package/docs/types/GeolocationResult.html +0 -150
- package/docs/types/GetDataOptions.html +0 -87
- package/docs/types/LanguageGeocodingString.html +0 -80
- package/docs/types/ReverseGeocodingOptions.html +0 -89
- package/docs/types/StaticMapMarker.html +0 -80
- package/docs/types/XYZ.html +0 -87
- package/docs/variables/config.html +0 -80
- package/docs/variables/coordinates-1.html +0 -124
- package/docs/variables/data.html +0 -103
- package/docs/variables/geolocation.html +0 -101
- package/docs/variables/staticMaps.html +0 -147
- package/docsmd/images/JS-logo.svg +0 -4
- package/docsmd/images/TS-logo.svg +0 -6
- package/docsmd/images/maptiler-client-logo.afdesign +0 -0
- package/docsmd/images/maptiler-client-logo.svg +0 -75
- package/docsmd/images/maptiler-logo.svg +0 -23
- package/docsmd/images/screenshots/static-bounded-europe-1024.png +0 -0
- package/docsmd/images/screenshots/static-bounded-europe-2048.png +0 -0
- package/docsmd/images/screenshots/static-bounded-portugal-1024x2048.png +0 -0
- package/docsmd/images/screenshots/static-bounded-portugal-2048x2048.png +0 -0
- 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
|
-
#
|
|
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](
|
|
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:
|
|
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:
|
|
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:
|
|
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
|
};
|