@maptiler/client 1.7.0 → 1.8.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 (38) hide show
  1. package/.github/pull_request_template.md +11 -0
  2. package/.github/workflows/format-lint.yml +24 -0
  3. package/CHANGELOG.md +25 -0
  4. package/dist/maptiler-client.cjs +388 -306
  5. package/dist/maptiler-client.cjs.map +1 -1
  6. package/dist/maptiler-client.d.ts +270 -100
  7. package/dist/maptiler-client.min.mjs +1 -1
  8. package/dist/maptiler-client.mjs +380 -294
  9. package/dist/maptiler-client.mjs.map +1 -1
  10. package/package.json +7 -5
  11. package/readme.md +133 -1
  12. package/rollup.config.js +3 -3
  13. package/dist/maptiler-client.umd.js +0 -1541
  14. package/dist/maptiler-client.umd.js.map +0 -1
  15. package/dist/maptiler-client.umd.min.js +0 -1
  16. package/examples/test-browser-es.html +0 -103
  17. package/examples/test-browser-umd.html +0 -90
  18. package/examples/test-node.js +0 -52
  19. package/src/callFetch.ts +0 -18
  20. package/src/config.ts +0 -68
  21. package/src/defaults.ts +0 -11
  22. package/src/demProfiler/getElevation.ts +0 -46
  23. package/src/demProfiler/index.ts +0 -240
  24. package/src/demProfiler/tileCover.ts +0 -96
  25. package/src/geometry/area.ts +0 -96
  26. package/src/geometry/distance.ts +0 -45
  27. package/src/geometry/index.ts +0 -3
  28. package/src/geometry/util.ts +0 -34
  29. package/src/index.ts +0 -114
  30. package/src/language.ts +0 -87
  31. package/src/mapstyle.ts +0 -968
  32. package/src/services/ServiceError.ts +0 -13
  33. package/src/services/coordinates.ts +0 -263
  34. package/src/services/data.ts +0 -63
  35. package/src/services/geocoding.ts +0 -461
  36. package/src/services/geolocation.ts +0 -139
  37. package/src/services/simplify.ts +0 -87
  38. package/src/services/staticMaps.ts +0 -463
