@maptiler/client 1.1.2 → 1.3.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 (76) hide show
  1. package/dist/maptiler-client.cjs +89 -38
  2. package/dist/maptiler-client.cjs.map +1 -1
  3. package/dist/maptiler-client.d.ts +70 -29
  4. package/dist/maptiler-client.min.mjs +1 -1
  5. package/dist/maptiler-client.mjs +89 -38
  6. package/dist/maptiler-client.mjs.map +1 -1
  7. package/dist/maptiler-client.umd.js +89 -38
  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 +7 -7
  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 +36 -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 -69
  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 +8 -8
  68. package/package.json +1 -1
  69. package/readme.md +3 -3
  70. package/src/index.ts +4 -0
  71. package/src/mapstyle.ts +52 -7
  72. package/src/services/coordinates.ts +2 -2
  73. package/src/services/data.ts +1 -1
  74. package/src/services/geocoding.ts +152 -61
  75. package/src/services/geolocation.ts +1 -1
  76. package/src/services/staticMaps.ts +1 -1
@@ -1,4 +1,4 @@
1
- [MapTiler Client - v1.1.2](../README.md) / ReferenceMapStyle
1
+ [MapTiler Client - v1.3.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/ec0b213/src/mapstyle.ts#L180)
38
+ [mapstyle.ts:180](https://github.com/maptiler/maptiler-client-js/blob/46295fc/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/ec0b213/src/mapstyle.ts#L212)
60
+ [mapstyle.ts:212](https://github.com/maptiler/maptiler-client-js/blob/46295fc/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/ec0b213/src/mapstyle.ts#L250)
76
+ [mapstyle.ts:250](https://github.com/maptiler/maptiler-client-js/blob/46295fc/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/ec0b213/src/mapstyle.ts#L204)
92
+ [mapstyle.ts:204](https://github.com/maptiler/maptiler-client-js/blob/46295fc/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/ec0b213/src/mapstyle.ts#L196)
108
+ [mapstyle.ts:196](https://github.com/maptiler/maptiler-client-js/blob/46295fc/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/ec0b213/src/mapstyle.ts#L232)
131
+ [mapstyle.ts:232](https://github.com/maptiler/maptiler-client-js/blob/46295fc/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/ec0b213/src/mapstyle.ts#L242)
147
+ [mapstyle.ts:242](https://github.com/maptiler/maptiler-client-js/blob/46295fc/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/ec0b213/src/mapstyle.ts#L222)
169
+ [mapstyle.ts:222](https://github.com/maptiler/maptiler-client-js/blob/46295fc/src/mapstyle.ts#L222)
@@ -1,4 +1,4 @@
1
- [MapTiler Client - v1.1.2](../README.md) / ServiceError
1
+ [MapTiler Client - v1.3.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/ec0b213/src/services/ServiceError.ts#L5)
42
+ [services/ServiceError.ts:5](https://github.com/maptiler/maptiler-client-js/blob/46295fc/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/ec0b213/src/services/ServiceError.ts#L5)
52
+ [services/ServiceError.ts:5](https://github.com/maptiler/maptiler-client-js/blob/46295fc/src/services/ServiceError.ts#L5)
@@ -5,7 +5,7 @@
5
5
 
6
6
  <body>
7
7
  <p>
8
- This demo is using the UMD bundle.
8
+ This demo is using the UMD bundle. Add <code>?key=YOUR_API_KEY</code> to the URL.
9
9
  </p>
10
10
  <p>
11
11
  Open JS console.
@@ -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);
@@ -67,11 +67,11 @@
67
67
  hiDPI: true,
68
68
  width: 1024,
69
69
  height: 2048,
70
- style: maptilerClient.MapStyle.STAGE.DARK,
70
+ style: maptilerClient.MapStyle.DATAVIZ.DARK,
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.2",
3
+ "version": "1.3.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",
package/readme.md CHANGED
@@ -205,9 +205,9 @@ In the following static map functions, the `option` object features a `style` pr
205
205
  - `MapStyle.TONER.LITE` (variant)
206
206
  - `MapStyle.TONER.LINES` (variant)
207
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)
208
+ - `MapStyle.DATAVIZ`, the perfect style for data visualization, with very little noise
209
+ - `MapStyle.DATAVIZ.DARK` (variant)
210
+ - `MapStyle.DATAVIZ.LIGHT` (variant)
211
211
 
212
212
  ### Centered static maps
213
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).
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
  */
@@ -435,7 +452,7 @@ export type MapStyleType = {
435
452
  /**
436
453
  * Minimalist style, perfect for data visualization
437
454
  */
438
- STAGE: ReferenceMapStyle & {
455
+ DATAVIZ: ReferenceMapStyle & {
439
456
  /**
440
457
  * Minimalist style, perfect for data visualization
441
458
  */
@@ -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",
@@ -749,26 +794,26 @@ export const mapStylePresetList: Array<MapStylePreset> = [
749
794
  },
750
795
 
751
796
  {
752
- referenceStyleID: "STAGE",
753
- name: "Stage",
797
+ referenceStyleID: "DATAVIZ",
798
+ name: "Dataviz",
754
799
  description: "",
755
800
  variants: [
756
801
  {
757
- id: "stage",
802
+ id: "dataviz",
758
803
  name: "Default",
759
804
  variantType: "DEFAULT",
760
805
  description: "",
761
806
  imageURL: "",
762
807
  },
763
808
  {
764
- id: "stage-dark",
809
+ id: "dataviz-dark",
765
810
  name: "Dark",
766
811
  variantType: "DARK",
767
812
  description: "",
768
813
  imageURL: "",
769
814
  },
770
815
  {
771
- id: "stage-light",
816
+ id: "dataviz-light",
772
817
  name: "Light",
773
818
  variantType: "LIGHT",
774
819
  description: "",
@@ -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,45 @@ 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
+
105
193
  /**
106
194
  * Performs a forward geocoding query to MapTiler API.
107
195
  * Providing a human readable place name (of a city, country, street, etc.), the function returns
@@ -123,60 +211,47 @@ async function forward(
123
211
  `geocoding/${encodeURIComponent(query)}.json`,
124
212
  defaults.maptilerApiURL
125
213
  );
126
- endpoint.searchParams.set("key", options.apiKey ?? config.apiKey);
127
214
 
128
- if ("bbox" in options) {
129
- endpoint.searchParams.set("bbox", options.bbox.join(","));
215
+ const { searchParams } = endpoint;
216
+
217
+ addCommonForwardAndReverseGeocodingOptions(searchParams, options);
218
+
219
+ if (options.bbox != undefined) {
220
+ searchParams.set("bbox", options.bbox.join(","));
130
221
  }
131
222
 
132
- if ("proximity" in options) {
133
- endpoint.searchParams.set("proximity", options.proximity.join(","));
223
+ if (options.proximity != undefined) {
224
+ searchParams.set("proximity", options.proximity.join(","));
134
225
  }
135
226
 
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(",");
227
+ if (options.country != undefined) {
228
+ searchParams.set("country", options.country.join(","));
229
+ }
230
+
231
+ if (options.fuzzyMatch != undefined) {
232
+ searchParams.set("fuzzyMatch", options.fuzzyMatch ? "true" : "false");
233
+ }
147
234
 
148
- endpoint.searchParams.set("language", languages);
235
+ if (options.autocomplete != undefined) {
236
+ searchParams.set("autocomplete", options.autocomplete ? "true" : "false");
149
237
  }
150
238
 
151
239
  const urlWithParams = endpoint.toString();
240
+
152
241
  const res = await callFetch(urlWithParams);
153
242
 
154
243
  if (!res.ok) {
155
- throw new ServiceError(
156
- res,
157
- res.status in customMessages ? customMessages[res.status] : ""
158
- );
244
+ throw new ServiceError(res, customMessages[res.status] ?? "");
159
245
  }
160
246
 
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;
247
+ const obj: GeocodingSearchResult = await res.json();
170
248
 
171
- /**
172
- * Prefer results in specific language. It’s possible to specify multiple values.
173
- */
174
- language?: LanguageGeocodingString | Array<LanguageGeocodingString>;
175
- };
249
+ return obj;
250
+ }
176
251
 
177
252
  /**
178
253
  * 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.)
254
+ * Providing a longitude and latitude, this function returns a set of human readable information about this place (country, city, street, etc.)
180
255
  * Learn more on the MapTiler API reference page: https://docs.maptiler.com/cloud/api/geocoding/#search-by-coordinates-reverse
181
256
  * @param position
182
257
  * @param options
@@ -194,35 +269,50 @@ async function reverse(
194
269
  `geocoding/${position[0]},${position[1]}.json`,
195
270
  defaults.maptilerApiURL
196
271
  );
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
272
 
211
- endpoint.searchParams.set("language", languages);
273
+ addCommonForwardAndReverseGeocodingOptions(endpoint.searchParams, options);
274
+
275
+ const urlWithParams = endpoint.toString();
276
+
277
+ const res = await callFetch(urlWithParams);
278
+
279
+ if (!res.ok) {
280
+ throw new ServiceError(res, customMessages[res.status] ?? "");
212
281
  }
213
282
 
283
+ const obj: GeocodingSearchResult = await res.json();
284
+
285
+ return obj;
286
+ }
287
+
288
+ /**
289
+ * Perform a geocoding query to MapTiler API to obtain fature by its ID.
290
+ * Providing a feature ID, this function returns a feature which includes its full geometry.
291
+ * Note that the feature ID is not stable and it changes when the database is re-indexed.
292
+ * Learn more on the MapTiler API reference page: https://docs.maptiler.com/cloud/api/geocoding/#search-by-feature-id
293
+ * @param id
294
+ * @param options
295
+ * @returns
296
+ */
297
+ async function byId(
298
+ id: string,
299
+ options: ByIdGeocodingOptions = {}
300
+ ): Promise<GeocodingSearchResult> {
301
+ const endpoint = new URL(`geocoding/${id}.json`, defaults.maptilerApiURL);
302
+
303
+ addLanguageGeocodingOptions(endpoint.searchParams, options);
304
+
214
305
  const urlWithParams = endpoint.toString();
306
+
215
307
  const res = await callFetch(urlWithParams);
216
308
 
217
309
  if (!res.ok) {
218
- throw new ServiceError(
219
- res,
220
- res.status in customMessages ? customMessages[res.status] : ""
221
- );
310
+ throw new ServiceError(res, customMessages[res.status] ?? "");
222
311
  }
223
312
 
224
- const obj = await res.json();
225
- return obj as GeocodingSearchResult;
313
+ const obj: GeocodingSearchResult = await res.json();
314
+
315
+ return obj;
226
316
  }
227
317
 
228
318
  /**
@@ -233,6 +323,7 @@ async function reverse(
233
323
  const geocoding = {
234
324
  forward,
235
325
  reverse,
326
+ byId,
236
327
  language: LanguageGeocoding,
237
328
  };
238
329
 
@@ -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