@maptiler/client 1.1.3 → 1.4.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 (75) hide show
  1. package/dist/maptiler-client.cjs +113 -36
  2. package/dist/maptiler-client.cjs.map +1 -1
  3. package/dist/maptiler-client.d.ts +79 -28
  4. package/dist/maptiler-client.min.mjs +1 -1
  5. package/dist/maptiler-client.mjs +113 -36
  6. package/dist/maptiler-client.mjs.map +1 -1
  7. package/dist/maptiler-client.umd.js +113 -36
  8. package/dist/maptiler-client.umd.js.map +1 -1
  9. package/dist/maptiler-client.umd.min.js +1 -1
  10. package/docs/assets/search.js +1 -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 +4 -4
  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 +12 -6
  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 +6 -6
  36. package/docs/types/services_coordinates.CoordinatesTransformOptions.html +6 -6
  37. package/docs/types/services_coordinates.XYZ.html +5 -5
  38. package/docs/types/services_data.GetDataOptions.html +6 -6
  39. package/docs/types/services_geocoding.ByIdGeocodingOptions.html +63 -0
  40. package/docs/types/services_geocoding.CommonForwardAndReverseGeocodingOptions.html +63 -0
  41. package/docs/types/services_geocoding.Coordinates.html +9 -6
  42. package/docs/types/services_geocoding.FeatureHierarchy.html +9 -6
  43. package/docs/types/services_geocoding.GeocodingFeature.html +9 -6
  44. package/docs/types/services_geocoding.GeocodingOptions.html +10 -26
  45. package/docs/types/services_geocoding.GeocodingSearchResult.html +9 -6
  46. package/docs/types/services_geocoding.LanguageGeocodingOptions.html +70 -0
  47. package/docs/types/services_geocoding.ReverseGeocodingOptions.html +10 -18
  48. package/docs/types/services_geolocation.GeolocationInfoOptions.html +6 -6
  49. package/docs/types/services_geolocation.GeolocationResult.html +5 -5
  50. package/docs/types/services_staticMaps.AutomaticStaticMapOptions.html +5 -5
  51. package/docs/types/services_staticMaps.BoundedStaticMapOptions.html +5 -5
  52. package/docs/types/services_staticMaps.CenteredStaticMapOptions.html +5 -5
  53. package/docs/types/services_staticMaps.StaticMapBaseOptions.html +6 -6
  54. package/docs/types/services_staticMaps.StaticMapMarker.html +5 -5
  55. package/docs/variables/config.config.html +5 -5
  56. package/docs/variables/language.LanguageGeocoding.html +5 -5
  57. package/docs/variables/services_coordinates.coordinates.html +5 -5
  58. package/docs/variables/services_data.data.html +5 -5
  59. package/docs/variables/services_geocoding.geocoding.html +56 -12
  60. package/docs/variables/services_geolocation.geolocation.html +5 -5
  61. package/docs/variables/services_staticMaps.staticMaps.html +5 -5
  62. package/docsmd/README.md +82 -68
  63. package/docsmd/classes/ClientConfig.md +5 -5
  64. package/docsmd/classes/MapStyleVariant.md +13 -13
  65. package/docsmd/classes/ReferenceMapStyle.md +9 -9
  66. package/docsmd/classes/ServiceError.md +3 -3
  67. package/examples/test-browser-umd.html +6 -6
  68. package/package.json +3 -1
  69. package/src/index.ts +4 -0
  70. package/src/mapstyle.ts +46 -1
  71. package/src/services/coordinates.ts +2 -2
  72. package/src/services/data.ts +1 -1
  73. package/src/services/geocoding.ts +206 -65
  74. package/src/services/geolocation.ts +1 -1
  75. package/src/services/staticMaps.ts +1 -1
@@ -1,4 +1,4 @@
1
- [MapTiler Client - v1.1.3](../README.md) / ReferenceMapStyle
1
+ [MapTiler Client - v1.4.0](../README.md) / ReferenceMapStyle
2
2
 
3
3
  # Class: ReferenceMapStyle
4
4
 
@@ -35,7 +35,7 @@ An instance of reference style contains a list of StyleVariants ordered by relev
35
35
 
36
36
  #### Defined in
37
37
 
