@maptiler/client 1.1.0 → 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.
- package/dist/maptiler-client.cjs +122 -1
- package/dist/maptiler-client.cjs.map +1 -1
- package/dist/maptiler-client.d.ts +12 -2
- package/dist/maptiler-client.min.mjs +1 -1
- package/dist/maptiler-client.mjs +122 -1
- package/dist/maptiler-client.mjs.map +1 -1
- package/dist/maptiler-client.umd.js +122 -1
- package/dist/maptiler-client.umd.js.map +1 -1
- package/dist/maptiler-client.umd.min.js +1 -1
- package/docs/classes/config.ClientConfig.html +9 -9
- package/docs/classes/services_ServiceError.ServiceError.html +7 -7
- package/docs/functions/language.getAutoLanguageGeocoding.html +5 -5
- package/docs/functions/services_simplify.default.html +5 -5
- package/docs/index.html +28 -35
- package/docs/modules/config.html +5 -5
- package/docs/modules/language.html +5 -5
- package/docs/modules/services_ServiceError.html +5 -5
- package/docs/modules/services_coordinates.html +5 -5
- package/docs/modules/services_data.html +5 -5
- package/docs/modules/services_geocoding.html +5 -5
- package/docs/modules/services_geolocation.html +5 -5
- package/docs/modules/services_simplify.html +5 -5
- package/docs/modules/services_staticMaps.html +5 -5
- package/docs/modules.html +4 -4
- package/docs/types/config.FetchFunction.html +5 -5
- package/docs/types/language.LanguageGeocodingString.html +5 -5
- package/docs/types/services_coordinates.CoordinateExport.html +5 -5
- package/docs/types/services_coordinates.CoordinateGrid.html +5 -5
- package/docs/types/services_coordinates.CoordinateId.html +5 -5
- package/docs/types/services_coordinates.CoordinateSearch.html +5 -5
- package/docs/types/services_coordinates.CoordinateSearchResult.html +5 -5
- package/docs/types/services_coordinates.CoordinateTransformResult.html +5 -5
- package/docs/types/services_coordinates.CoordinateTransformation.html +5 -5
- package/docs/types/services_coordinates.CoordinatesSearchOptions.html +5 -5
- package/docs/types/services_coordinates.CoordinatesTransformOptions.html +5 -5
- package/docs/types/services_coordinates.XYZ.html +5 -5
- package/docs/types/services_data.GetDataOptions.html +5 -5
- package/docs/types/services_geocoding.Coordinates.html +5 -5
- package/docs/types/services_geocoding.FeatureHierarchy.html +5 -5
- package/docs/types/services_geocoding.GeocodingFeature.html +5 -5
- package/docs/types/services_geocoding.GeocodingOptions.html +5 -5
- package/docs/types/services_geocoding.GeocodingSearchResult.html +5 -5
- package/docs/types/services_geocoding.ReverseGeocodingOptions.html +5 -5
- package/docs/types/services_geolocation.GeolocationInfoOptions.html +5 -5
- package/docs/types/services_geolocation.GeolocationResult.html +5 -5
- package/docs/types/services_staticMaps.AutomaticStaticMapOptions.html +5 -5
- package/docs/types/services_staticMaps.BoundedStaticMapOptions.html +5 -5
- package/docs/types/services_staticMaps.CenteredStaticMapOptions.html +5 -5
- package/docs/types/services_staticMaps.StaticMapBaseOptions.html +5 -5
- package/docs/types/services_staticMaps.StaticMapMarker.html +5 -5
- package/docs/variables/config.config.html +5 -5
- package/docs/variables/language.LanguageGeocoding.html +5 -5
- package/docs/variables/services_coordinates.coordinates.html +5 -5
- package/docs/variables/services_data.data.html +5 -5
- package/docs/variables/services_geocoding.geocoding.html +5 -5
- package/docs/variables/services_geolocation.geolocation.html +5 -5
- package/docs/variables/services_staticMaps.staticMaps.html +5 -5
- package/docsmd/README.md +46 -44
- package/docsmd/classes/ClientConfig.md +5 -5
- package/docsmd/classes/MapStyleVariant.md +29 -12
- package/docsmd/classes/ReferenceMapStyle.md +9 -9
- package/docsmd/classes/ServiceError.md +3 -3
- package/package.json +1 -1
- package/readme.md +28 -28
- package/src/index.ts +2 -2
- package/src/mapstyle.ts +33 -0
package/readme.md
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
<p align="center">
|
|
2
|
-
<a href="https://
|
|
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
|
|
|
@@ -19,11 +19,11 @@
|
|
|
19
19
|
## What?
|
|
20
20
|
|
|
21
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:
|
|
22
|
-
- Geocoding forward and reverse
|
|
23
|
-
- Geolocation from visitor's IP address
|
|
24
|
-
- Coordidinate systems search and tranform
|
|
25
|
-
- User data fetching as GeoJSON
|
|
26
|
-
- 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
27
|
|
|
28
28
|
## Why?
|
|
29
29
|
|
|
@@ -37,8 +37,6 @@ The project is entirely written in TypeScript and all the function arguments are
|
|
|
37
37
|
- Runs: in Node.js or in browser
|
|
38
38
|
- Open source license
|
|
39
39
|
|
|
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!
|
|
41
|
-
|
|
42
40
|
# Install
|
|
43
41
|
```shell
|
|
44
42
|
npm install --save @maptiler/client
|
|
@@ -69,7 +67,7 @@ The [examples](examples/) folder includes are featuring usages for **NodeJS**, *
|
|
|
69
67
|
Here is the list of service wrapper functions that are built-in:
|
|
70
68
|
|
|
71
69
|
## 🔍 Geocoding
|
|
72
|
-
> ✅ Please, use 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) ⚖️
|
|
73
71
|
|
|
74
72
|
### Forward
|
|
75
73
|
You want to know the longitude and latitude of a specific place, use the forward geocoding:
|
|
@@ -82,7 +80,7 @@ You can provide some options such as:
|
|
|
82
80
|
- one of more languages to get the results into
|
|
83
81
|
- a bounding geo box, to restrict the search to a given window
|
|
84
82
|
|
|
85
|
-
Read more about forward geocoding on our official
|
|
83
|
+
Read more about forward geocoding on our [official documentation](https://docs.maptiler.com/client-js/geocoding/#forward).
|
|
86
84
|
|
|
87
85
|
### Reverse
|
|
88
86
|
You wan to tknow the name of a place, given a longitude-latitude? Use the reverse geocoding:
|
|
@@ -92,7 +90,7 @@ const result = await maptilerClient.geocoding.reverse([6.249638, 46.402056]);
|
|
|
92
90
|
```
|
|
93
91
|
The same option object as the forward geocoding can be provided.
|
|
94
92
|
|
|
95
|
-
Read more about reverse geocoding on our official
|
|
93
|
+
Read more about reverse geocoding on our [official documentation](https://docs.maptiler.com/client-js/geocoding/#reverse).
|
|
96
94
|
|
|
97
95
|
### Language
|
|
98
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:
|
|
@@ -101,12 +99,12 @@ For both *forward* and *reverse* geocoding, this library provides a list of supp
|
|
|
101
99
|
const result = await maptilerClient.geocoding.forward('paris', {language: [maptilerClient.geocoding.languages.SPANISH, maptilerClient.geocoding.languages.KOREAN]})
|
|
102
100
|
```
|
|
103
101
|
|
|
104
|
-
The special language `AUTO` will detect the
|
|
102
|
+
The special language `AUTO` will detect the platform/browser preferred language.
|
|
105
103
|
|
|
106
104
|
## 🕵️♂️ Geolocation
|
|
107
|
-
|
|
105
|
+
The geolocation service provides location informations of a visitor using its IP address.
|
|
108
106
|
|
|
109
|
-
The geolocation
|
|
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.
|
|
110
108
|
|
|
111
109
|
There is only a single function:
|
|
112
110
|
```ts
|
|
@@ -114,11 +112,9 @@ There is only a single function:
|
|
|
114
112
|
const result = await maptilerClient.geolocation.info();
|
|
115
113
|
```
|
|
116
114
|
|
|
117
|
-
Read more about geolocation on our official
|
|
115
|
+
Read more about geolocation on our [official documentation](https://docs.maptiler.com/client-js/geolocation/).
|
|
118
116
|
|
|
119
117
|
## 🌐 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
|
-
|
|
122
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!
|
|
123
119
|
|
|
124
120
|
### Search
|
|
@@ -133,7 +129,7 @@ const resultD = await maptilerClient.coordinates.search('code:4326', {transforma
|
|
|
133
129
|
|
|
134
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.
|
|
135
131
|
|
|
136
|
-
Read more about searching coordinate systems on our official
|
|
132
|
+
Read more about searching coordinate systems on our [official documentation](https://docs.maptiler.com/client-js/coordinates/#search).
|
|
137
133
|
|
|
138
134
|
### Transform
|
|
139
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).
|
|
@@ -150,7 +146,7 @@ const resultA = await maptilerClient.coordinates.transform([1, 45], {targetCrs:
|
|
|
150
146
|
const resultB = await maptilerClient.coordinates.transform([[10, 48], [1, 45]], {targetCrs: 9793})
|
|
151
147
|
```
|
|
152
148
|
|
|
153
|
-
Read more about transforming coordinates on our official
|
|
149
|
+
Read more about transforming coordinates on our [official documentation](https://docs.maptiler.com/client-js/coordinates/#transform).
|
|
154
150
|
|
|
155
151
|
## 💽 Data
|
|
156
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:
|
|
@@ -162,6 +158,8 @@ const result = await maptilerClient.data.get('my-dataset-unique-id')
|
|
|
162
158
|
|
|
163
159
|
Since the result is a GeoJSON, it can easily be added to a `map` with `.addSource()` and `.addLayer()`.
|
|
164
160
|
|
|
161
|
+
Read more about fetching your own data on our [official documentation](https://docs.maptiler.com/client-js/data/).
|
|
162
|
+
|
|
165
163
|
## 🗺️ Static maps
|
|
166
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) ⚖️
|
|
167
165
|
|
|
@@ -172,7 +170,9 @@ Maptiler Cloud provides many possibilities for creating static maps as PNG, JPEG
|
|
|
172
170
|
|
|
173
171
|
Three modes are available: `centered`, `bounded` and `automatic`.
|
|
174
172
|
|
|
175
|
-
> 📣 *__important:__*
|
|
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
176
|
|
|
177
177
|
### Map Styles
|
|
178
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:
|
|
@@ -214,7 +214,7 @@ This type of map is centered on a longitude-latitude coordinate and the zoom lev
|
|
|
214
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).
|
|
215
215
|
|
|
216
216
|
```ts
|
|
217
|
-
const imageLink =
|
|
217
|
+
const imageLink = maptilerClient.staticMaps.centered(
|
|
218
218
|
// center position (Boston)
|
|
219
219
|
[-71.06080, 42.362114],
|
|
220
220
|
|
|
@@ -242,7 +242,7 @@ Read more about centered static maps on our official [API documentation](https:/
|
|
|
242
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.
|
|
243
243
|
|
|
244
244
|
```ts
|
|
245
|
-
const imageLink =
|
|
245
|
+
const imageLink = maptilerClient.staticMaps.bounded(
|
|
246
246
|
// The bounding box on Europe
|
|
247
247
|
[
|
|
248
248
|
-24, // west bound (min x)
|
|
@@ -270,7 +270,7 @@ Since the zoom level cannot be provided, the level of details is dictated by the
|
|
|
270
270
|
| :-----------: | :-----------: |
|
|
271
271
|
|  |  |
|
|
272
272
|
|
|
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
|
|
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%:
|
|
274
274
|
|
|
275
275
|
|
|
276
276
|
| `2048 x 2048` | `1024 x 2048` |
|
|
@@ -283,7 +283,7 @@ Read more about bounded static maps on our official [API documentation](https://
|
|
|
283
283
|
### Automatic static maps
|
|
284
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.
|
|
285
285
|
|
|
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
|
|
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:
|
|
287
287
|
|
|
288
288
|
```ts
|
|
289
289
|
// Fetching the GeoJSON
|
|
@@ -293,11 +293,11 @@ const bikeTrack = await maptilerClient.data.get('the-id-of-a-bike-track-in-montr
|
|
|
293
293
|
const trackPoints = bikeTrack.features[0].geometry.coordinates[0]
|
|
294
294
|
.map(p => p.slice(0, 2));
|
|
295
295
|
|
|
296
|
-
const imageLink =
|
|
296
|
+
const imageLink = maptilerClient.staticMaps.automatic({
|
|
297
297
|
// hiDPI/Retina precision
|
|
298
298
|
hiDPI: true,
|
|
299
299
|
|
|
300
|
-
// A
|
|
300
|
+
// A fairly large output image
|
|
301
301
|
width: 2048,
|
|
302
302
|
height: 1024 ,
|
|
303
303
|
|
|
@@ -319,7 +319,7 @@ And voila!
|
|
|
319
319
|
|
|
320
320
|

|
|
321
321
|
|
|
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
|
|
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).
|
|
323
323
|
|
|
324
324
|
Read more about bounded static maps on our official [API documentation](https://docs.maptiler.com/cloud/api/static-maps/#auto-fitted-image).
|
|
325
325
|
|
|
@@ -344,4 +344,4 @@ config.fetch = fetch;
|
|
|
344
344
|
```
|
|
345
345
|
|
|
346
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
|
|
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
|
@@ -51,7 +51,7 @@ import {
|
|
|
51
51
|
ReferenceMapStyle,
|
|
52
52
|
mapStylePresetList,
|
|
53
53
|
MapStyle,
|
|
54
|
-
|
|
54
|
+
expandMapStyle,
|
|
55
55
|
} from "./mapstyle";
|
|
56
56
|
|
|
57
57
|
// Exporting types
|
|
@@ -103,5 +103,5 @@ export {
|
|
|
103
103
|
ReferenceMapStyle,
|
|
104
104
|
mapStylePresetList,
|
|
105
105
|
MapStyle,
|
|
106
|
-
|
|
106
|
+
expandMapStyle,
|
|
107
107
|
};
|
package/src/mapstyle.ts
CHANGED
|
@@ -1,3 +1,28 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Expand the map style provided as argument of the Map constructor
|
|
3
|
+
* @param style
|
|
4
|
+
* @returns
|
|
5
|
+
*/
|
|
6
|
+
export function expandMapStyle(style): string {
|
|
7
|
+
// testing if the style provided is of form "maptiler://some-style"
|
|
8
|
+
const maptilerDomainRegex = /^maptiler:\/\/(.*)/;
|
|
9
|
+
let match;
|
|
10
|
+
const trimmed = style.trim();
|
|
11
|
+
let expandedStyle;
|
|
12
|
+
|
|
13
|
+
// The style was possibly already given as expanded URL
|
|
14
|
+
if (trimmed.startsWith("http://") || trimmed.startsWith("https://")) {
|
|
15
|
+
expandedStyle = trimmed;
|
|
16
|
+
} else if ((match = maptilerDomainRegex.exec(trimmed)) !== null) {
|
|
17
|
+
expandedStyle = `https://api.maptiler.com/maps/${match[1]}/style.json`;
|
|
18
|
+
} else {
|
|
19
|
+
// The style could also possibly just be the name of the style without any URI style
|
|
20
|
+
expandedStyle = `https://api.maptiler.com/maps/${trimmed}/style.json`;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
return expandedStyle;
|
|
24
|
+
}
|
|
25
|
+
|
|
1
26
|
/**
|
|
2
27
|
* Type for object containing style details
|
|
3
28
|
*/
|
|
@@ -128,6 +153,14 @@ export class MapStyleVariant {
|
|
|
128
153
|
getImageURL(): string {
|
|
129
154
|
return this.imageURL;
|
|
130
155
|
}
|
|
156
|
+
|
|
157
|
+
/**
|
|
158
|
+
* Get the style as usable by MapLibre, a string (URL) or a plain style description (StyleSpecification)
|
|
159
|
+
* @returns
|
|
160
|
+
*/
|
|
161
|
+
getExpandedStyleURL(): string {
|
|
162
|
+
return expandMapStyle(this.getId());
|
|
163
|
+
}
|
|
131
164
|
}
|
|
132
165
|
|
|
133
166
|
/**
|