@@ -1,461 +0,0 @@
1
- import { BBox, Feature, Geometry, Position } from "geojson";
2
- import { callFetch } from "../callFetch";
3
- import { config } from "../config";
4
- import { defaults } from "../defaults";
5
-
6
- import {
7
- getAutoLanguageGeocoding,
8
- LanguageGeocoding,
9
- LanguageGeocodingString,
10
- } from "../language";
11
- import { ServiceError } from "./ServiceError";
12
-
13
- const customMessages = {
14
- 400: "Query too long / Invalid parameters",
15
- 403: "Key is missing, invalid or restricted",
16
- };
17
-
18
- export type LanguageGeocodingOptions = {
19
- /**
20
- * Prefer results in specific language. It’s possible to specify multiple values.
21
- */
22
- language?: LanguageGeocodingString | Array<LanguageGeocodingString>;
23
- };
24
-
25
- export type CommonForwardAndReverseGeocodingOptions =
26
- LanguageGeocodingOptions & {
27
- /**
28
- * Custom MapTiler Cloud API key to use instead of the one in global `config`
29
- */
30
- apiKey?: string;
31
-
32
- /**
33
- * Maximum number of results to show. Must be between 1 and 10. Default is 5 for forward and 1 for reverse geocoding.
34
- */
35
- limit?: number;
36
-
37
- /**
38
- * Filter of feature types to return. If not specified, all available feature types are returned.
39
- */
40
- types?: (
41
- | "country"
42
- | "region"
43
- | "subregion"
44
- | "county"
45
- | "joint_municipality"
46
- | "joint_submunicipality"
47
- | "municipality"
48
- | "municipal_district"
49
- | "locality"
50
- | "neighbourhood"
51
- | "place"
52
- | "postal_code"
53
- | "address"
54
- | "poi"
55
- )[];
56
- };
57
-
58
- export type GeocodingOptions = CommonForwardAndReverseGeocodingOptions & {
59
- /**
60
- * Only search for results in the specified area.
61
- */
62
- bbox?: BBox;
63
-
64
- /**
65
- * Prefer results close to a specific location.
66
- */
67
- proximity?: Position;
68
-
69
- /**
70
- * Limit search to specific country/countries specified as list of Alpha-2 ISO 3166-1 codes.
71
- */
72
- country?: string[];
73
-
74
- /**
75
- * Set to `false` to disable fuzzy (typo-tolerant) search. Default is `true`.
76
- */
77
- fuzzyMatch?: boolean;
78
-
79
- /**
80
- * Set to `true` to use autocomplete, `false` to disable it.
81
- * Default (`undefined`) is to combine autocomplete with non-autocomplete results.
82
- */
83
- autocomplete?: boolean;
84
- };
85
-
86
- export type ReverseGeocodingOptions = CommonForwardAndReverseGeocodingOptions;
87
-
88
- export type ByIdGeocodingOptions = LanguageGeocodingOptions & {
89
- apiKey?: string;
90
- };
91
-
92
- export type Coordinates = Position;
93
-
94
- type FeatureProperties = {
95
- /**
96
- * External reference of the feature used for debugging purposes
97
- */
98
- ref: string;
99
-
100
- /**
101
- * ISO 3166-1 alpha-2 country code of the feature
102
- */
103
- country_code: string;
104
-
105
- /**
106
- * (experimental) Kind of the feature
107
- */
108
- kind?:
109
- | "road"
110
- | "road_relation"
111
- | "admin_area"
112
- | "place"
113
- | "street"
114
- | "virtual_street";
115
-
116
- /**
117
- * (experimental) Value of place=* tag from OpenStreetMap feature if kind=place
118
- */
119
- "osm:place_type"?: string;
120
-
121
- /**
122
- * (experimental) Feature tags from OpenStreetMap. Only available for `poi` type.
123
- */
124
- "osm:tags"?: Record<string, string>;
125
-
126
- /**
127
- * Array of POI categories. Only available for `poi` type.
128
- */
129
- categories?: string[];
130
- };
131
-
132
- type FeatureBase = {
133
- /**
134
- * Unique feature ID
135
- */
136
- id: string;
137
-
138
- /**
139
- * Localized feature name
140
- */
141
- text: string;
142
-
143
- /**
144
- * Query's primary ISO 639-1 language code
145
- */
146
- language?: string;
147
-
148
- /**
149
- * A string analogous to the `text` field that matches the query in the requested language.
150
- * This field is only returned when multiple languages are requested using the `language` parameter, and will be present for each requested language.
151
- */
152
- [text: `text_${string}`]: string;
153
-
154
- /**
155
- * A ISO 639-1 query's fallback language code.
156
- * This field is only returned when multiple languages are requested using the `language` parameter, and will be present for each requested language.
157
- */
158
- [language: `language_${string}`]: string;
159
- };
160
-
161
- export type FeatureHierarchy = FeatureProperties & FeatureBase;
162
-
163
- export type GeocodingFeature = Feature<Geometry, FeatureProperties> &
164
- FeatureBase & {
165
- /**
166
- * Bounding box of the original feature as [w, s, e, n] array
167
- */
168
- bbox: BBox;
169
-
170
- /**
171
- * A [lon, lat] array of the original feature centeroid
172
- */
173
- center: Coordinates;
174
-
175
- /**
176
- * Formatted (including the hierarchy) and localized feature full name
177
- */
178
- place_name: string;
179
-
180
- /**
181
- * A string analogous to the `place_name` field that matches the query in the requested language.
182
- * This field is only returned when multiple languages are requested using the `language` parameter, and will be present for each requested language.
183
- */
184
- [key: `place_name_${string}`]: string;
185
-
186
- /**
187
- * An array of feature types describing the feature.
188
- * Currently each feature has only single type but this may change in the future.
189
- */
190
- place_type: string[];
191
-
192
- /**
193
- * Localized type of the place name, matches `place_type` property
194
- */
195
- place_type_name: string[];
196
-
197
- /**
198
- * Feature hierarchy
199
- */
200
- context?: Array<FeatureHierarchy>;
201
-
202
- /**
203
- * Address number, if applicable
204
- */
205
- address?: string;
206
-
207
- /**
208
- * Indicates how well the returned feature matches the user's query on a scale from 0 to 1.
209
- * 0 means the result does not match the query text at all, while 1 means the result fully matches the query text.
210
- * You can use the relevance property to remove results that don't fully match the query.
211
- */
212
- relevance: number;
213
- };
214
-
215
- export type GeocodingSearchResult = {
216
- type: "FeatureCollection";
217
-
218
- /**
219
- * Array of features found
220
- */
221
- features: Array<GeocodingFeature>;
222
-
223
- /**
224
- * Tokenized search query
225
- */
226
- query: Array<string>;
227
-
228
- /**
229
- * Attribution of the result
230
- */
231
- attribution: string;
232
- };
233
-
234
- function addLanguageGeocodingOptions(
235
- searchParams: URLSearchParams,
236
- options: LanguageGeocodingOptions,
237
- ) {
238
- if (options.language == undefined) {
239
- return;
240
- }
241
-
242
- const languages = Array.from(
243
- new Set(
244
- (Array.isArray(options.language)
245
- ? options.language
246
- : [options.language]
247
- ).map((lang) =>
248
- lang === LanguageGeocoding.AUTO ? getAutoLanguageGeocoding() : lang,
249
- ),
250
- ),
251
- ).join(",");
252
-
253
- searchParams.set("language", languages);
254
- }
255
-
256
- function addCommonForwardAndReverseGeocodingOptions(
257
- searchParams: URLSearchParams,
258
- options: CommonForwardAndReverseGeocodingOptions,
259
- ) {
260
- searchParams.set("key", options.apiKey ?? config.apiKey);
261
-
262
- if (options.limit != undefined) {
263
- searchParams.set("limit", String(options.limit));
264
- }
265
-
266
- if (options.types != undefined) {
267
- searchParams.set("types", options.types.join(","));
268
- }
269
-
270
- addLanguageGeocodingOptions(searchParams, options);
271
- }
272
-
273
- function addForwardGeocodingOptions(
274
- searchParams: URLSearchParams,
275
- options: GeocodingOptions,
276
- ) {
277
- addCommonForwardAndReverseGeocodingOptions(searchParams, options);
278
-
279
- if (options.bbox != undefined) {
280
- searchParams.set("bbox", options.bbox.join(","));
281
- }
282
-
283
- if (options.proximity != undefined) {
284
- searchParams.set("proximity", options.proximity.join(","));
285
- }
286
-
287
- if (options.country != undefined) {
288
- searchParams.set("country", options.country.join(","));
289
- }
290
-
291
- if (options.fuzzyMatch != undefined) {
292
- searchParams.set("fuzzyMatch", options.fuzzyMatch ? "true" : "false");
293
- }
294
-
295
- if (options.autocomplete != undefined) {
296
- searchParams.set("autocomplete", options.autocomplete ? "true" : "false");
297
- }
298
- }
299
-
300
- /**
301
- * Performs a forward geocoding query to MapTiler API.
302
- * Providing a human readable place name (of a city, country, street, etc.), the function returns
303
- * a list of candidate locations including longitude and latitude.
304
- * Learn more on the MapTiler API reference page: https://docs.maptiler.com/cloud/api/geocoding/#search-by-name-forward
305
- * @param query
306
- * @param options
307
- * @returns
308
- */
309
- async function forward(
310
- query: string,
311
- options: GeocodingOptions = {},
312
- ): Promise<GeocodingSearchResult> {
313
- if (typeof query !== "string" || query.trim().length === 0) {
314
- throw new Error("The query must be a non-empty string");
315
- }
316
-
317
- const endpoint = new URL(
318
- `geocoding/${encodeURIComponent(query)}.json`,
319
- defaults.maptilerApiURL,
320
- );
321
-
322
- const { searchParams } = endpoint;
323
-
324
- addForwardGeocodingOptions(searchParams, options);
325
-
326
- const urlWithParams = endpoint.toString();
327
-
328
- const res = await callFetch(urlWithParams);
329
-
330
- if (!res.ok) {
331
- throw new ServiceError(res, customMessages[res.status] ?? "");
332
- }
333
-
334
- const obj: GeocodingSearchResult = await res.json();
335
-
336
- return obj;
337
- }
338
-
339
- /**
340
- * Perform a reverse geocoding query to MapTiler API.
341
- * Providing a longitude and latitude, this function returns a set of human readable information about this place (country, city, street, etc.)
342
- * Learn more on the MapTiler API reference page: https://docs.maptiler.com/cloud/api/geocoding/#search-by-coordinates-reverse
343
- * @param position
344
- * @param options
345
- * @returns
346
- */
347
- async function reverse(
348
- position: Position,
349
- options: ReverseGeocodingOptions = {},
350
- ): Promise<GeocodingSearchResult> {
351
- if (!Array.isArray(position) || position.length < 2) {
352
- throw new Error("The position must be an array of form [lng, lat].");
353
- }
354
-
355
- const endpoint = new URL(
356
- `geocoding/${position[0]},${position[1]}.json`,
357
- defaults.maptilerApiURL,
358
- );
359
-
360
- addCommonForwardAndReverseGeocodingOptions(endpoint.searchParams, options);
361
-
362
- const urlWithParams = endpoint.toString();
363
-
364
- const res = await callFetch(urlWithParams);
365
-
366
- if (!res.ok) {
367
- throw new ServiceError(res, customMessages[res.status] ?? "");
368
- }
369
-
370
- const obj: GeocodingSearchResult = await res.json();
371
-
372
- return obj;
373
- }
374
-
375
- /**
376
- * Perform a geocoding query to MapTiler API to obtain fature by its ID.
377
- * Providing a feature ID, this function returns a feature which includes its full geometry.
378
- * Note that the feature ID is not stable and it changes when the database is re-indexed.
379
- * Learn more on the MapTiler API reference page: https://docs.maptiler.com/cloud/api/geocoding/#search-by-feature-id
380
- * @param id
381
- * @param options
382
- * @returns
383
- */
384
- async function byId(
385
- id: string,
386
- options: ByIdGeocodingOptions = {},
387
- ): Promise<GeocodingSearchResult> {
388
- const endpoint = new URL(`geocoding/${id}.json`, defaults.maptilerApiURL);
389
- endpoint.searchParams.set("key", options.apiKey ?? config.apiKey);
390
-
391
- addLanguageGeocodingOptions(endpoint.searchParams, options);
392
-
393
- const urlWithParams = endpoint.toString();
394
-
395
- const res = await callFetch(urlWithParams);
396
-
397
- if (!res.ok) {
398
- throw new ServiceError(res, customMessages[res.status] ?? "");
399
- }
400
-
401
- const obj: GeocodingSearchResult = await res.json();
402
-
403
- return obj;
404
- }
405
-
406
- /**
407
- * Perform a batch geocoding query to MapTiler API.
408
- * Provide multiple queries in the array. Each query can be forward, reverse or by feature ID.
409
- * Learn more on the MapTiler API reference page: https://docs.maptiler.com/cloud/api/geocoding/#batch-geocoding
410
- * @param queries
411
- * @param options
412
- * @returns
413
- */
414
- async function batch(
415
- queries: string[],
416
- options: GeocodingOptions = {},
417
- ): Promise<GeocodingSearchResult[]> {
418
- if (!queries.length) {
419
- return [];
420
- }
421
-
422
- const joinedQuery = queries
423
- .map((query) => encodeURIComponent(query))
424
- .join(";");
425
-
426
- const endpoint = new URL(
427
- `geocoding/${joinedQuery}.json`,
428
- defaults.maptilerApiURL,
429
- );
430
-
431
- const { searchParams } = endpoint;
432
-
433
- addForwardGeocodingOptions(searchParams, options);
434
-
435
- const urlWithParams = endpoint.toString();
436
-
437
- const res = await callFetch(urlWithParams);
438
-
439
- if (!res.ok) {
440
- throw new ServiceError(res, customMessages[res.status] ?? "");
441
- }
442
-
443
- const obj = await res.json();
444
-
445
- return queries.length === 1 ? [obj] : obj;
446
- }
447
-
448
- /**
449
- * The **geocoding** namespace contains asynchronous functions to call the [MapTiler Geocoding API](https://docs.maptiler.com/cloud/api/geocoding/).
450
- * The **Geocoding API** provides ways to get geographic coordinates from a human-readable search query of a place (forward geocoding)
451
- * and to get the location details (country, city, street, etc.) from a geographic coordinate (reverse geocoding);
452
- */
453
- const geocoding = {
454
- forward,
455
- reverse,
456
- byId,
457
- batch,
458
- language: LanguageGeocoding,
459
- };
460
-
461
- export { geocoding };
@@ -1,139 +0,0 @@
1
- import { BBox } from "geojson";
2
- import { callFetch } from "../callFetch";
3
- import { config } from "../config";
4
- import { defaults } from "../defaults";
5
- import { ServiceError } from "./ServiceError";
6
-
7
- const customMessages = {
8
- 403: "Key is missing, invalid or restricted",
9
- };
10
-
11
- /**
12
- * Options that can be provided to get user data.
13
- */
14
- export type GeolocationInfoOptions = {
15
- /**
16
- * Custom MapTiler Cloud API key to use instead of the one in global `config`
17
- */
18
- apiKey?: string;
19
- };
20
-
21
- export type GeolocationResult = {
22
- /**
23
- * Name of the country
24
- * Example: Switzerland
25
- */
26
- country?: string;
27
-
28
- /**
29
- * Two-letter code of the country ISO 3166-1 alpha-2 codes
30
- * Example: CH
31
- */
32
- country_code?: string;
33
-
34
- /**
35
- * Bounds of the country in WGS84 degrees [west, south, east, north].
36
- * Example: [5.95538,45.818852,10.490936,47.809357]
37
- */
38
- country_bounds?: BBox;
39
-
40
- /**
41
- * Official country languages in ISO 639-1 format. ISO 639-1 codes
42
- * Example: ["de","fr","it"]
43
- */
44
- country_languages?: Array<string>;
45
-
46
- /**
47
- * Name of the continent
48
- * Example: Europe
49
- */
50
- continent?: string;
51
-
52
- /**
53
- * Two-letter code of the continent
54
- * Example: EU
55
- */
56
- continent_code?: string;
57
-
58
- /**
59
- * Indicated whether the country is part of the European Union.
60
- */
61
- eu?: boolean;
62
-
63
- /**
64
- * Name of the city
65
- * Example: Zurich
66
- */
67
- city?: string;
68
-
69
- /**
70
- * Latitude of the location
71
- * Example: 47.36667
72
- */
73
- latitude?: number;
74
-
75
- /**
76
- * Longitude of the location
77
- * Example: 8.55
78
- */
79
- longitude?: number;
80
-
81
- /**
82
- * Postal code
83
- * Example: 8000
84
- */
85
- postal?: string;
86
-
87
- /**
88
- * If known, the ISO 3166-2 name for the first level region. ISO 3166-2 codes
89
- * Example: Zurich
90
- */
91
- region?: string;
92
-
93
- /**
94
- * If known, the ISO 3166-2 code for the first level region. ISO 3166-2 codes
95
- * Example: ZH
96
- */
97
- region_code?: string;
98
-
99
- /**
100
- * Name of the timezone
101
- * Example: Europe/Zurich
102
- */
103
- timezone?: string;
104
- };
105
-
106
- /**
107
- * Looks up geolocation details from IP address using MapTiler API.
108
- * Learn more on the MapTiler API reference page: https://docs.maptiler.com/cloud/api/geolocation/#ip-geolocation
109
- * @returns
110
- */
111
- async function info(
112
- options: GeolocationInfoOptions = {},
113
- ): Promise<GeolocationResult> {
114
- const endpoint = new URL(`geolocation/ip.json`, defaults.maptilerApiURL);
115
- endpoint.searchParams.set("key", options.apiKey ?? config.apiKey);
116
- const urlWithParams = endpoint.toString();
117
-
118
- const res = await callFetch(urlWithParams);
119
-
120
- if (!res.ok) {
121
- throw new ServiceError(
122
- res,
123
- res.status in customMessages ? customMessages[res.status] : "",
124
- );
125
- }
126
-
127
- const obj = await res.json();
128
- return obj as GeolocationResult;
129
- }
130
-
131
- /**
132
- * The **geolocation** namespace contains an asynchronous function to call the [MapTiler Geolocation API](https://docs.maptiler.com/cloud/api/geolocation/).
133
- * The **Geolocation API** provides a way to retrieve the IP address as well as geographic informations of a machine performing the query (most likely: a user)
134
- */
135
- const geolocation = {
136
- info,
137
- };
138
-
139
- export { geolocation };
@@ -1,87 +0,0 @@
1
- /**\
2
- * This code is borrowed from https://github.com/mourner/simplify-js and reworked a little.
3
- */
4
-
5
- import { Position } from "geojson";
6
-
7
- // square distance from a point to a segment
8
- function getSqSegDist(p: Position, p1: Position, p2: Position): number {
9
- let x = p1[0],
10
- y = p1[1],
11
- dx = p2[0] - x,
12
- dy = p2[1] - y;
13
-
14
- if (dx !== 0 || dy !== 0) {
15
- const t = ((p[0] - x) * dx + (p[1] - y) * dy) / (dx * dx + dy * dy);
16
-
17
- if (t > 1) {
18
- x = p2[0];
19
- y = p2[1];
20
- } else if (t > 0) {
21
- x += dx * t;
22
- y += dy * t;
23
- }
24
- }
25
-
26
- dx = p[0] - x;
27
- dy = p[1] - y;
28
-
29
- return dx * dx + dy * dy;
30
- }
31
-
32
- function simplifyDPStep(
33
- points: Array<Position>,
34
- first: number,
35
- last: number,
36
- sqTolerance: number,
37
- simplified: Array<Position>,
38
- ) {
39
- let maxSqDist = sqTolerance,
40
- index;
41
-
42
- for (let i = first + 1; i < last; i++) {
43
- const sqDist = getSqSegDist(points[i], points[first], points[last]);
44
-
45
- if (sqDist > maxSqDist) {
46
- index = i;
47
- maxSqDist = sqDist;
48
- }
49
- }
50
-
51
- if (maxSqDist > sqTolerance) {
52
- if (index - first > 1) {
53
- simplifyDPStep(points, first, index, sqTolerance, simplified);
54
- }
55
- simplified.push(points[index]);
56
-
57
- if (last - index > 1) {
58
- simplifyDPStep(points, index, last, sqTolerance, simplified);
59
- }
60
- }
61
- }
62
-
63
- // simplification using Ramer-Douglas-Peucker algorithm
64
- function simplifyDouglasPeucker(
65
- points: Array<Position>,
66
- sqTolerance: number,
67
- ): Array<Position> {
68
- const last = points.length - 1;
69
- const simplified = [points[0]];
70
- simplifyDPStep(points, 0, last, sqTolerance, simplified);
71
- simplified.push(points[last]);
72
- return simplified;
73
- }
74
-
75
- // both algorithms combined for awesome performance
76
- export default function simplify(
77
- points: Array<Position>,
78
- tolerance: number,
79
- ): Array<Position> {
80
- if (points.length <= 2) {
81
- return points;
82
- }
83
-
84
- const sqTolerance = tolerance !== undefined ? tolerance * tolerance : 1;
85
- const simplePoints = simplifyDouglasPeucker(points, sqTolerance);
86
- return simplePoints;
87
- }