38
- [mapstyle.ts:180](https://github.com/maptiler/maptiler-client-js/blob/ba8c80a/src/mapstyle.ts#L180)
38
+ [mapstyle.ts:180](https://github.com/maptiler/maptiler-client-js/blob/8bd7bfc/src/mapstyle.ts#L180)
39
39
 
40
40
  ## Methods
41
41
 
@@ -57,7 +57,7 @@ Add a variant to _this_ reference style
57
57
 
58
58
  #### Defined in
59
59
 
60
- [mapstyle.ts:212](https://github.com/maptiler/maptiler-client-js/blob/ba8c80a/src/mapstyle.ts#L212)
60
+ [mapstyle.ts:212](https://github.com/maptiler/maptiler-client-js/blob/8bd7bfc/src/mapstyle.ts#L212)
61
61
 
62
62
  ___
63
63
 
@@ -73,7 +73,7 @@ Get the defualt variant for this reference style
73
73
 
74
74
  #### Defined in
75
75
 
76
- [mapstyle.ts:250](https://github.com/maptiler/maptiler-client-js/blob/ba8c80a/src/mapstyle.ts#L250)
76
+ [mapstyle.ts:250](https://github.com/maptiler/maptiler-client-js/blob/8bd7bfc/src/mapstyle.ts#L250)
77
77
 
78
78
  ___
79
79
 
@@ -89,7 +89,7 @@ Get the id of _this_ reference style
89
89
 
90
90
  #### Defined in
91
91
 
92
- [mapstyle.ts:204](https://github.com/maptiler/maptiler-client-js/blob/ba8c80a/src/mapstyle.ts#L204)
92
+ [mapstyle.ts:204](https://github.com/maptiler/maptiler-client-js/blob/8bd7bfc/src/mapstyle.ts#L204)
93
93
 
94
94
  ___
95
95
 
@@ -105,7 +105,7 @@ Get the human-friendly name of this reference style
105
105
 
106
106
  #### Defined in
107
107
 
108
- [mapstyle.ts:196](https://github.com/maptiler/maptiler-client-js/blob/ba8c80a/src/mapstyle.ts#L196)
108
+ [mapstyle.ts:196](https://github.com/maptiler/maptiler-client-js/blob/8bd7bfc/src/mapstyle.ts#L196)
109
109
 
110
110
  ___
111
111
 
@@ -128,7 +128,7 @@ then the most relevant default variant is returned instead
128
128
 
129
129
  #### Defined in
130
130
 
131
- [mapstyle.ts:232](https://github.com/maptiler/maptiler-client-js/blob/ba8c80a/src/mapstyle.ts#L232)
131
+ [mapstyle.ts:232](https://github.com/maptiler/maptiler-client-js/blob/8bd7bfc/src/mapstyle.ts#L232)
132
132
 
133
133
  ___
134
134
 
@@ -144,7 +144,7 @@ Get the list of variants for this reference style
144
144
 
145
145
  #### Defined in
146
146
 
147
- [mapstyle.ts:242](https://github.com/maptiler/maptiler-client-js/blob/ba8c80a/src/mapstyle.ts#L242)
147
+ [mapstyle.ts:242](https://github.com/maptiler/maptiler-client-js/blob/8bd7bfc/src/mapstyle.ts#L242)
148
148
 
149
149
  ___
150
150
 
@@ -166,4 +166,4 @@ Check if a given variant type exists for this reference style
166
166
 
167
167
  #### Defined in
168
168
 
169
- [mapstyle.ts:222](https://github.com/maptiler/maptiler-client-js/blob/ba8c80a/src/mapstyle.ts#L222)
169
+ [mapstyle.ts:222](https://github.com/maptiler/maptiler-client-js/blob/8bd7bfc/src/mapstyle.ts#L222)
@@ -1,4 +1,4 @@
1
- [MapTiler Client - v1.1.3](../README.md) / ServiceError
1
+ [MapTiler Client - v1.4.0](../README.md) / ServiceError
2
2
 
3
3
  # Class: ServiceError
4
4
 
@@ -39,7 +39,7 @@ Error.constructor
39
39
 
40
40
  #### Defined in
41
41
 
42
- [services/ServiceError.ts:5](https://github.com/maptiler/maptiler-client-js/blob/ba8c80a/src/services/ServiceError.ts#L5)
42
+ [services/ServiceError.ts:5](https://github.com/maptiler/maptiler-client-js/blob/8bd7bfc/src/services/ServiceError.ts#L5)
43
43
 
44
44
  ## Properties
45
45
 
@@ -49,4 +49,4 @@ Error.constructor
49
49
 
50
50
  #### Defined in
51
51
 
52
- [services/ServiceError.ts:5](https://github.com/maptiler/maptiler-client-js/blob/ba8c80a/src/services/ServiceError.ts#L5)
52
+ [services/ServiceError.ts:5](https://github.com/maptiler/maptiler-client-js/blob/8bd7bfc/src/services/ServiceError.ts#L5)
@@ -58,7 +58,7 @@
58
58
  height: 500,
59
59
  style: 'winter',
60
60
  markers: [[7, 46, 'green'], [8, 47, '#982']],
61
- apiKey: "YOUR_PRO_API_KEY",
61
+ // apiKey: "YOUR_PRO_API_KEY",
62
62
  });
63
63
 
64
64
  addImage(imageLinkCentered);
@@ -71,7 +71,7 @@
71
71
  path: [[-9.8905, 36.6274], [-9.8905, 42.3208], [-6.0453, 42.3208], [-6.0453, 36.6274], [-9.8905, 36.6274]],
72
72
  pathStrokeColor: 'red',
73
73
  pathWidth: 4,
74
- apiKey: "YOUR_PRO_API_KEY",
74
+ // apiKey: "YOUR_PRO_API_KEY",
75
75
  });
76
76
 
77
77
  addImage(imageLinkBounded);
@@ -79,10 +79,10 @@
79
79
 
80
80
 
81
81
  (async () => {
82
- await testGeocoding();
83
- await testGeolocation();
84
- await testCoordinates();
85
- await testData();
82
+ // await testGeocoding();
83
+ // await testGeolocation();
84
+ // await testCoordinates();
85
+ // await testData();
86
86
  staticMapTest();
87
87
  })()
88
88
  </script>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@maptiler/client",
3
- "version": "1.1.3",
3
+ "version": "1.4.0",
4
4
  "description": "Javascript & Typescript wrapper to MapTiler Cloud API",
5
5
  "module": "dist/maptiler-client.mjs",
6
6
  "types": "dist/maptiler-client.d.ts",
@@ -17,7 +17,9 @@
17
17
  },
18
18
  "keywords": [
19
19
  "geocoding",
20
+ "forward geocoding",
20
21
  "reverse geocoding",
22
+ "batch geocoding",
21
23
  "coordinates",
22
24
  "CRS",
23
25
  "geolocation",
package/src/index.ts CHANGED
@@ -8,6 +8,8 @@ import { geocoding } from "./services/geocoding";
8
8
  import type {
9
9
  GeocodingOptions,
10
10
  ReverseGeocodingOptions,
11
+ LanguageGeocodingOptions,
12
+ CommonForwardAndReverseGeocodingOptions,
11
13
  GeocodingSearchResult,
12
14
  GeocodingFeature,
13
15
  FeatureHierarchy,
@@ -60,6 +62,8 @@ export type {
60
62
  BBox,
61
63
  GeocodingOptions,
62
64
  ReverseGeocodingOptions,
65
+ LanguageGeocodingOptions,
66
+ CommonForwardAndReverseGeocodingOptions,
63
67
  GeocodingSearchResult,
64
68
  GeocodingFeature,
65
69
  CoordinateExport,
package/src/mapstyle.ts CHANGED
@@ -272,6 +272,10 @@ export type MapStyleType = {
272
272
  * Suitable for navigation, with high level of detail on urban areas, plenty of POIs and 3D buildings, in light mode.
273
273
  */
274
274
  LIGHT: MapStyleVariant;
275
+ /**
276
+ * Suitable for navigation, with high level of detail on urban areas, plenty of POIs and 3D buildings, in blue night mode.
277
+ */
278
+ NIGHT: MapStyleVariant;
275
279
  /**
276
280
  * Suitable for navigation, with high level of detail on urban areas, plenty of POIs and 3D buildings, with a pastel color palette.
277
281
  */
@@ -286,6 +290,11 @@ export type MapStyleType = {
286
290
  * Suitable for outdoor activities. With elevation isolines and hillshading.
287
291
  */
288
292
  DEFAULT: MapStyleVariant;
293
+
294
+ /**
295
+ * Suitable for outdoor activities. With elevation isolines and hillshading, in dark mode.
296
+ */
297
+ DARK: MapStyleVariant;
289
298
  };
290
299
 
291
300
  /**
@@ -296,6 +305,10 @@ export type MapStyleType = {
296
305
  * Suitabe for winter outdoor activities. With ski tracks, elevation isolines and hillshading.
297
306
  */
298
307
  DEFAULT: MapStyleVariant;
308
+ /**
309
+ * Suitabe for winter outdoor activities. With ski tracks, elevation isolines and hillshading, in dark mode.
310
+ */
311
+ DARK: MapStyleVariant;
299
312
  };
300
313
 
301
314
  /**
@@ -373,6 +386,10 @@ export type MapStyleType = {
373
386
  * A nice high-contrast, yet less saturated alternative to the `outdoor` style, with hillshading, 3D buildings and fairly high street details
374
387
  */
375
388
  DEFAULT: MapStyleVariant;
389
+ /**
390
+ * A nice high-contrast, yet less saturated alternative to the `outdoor` style, with hillshading, 3D buildings and fairly high street details, in dark mode
391
+ */
392
+ DARK: MapStyleVariant;
376
393
  /**
377
394
  * A nice high-contrast, and high saturation alternative to the `outdoor` style, with hillshading, 3D buildings and fairly high street details
378
395
  */
@@ -490,6 +507,13 @@ export const mapStylePresetList: Array<MapStylePreset> = [
490
507
  description: "",
491
508
  imageURL: "",
492
509
  },
510
+ {
511
+ id: "streets-v2-night",
512
+ name: "Night",
513
+ variantType: "NIGHT",
514
+ description: "",
515
+ imageURL: "",
516
+ },
493
517
  {
494
518
  id: "streets-v2-pastel",
495
519
  name: "Pastel",
@@ -512,6 +536,13 @@ export const mapStylePresetList: Array<MapStylePreset> = [
512
536
  description: "",
513
537
  imageURL: "",
514
538
  },
539
+ {
540
+ id: "outdoor-v2-dark",
541
+ name: "Dark",
542
+ variantType: "DARK",
543
+ description: "",
544
+ imageURL: "",
545
+ },
515
546
  ],
516
547
  },
517
548
 
@@ -522,11 +553,18 @@ export const mapStylePresetList: Array<MapStylePreset> = [
522
553
  variants: [
523
554
  {
524
555
  id: "winter-v2",
525
- name: "Winter",
556
+ name: "Default",
526
557
  variantType: "DEFAULT",
527
558
  description: "",
528
559
  imageURL: "",
529
560
  },
561
+ {
562
+ id: "winter-v2-dark",
563
+ name: "Dark",
564
+ variantType: "DARK",
565
+ description: "",
566
+ imageURL: "",
567
+ },
530
568
  ],
531
569
  },
532
570
 
@@ -652,6 +690,13 @@ export const mapStylePresetList: Array<MapStylePreset> = [
652
690
  description: "",
653
691
  imageURL: "",
654
692
  },
693
+ {
694
+ id: "topo-v2-dark",
695
+ name: "Dark",
696
+ variantType: "DARK",
697
+ description: "",
698
+ imageURL: "",
699
+ },
655
700
  {
656
701
  id: "topo-v2-shiny",
657
702
  name: "Shiny",
@@ -10,7 +10,7 @@ const customMessages = {
10
10
 
11
11
  export type CoordinatesSearchOptions = {
12
12
  /**
13
- * Custom mapTiler Cloud API key to use instead of the one in global `config`
13
+ * Custom MapTiler Cloud API key to use instead of the one in global `config`
14
14
  */
15
15
  apiKey?: string;
16
16
 
@@ -173,7 +173,7 @@ export type CoordinateTransformResult = {
173
173
  */
174
174
  export type CoordinatesTransformOptions = {
175
175
  /**
176
- * Custom mapTiler Cloud API key to use instead of the one in global `config`
176
+ * Custom MapTiler Cloud API key to use instead of the one in global `config`
177
177
  */
178
178
  apiKey?: string;
179
179
 
@@ -13,7 +13,7 @@ const customMessages = {
13
13
  */
14
14
  export type GetDataOptions = {
15
15
  /**
16
- * Custom mapTiler Cloud API key to use instead of the one in global `config`
16
+ * Custom MapTiler Cloud API key to use instead of the one in global `config`
17
17
  */
18
18
  apiKey?: string;
19
19
  };
@@ -15,12 +15,46 @@ const customMessages = {
15
15
  403: "Key is missing, invalid or restricted",
16
16
  };
17
17
 
18
- export type GeocodingOptions = {
18
+ export type LanguageGeocodingOptions = {
19
19
  /**
20
- * Custom mapTiler Cloud API key to use instead of the one in global `config`
20
+ * Prefer results in specific language. It’s possible to specify multiple values.
21
21
  */
22
- apiKey?: string;
22
+ language?: LanguageGeocodingString | Array<LanguageGeocodingString>;
23
+ };
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
+ )[];
55
+ };
56
+
57
+ export type GeocodingOptions = CommonForwardAndReverseGeocodingOptions & {
24
58
  /**
25
59
  * Only search for results in the specified area.
26
60
  */
@@ -32,11 +66,26 @@ export type GeocodingOptions = {
32
66
  proximity?: Position;
33
67
 
34
68
  /**
35
- * Prefer results in specific language. It’s possible to specify multiple values.
69
+ * Limit search to specific country/countries specified as list of Alpha-2 ISO 3166-1 codes.
36
70
  */
37
- language?: LanguageGeocodingString | Array<LanguageGeocodingString>;
71
+ country?: string[];
72
+
73
+ /**
74
+ * Set to `false` to disable fuzzy (typo-tolerant) search. Default is `true`.
75
+ */
76
+ fuzzyMatch?: boolean;
77
+
78
+ /**
79
+ * Set to `true` to use autocomplete, `false` to disable it.
80
+ * Default (`undefined`) is to combine autocomplete with non-autocomplete results.
81
+ */
82
+ autocomplete?: boolean;
38
83
  };
39
84
 
85
+ export type ReverseGeocodingOptions = CommonForwardAndReverseGeocodingOptions;
86
+
87
+ export type ByIdGeocodingOptions = LanguageGeocodingOptions;
88
+
40
89
  export type Coordinates = Position;
41
90
 
42
91
  export type FeatureHierarchy = {
@@ -102,6 +151,72 @@ export type GeocodingSearchResult = {
102
151
  attribution: string;
103
152
  };
104
153
 
154
+ function addLanguageGeocodingOptions(
155
+ searchParams: URLSearchParams,
156
+ options: LanguageGeocodingOptions
157
+ ) {
158
+ if (options.language == undefined) {
159
+ return;
160
+ }
161
+
162
+ const languages = Array.from(
163
+ new Set(
164
+ (Array.isArray(options.language)
165
+ ? options.language
166
+ : [options.language]
167
+ ).map((lang) =>
168
+ lang === LanguageGeocoding.AUTO ? getAutoLanguageGeocoding() : lang
169
+ )
170
+ )
171
+ ).join(",");
172
+
173
+ searchParams.set("language", languages);
174
+ }
175
+
176
+ function addCommonForwardAndReverseGeocodingOptions(
177
+ searchParams: URLSearchParams,
178
+ options: CommonForwardAndReverseGeocodingOptions
179
+ ) {
180
+ searchParams.set("key", options.apiKey ?? config.apiKey);
181
+
182
+ if (options.limit != undefined) {
183
+ searchParams.set("limit", String(options.limit));
184
+ }
185
+
186
+ if (options.types != undefined) {
187
+ searchParams.set("types", options.types.join(","));
188
+ }
189
+
190
+ addLanguageGeocodingOptions(searchParams, options);
191
+ }
192
+
193
+ function addForwardGeocodingOptions(
194
+ searchParams: URLSearchParams,
195
+ options: GeocodingOptions
196
+ ) {
197
+ addCommonForwardAndReverseGeocodingOptions(searchParams, options);
198
+
199
+ if (options.bbox != undefined) {
200
+ searchParams.set("bbox", options.bbox.join(","));
201
+ }
202
+
203
+ if (options.proximity != undefined) {
204
+ searchParams.set("proximity", options.proximity.join(","));
205
+ }
206
+
207
+ if (options.country != undefined) {
208
+ searchParams.set("country", options.country.join(","));
209
+ }
210
+
211
+ if (options.fuzzyMatch != undefined) {
212
+ searchParams.set("fuzzyMatch", options.fuzzyMatch ? "true" : "false");
213
+ }
214
+
215
+ if (options.autocomplete != undefined) {
216
+ searchParams.set("autocomplete", options.autocomplete ? "true" : "false");
217
+ }
218
+ }
219
+
105
220
  /**
106
221
  * Performs a forward geocoding query to MapTiler API.
107
222
  * Providing a human readable place name (of a city, country, street, etc.), the function returns
@@ -123,60 +238,27 @@ async function forward(
123
238
  `geocoding/${encodeURIComponent(query)}.json`,
124
239
  defaults.maptilerApiURL
125
240
  );
126
- endpoint.searchParams.set("key", options.apiKey ?? config.apiKey);
127
241
 
128
- if ("bbox" in options) {
129
- endpoint.searchParams.set("bbox", options.bbox.join(","));
130
- }
131
-
132
- if ("proximity" in options) {
133
- endpoint.searchParams.set("proximity", options.proximity.join(","));
134
- }
242
+ const { searchParams } = endpoint;
135
243
 
136
- if ("language" in options) {
137
- const languages = Array.from(
138
- new Set(
139
- (Array.isArray(options.language)
140
- ? options.language
141
- : [options.language]
142
- ).map((lang) =>
143
- lang === LanguageGeocoding.AUTO ? getAutoLanguageGeocoding() : lang
144
- )
145
- )
146
- ).join(",");
147
-
148
- endpoint.searchParams.set("language", languages);
149
- }
244
+ addForwardGeocodingOptions(searchParams, options);
150
245
 
151
246
  const urlWithParams = endpoint.toString();
247
+
152
248
  const res = await callFetch(urlWithParams);
153
249
 
154
250
  if (!res.ok) {
155
- throw new ServiceError(
156
- res,
157
- res.status in customMessages ? customMessages[res.status] : ""
158
- );
251
+ throw new ServiceError(res, customMessages[res.status] ?? "");
159
252
  }
160
253
 
161
- const obj = await res.json();
162
- return obj as GeocodingSearchResult;
163
- }
164
-
165
- export type ReverseGeocodingOptions = {
166
- /**
167
- * Custom mapTiler Cloud API key to use instead of the one in global `config`
168
- */
169
- apiKey?: string;
254
+ const obj: GeocodingSearchResult = await res.json();
170
255
 
171
- /**
172
- * Prefer results in specific language. It’s possible to specify multiple values.
173
- */
174
- language?: LanguageGeocodingString | Array<LanguageGeocodingString>;
175
- };
256
+ return obj;
257
+ }
176
258
 
177
259
  /**
178
260
  * Perform a reverse geocoding query to MapTiler API.
179
- * Providing a longitude and latitude, this function returns a set of human readable information abou this place (country, city, street, etc.)
261
+ * Providing a longitude and latitude, this function returns a set of human readable information about this place (country, city, street, etc.)
180
262
  * Learn more on the MapTiler API reference page: https://docs.maptiler.com/cloud/api/geocoding/#search-by-coordinates-reverse
181
263
  * @param position
182
264
  * @param options
@@ -194,35 +276,92 @@ async function reverse(
194
276
  `geocoding/${position[0]},${position[1]}.json`,
195
277
  defaults.maptilerApiURL
196
278
  );
197
- endpoint.searchParams.set("key", options.apiKey ?? config.apiKey);
198
-
199
- if ("language" in options) {
200
- const languages = Array.from(
201
- new Set(
202
- (Array.isArray(options.language)
203
- ? options.language
204
- : [options.language]
205
- ).map((lang) =>
206
- lang === LanguageGeocoding.AUTO ? getAutoLanguageGeocoding() : lang
207
- )
208
- )
209
- ).join(",");
210
279
 
211
- endpoint.searchParams.set("language", languages);
280
+ addCommonForwardAndReverseGeocodingOptions(endpoint.searchParams, options);
281
+
282
+ const urlWithParams = endpoint.toString();
283
+
284
+ const res = await callFetch(urlWithParams);
285
+
286
+ if (!res.ok) {
287
+ throw new ServiceError(res, customMessages[res.status] ?? "");
212
288
  }
213
289
 
290
+ const obj: GeocodingSearchResult = await res.json();
291
+
292
+ return obj;
293
+ }
294
+
295
+ /**
296
+ * Perform a geocoding query to MapTiler API to obtain fature by its ID.
297
+ * Providing a feature ID, this function returns a feature which includes its full geometry.
298
+ * Note that the feature ID is not stable and it changes when the database is re-indexed.
299
+ * Learn more on the MapTiler API reference page: https://docs.maptiler.com/cloud/api/geocoding/#search-by-feature-id
300
+ * @param id
301
+ * @param options
302
+ * @returns
303
+ */
304
+ async function byId(
305
+ id: string,
306
+ options: ByIdGeocodingOptions = {}
307
+ ): Promise<GeocodingSearchResult> {
308
+ const endpoint = new URL(`geocoding/${id}.json`, defaults.maptilerApiURL);
309
+
310
+ addLanguageGeocodingOptions(endpoint.searchParams, options);
311
+
214
312
  const urlWithParams = endpoint.toString();
313
+
215
314
  const res = await callFetch(urlWithParams);
216
315
 
217
316
  if (!res.ok) {
218
- throw new ServiceError(
219
- res,
220
- res.status in customMessages ? customMessages[res.status] : ""
221
- );
317
+ throw new ServiceError(res, customMessages[res.status] ?? "");
318
+ }
319
+
320
+ const obj: GeocodingSearchResult = await res.json();
321
+
322
+ return obj;
323
+ }
324
+
325
+ /**
326
+ * Perform a batch geocoding query to MapTiler API.
327
+ * Provide multiple queries in the array. Each query can be forward, reverse or by feature ID.
328
+ * Learn more on the MapTiler API reference page: https://docs.maptiler.com/cloud/api/geocoding/#batch-geocoding
329
+ * @param queries
330
+ * @param options
331
+ * @returns
332
+ */
333
+ async function batch(
334
+ queries: string[],
335
+ options: GeocodingOptions = {}
336
+ ): Promise<GeocodingSearchResult[]> {
337
+ if (!queries.length) {
338
+ return [];
339
+ }
340
+
341
+ const joinedQuery = queries
342
+ .map((query) => encodeURIComponent(query))
343
+ .join(";");
344
+
345
+ const endpoint = new URL(
346
+ `geocoding/${joinedQuery}.json`,
347
+ defaults.maptilerApiURL
348
+ );
349
+
350
+ const { searchParams } = endpoint;
351
+
352
+ addForwardGeocodingOptions(searchParams, options);
353
+
354
+ const urlWithParams = endpoint.toString();
355
+
356
+ const res = await callFetch(urlWithParams);
357
+
358
+ if (!res.ok) {
359
+ throw new ServiceError(res, customMessages[res.status] ?? "");
222
360
  }
223
361
 
224
362
  const obj = await res.json();
225
- return obj as GeocodingSearchResult;
363
+
364
+ return queries.length === 1 ? [obj] : obj;
226
365
  }
227
366
 
228
367
  /**
@@ -233,6 +372,8 @@ async function reverse(
233
372
  const geocoding = {
234
373
  forward,
235
374
  reverse,
375
+ byId,
376
+ batch,
236
377
  language: LanguageGeocoding,
237
378
  };
238
379
 
@@ -13,7 +13,7 @@ const customMessages = {
13
13
  */
14
14
  export type GeolocationInfoOptions = {
15
15
  /**
16
- * Custom mapTiler Cloud API key to use instead of the one in global `config`
16
+ * Custom MapTiler Cloud API key to use instead of the one in global `config`
17
17
  */
18
18
  apiKey?: string;
19
19
  };
@@ -9,7 +9,7 @@ import simplify from "./simplify";
9
9
  */
10
10
  export type StaticMapBaseOptions = {
11
11
  /**
12
- * Custom mapTiler Cloud API key to use instead of the one in global `config`
12
+ * Custom MapTiler Cloud API key to use instead of the one in global `config`
13
13
  */
14
14
  apiKey?: string;
15
15