@maptiler/client 1.0.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 (107) hide show
  1. package/.eslintrc.cjs +6 -0
  2. package/LICENSE +29 -0
  3. package/dist/maptiler-client.cjs +692 -0
  4. package/dist/maptiler-client.cjs.map +1 -0
  5. package/dist/maptiler-client.d.ts +702 -0
  6. package/dist/maptiler-client.min.mjs +1 -0
  7. package/dist/maptiler-client.mjs +680 -0
  8. package/dist/maptiler-client.mjs.map +1 -0
  9. package/dist/maptiler-client.umd.js +698 -0
  10. package/dist/maptiler-client.umd.js.map +1 -0
  11. package/dist/maptiler-client.umd.min.js +1 -0
  12. package/docs/.nojekyll +1 -0
  13. package/docs/assets/highlight.css +85 -0
  14. package/docs/assets/main.js +54 -0
  15. package/docs/assets/search.js +1 -0
  16. package/docs/assets/style.css +1257 -0
  17. package/docs/classes/ClientConfig.html +122 -0
  18. package/docs/classes/ServiceError.html +93 -0
  19. package/docs/images/JS-logo.svg +4 -0
  20. package/docs/images/TS-logo.svg +6 -0
  21. package/docs/images/maptiler-client-logo.afdesign +0 -0
  22. package/docs/images/maptiler-client-logo.svg +75 -0
  23. package/docs/images/maptiler-logo.svg +23 -0
  24. package/docs/images/screenshots/static-bounded-europe-1024.png +0 -0
  25. package/docs/images/screenshots/static-bounded-europe-2048.png +0 -0
  26. package/docs/images/screenshots/static-bounded-portugal-1024x2048.png +0 -0
  27. package/docs/images/screenshots/static-bounded-portugal-2048x2048.png +0 -0
  28. package/docs/images/screenshots/static-with-path.png +0 -0
  29. package/docs/index.html +280 -0
  30. package/docs/modules.html +119 -0
  31. package/docs/types/AutomaticStaticMapOptions.html +80 -0
  32. package/docs/types/BoundedStaticMapOptions.html +80 -0
  33. package/docs/types/CenteredStaticMapOptions.html +80 -0
  34. package/docs/types/CoordinateExport.html +85 -0
  35. package/docs/types/CoordinateGrid.html +83 -0
  36. package/docs/types/CoordinateId.html +85 -0
  37. package/docs/types/CoordinateSearch.html +107 -0
  38. package/docs/types/CoordinateSearchResult.html +89 -0
  39. package/docs/types/CoordinateTransformResult.html +90 -0
  40. package/docs/types/CoordinateTransformation.html +103 -0
  41. package/docs/types/Coordinates.html +78 -0
  42. package/docs/types/CoordinatesSearchOptions.html +97 -0
  43. package/docs/types/CoordinatesTransformOptions.html +99 -0
  44. package/docs/types/FeatureHierarchy.html +89 -0
  45. package/docs/types/FetchFunction.html +93 -0
  46. package/docs/types/GeocodingFeature.html +78 -0
  47. package/docs/types/GeocodingOptions.html +97 -0
  48. package/docs/types/GeocodingSearchResult.html +95 -0
  49. package/docs/types/GeolocationInfoOptions.html +87 -0
  50. package/docs/types/GeolocationResult.html +150 -0
  51. package/docs/types/GetDataOptions.html +87 -0
  52. package/docs/types/LanguageGeocodingString.html +80 -0
  53. package/docs/types/ReverseGeocodingOptions.html +89 -0
  54. package/docs/types/StaticMapBaseOptions.html +176 -0
  55. package/docs/types/StaticMapMarker.html +80 -0
  56. package/docs/types/XYZ.html +87 -0
  57. package/docs/variables/LanguageGeocoding.html +193 -0
  58. package/docs/variables/config.html +80 -0
  59. package/docs/variables/coordinates-1.html +124 -0
  60. package/docs/variables/data.html +103 -0
  61. package/docs/variables/geocoding.html +239 -0
  62. package/docs/variables/geolocation.html +101 -0
  63. package/docs/variables/staticMaps.html +147 -0
  64. package/docsmd/.nojekyll +1 -0
  65. package/docsmd/README.md +756 -0
  66. package/docsmd/classes/ClientConfig.md +90 -0
  67. package/docsmd/classes/ServiceError.md +52 -0
  68. package/docsmd/images/JS-logo.svg +4 -0
  69. package/docsmd/images/TS-logo.svg +6 -0
  70. package/docsmd/images/maptiler-client-logo.afdesign +0 -0
  71. package/docsmd/images/maptiler-client-logo.svg +75 -0
  72. package/docsmd/images/maptiler-logo.svg +23 -0
  73. package/docsmd/images/screenshots/static-bounded-europe-1024.png +0 -0
  74. package/docsmd/images/screenshots/static-bounded-europe-2048.png +0 -0
  75. package/docsmd/images/screenshots/static-bounded-portugal-1024x2048.png +0 -0
  76. package/docsmd/images/screenshots/static-bounded-portugal-2048x2048.png +0 -0
  77. package/docsmd/images/screenshots/static-with-path.png +0 -0
  78. package/examples/test-browser-es.html +102 -0
  79. package/examples/test-browser-umd.html +89 -0
  80. package/examples/test-node.js +52 -0
  81. package/images/JS-logo.svg +4 -0
  82. package/images/TS-logo.svg +6 -0
  83. package/images/maptiler-client-logo.afdesign +0 -0
  84. package/images/maptiler-client-logo.svg +75 -0
  85. package/images/maptiler-logo.svg +23 -0
  86. package/images/screenshots/static-bounded-europe-1024.png +0 -0
  87. package/images/screenshots/static-bounded-europe-2048.png +0 -0
  88. package/images/screenshots/static-bounded-portugal-1024x2048.png +0 -0
  89. package/images/screenshots/static-bounded-portugal-2048x2048.png +0 -0
  90. package/images/screenshots/static-with-path.png +0 -0
  91. package/package.json +69 -0
  92. package/readme.md +287 -0
  93. package/rollup.config.js +142 -0
  94. package/src/callFetch.ts +18 -0
  95. package/src/config.ts +65 -0
  96. package/src/defaults.ts +11 -0
  97. package/src/index.ts +90 -0
  98. package/src/language.ts +87 -0
  99. package/src/services/ServiceError.ts +10 -0
  100. package/src/services/coordinates.ts +258 -0
  101. package/src/services/data.ts +63 -0
  102. package/src/services/geocoding.ts +239 -0
  103. package/src/services/geolocation.ts +139 -0
  104. package/src/services/simplify.ts +87 -0
  105. package/src/services/staticMaps.ts +462 -0
  106. package/tsconfig.json +10 -0
  107. package/typedoc.json +10 -0
@@ -0,0 +1,462 @@
1
+ import { BBox, Position } from "geojson";
2
+ import { config } from "../config";
3
+ import { defaults } from "../defaults";
4
+ import simplify from "./simplify";
5
+
6
+ /**
7
+ * Base set of options that can be provided to all the types of static maps
8
+ */
9
+ export type StaticMapBaseOptions = {
10
+ /**
11
+ * Custom mapTiler Cloud API key to use instead of the one in global `config`
12
+ */
13
+ apiKey?: string;
14
+
15
+ /**
16
+ * Style of the map (not full style URL). Example: "winter", "streets-v2".
17
+ * Default: `"streets-v2"`
18
+ */
19
+ style?: string;
20
+
21
+ /**
22
+ * Double the size of the static map image to support hiDPI/Retina monitors.
23
+ * Default: `false`
24
+ */
25
+ hiDPI?: boolean;
26
+
27
+ /**
28
+ * Image format.
29
+ * Default: `"png"`
30
+ */
31
+ format?: "png" | "jpg" | "webp";
32
+
33
+ /**
34
+ * Width of the output image. Maximum value: `2048`.
35
+ * Default: `1024`
36
+ */
37
+ width?: number;
38
+
39
+ /**
40
+ * Height of the output image. Maximum value: `2048`.
41
+ * Default: `1024`
42
+ */
43
+ height?: number;
44
+
45
+ /**
46
+ * Placement of the attribution. Can also be set to `false` to not show attribution.
47
+ * Default: `"bottomright"`
48
+ */
49
+ attribution?: "bottomright" | "bottomleft" | "topleft" | "topright" | false;
50
+
51
+ /**
52
+ * A marker or list of markers to show on the map
53
+ * Default: none provided
54
+ */
55
+ markers?: StaticMapMarker | Array<StaticMapMarker>;
56
+
57
+ /**
58
+ * URL of the marker image. Applies only if one or multiple markers positions are provided.
59
+ * Default: none provided
60
+ */
61
+ markerIcon?: string;
62
+
63
+ /**
64
+ * Position of the marker regarding its coordinates. Applies only:
65
+ * - with a custom icon provided with `markerIcon`
66
+ * - if one or multiple markers positions are provided.
67
+ * Default: `"bottom"`
68
+ */
69
+ markerAnchor?:
70
+ | "top"
71
+ | "left"
72
+ | "bottom"
73
+ | "right"
74
+ | "center"
75
+ | "topleft"
76
+ | "bottomleft"
77
+ | "topright"
78
+ | "bottomright";
79
+
80
+ /**
81
+ * Draw a path or polygon on top of the map. If the path is too long it will be simplified, yet remaining accurate.
82
+ * Default: none provided
83
+ */
84
+ path?: Array<Position>;
85
+
86
+ /**
87
+ * Color of the path line. The color must be CSS compatible.
88
+ * Examples:
89
+ * - long form hex without transparency `"#FF0000"` (red)
90
+ * - short form hex without transparency `"#F00"` (red)
91
+ * - long form hex with transparency `"#FF000008"` (red, half opacity)
92
+ * - short form hex with transparency `"#F008"` (red, half opacity)
93
+ * - CSS color shorthands: `"red"`, `"chartreuse"`, etc.
94
+ * - decimal RGB values without transparency: `"rgb(128, 100, 255)"`
95
+ * - decimal RGB values with transparency: `"rgb(128, 100, 255, 0.5)"`
96
+ * Default: `"blue"`
97
+ */
98
+ pathStrokeColor?: string;
99
+
100
+ /**
101
+ * Color of the filling, also works if the polygon is not closed. The color must be CSS compatible.
102
+ * Examples:
103
+ * - long form hex without transparency `"#FF0000"` (red)
104
+ * - short form hex without transparency `"#F00"` (red)
105
+ * - long form hex with transparency `"#FF000008"` (red, half opacity)
106
+ * - short form hex with transparency `"#F008"` (red, half opacity)
107
+ * - CSS color shorthands: `"red"`, `"chartreuse"`, etc.
108
+ * - decimal RGB values without transparency: `"rgb(128, 100, 255)"`
109
+ * - decimal RGB values with transparency: `"rgb(128, 100, 255, 0.5)"`
110
+ * Default: none (transparent filling)
111
+ */
112
+ pathFillColor?: string;
113
+
114
+ /**
115
+ * Width of the path line in pixel. It can be floating point precision (ex: `0.5`)
116
+ * Default: `1` if `hiDPI` is `false` and `2` if `hiDPI` is `true`.
117
+ */
118
+ pathWidth?: number;
119
+ };
120
+
121
+ /**
122
+ * Options that can be provided to centered static maps
123
+ */
124
+ export type CenteredStaticMapOptions = StaticMapBaseOptions;
125
+
126
+ /**
127
+ * Options that can be provided to bounded static maps
128
+ */
129
+ export type BoundedStaticMapOptions = StaticMapBaseOptions & {
130
+ /**
131
+ * Extra space added around the regio of interest, in percentage.
132
+ * Default: `0.1` (for 10%)
133
+ */
134
+ padding?: number;
135
+ };
136
+
137
+ /**
138
+ * Options that can be provided to automatic static maps
139
+ */
140
+ export type AutomaticStaticMapOptions = BoundedStaticMapOptions;
141
+
142
+ /**
143
+ * Definition of a maker to show on a static map
144
+ */
145
+ export type StaticMapMarker = [
146
+ /**
147
+ * Longitude of the marker
148
+ */
149
+ number,
150
+ /**
151
+ * latitude of the marker
152
+ */
153
+ number,
154
+ /**
155
+ * Color of the marker with CSS syntax. Applies only if a custom `markerIcon` is not provided.
156
+ */
157
+ string
158
+ ];
159
+
160
+ function staticMapMarkerToString(
161
+ marker: StaticMapMarker,
162
+ includeColor = true
163
+ ): string {
164
+ let str = `${marker[0]},${marker[1]}`;
165
+
166
+ if (marker.length === 3 && includeColor) {
167
+ str += `,${marker[2]}`;
168
+ }
169
+
170
+ return str;
171
+ }
172
+
173
+ function simplifyAndStringify(path: Array<Position>, maxNbChar = 3000): string {
174
+ let str = path.map((point) => point.join(",")).join("|");
175
+ let tolerance = 0.000005;
176
+ const toleranceStep = 0.00001;
177
+
178
+ while (str.length > maxNbChar) {
179
+ const simplerPath = simplify(path, tolerance);
180
+ // str = simplerPath.map(point => point.join(',')).join('|');
181
+ str = simplerPath.map((point) => `${point[0]},${point[1]}`).join("|");
182
+ tolerance += toleranceStep;
183
+ }
184
+
185
+ return str;
186
+ }
187
+
188
+ /**
189
+ * Construct the URL for a static map centered on one point.
190
+ * Note: this function does not fetch the binary content of the image since
191
+ * the purpose of a static map is generally to have its URL as a `src` property of a <img/> element.
192
+ * If a path is provided and is too long, it will be simplified in an accurate way.
193
+ * @param center
194
+ * @param zoom
195
+ * @param options
196
+ * @returns
197
+ */
198
+ function centered(
199
+ center: Position,
200
+ zoom: number,
201
+ options: CenteredStaticMapOptions = {}
202
+ ): string {
203
+ const style = options.style ?? defaults.mapStyle;
204
+ const scale = options.hiDPI ? "@2x" : "";
205
+ const format = options.format ?? "png";
206
+ let width = ~~(options.width ?? 1024);
207
+ let height = ~~(options.height ?? 1024);
208
+
209
+ if (options.hiDPI) {
210
+ width = ~~(width / 2);
211
+ height = ~~(height / 2);
212
+ }
213
+
214
+ const endpoint = new URL(
215
+ `maps/${encodeURIComponent(style)}/static/${center[0]},${
216
+ center[1]
217
+ },${zoom}/${width}x${height}${scale}.${format}`,
218
+ defaults.maptilerApiURL
219
+ );
220
+
221
+ if ("attribution" in options) {
222
+ endpoint.searchParams.set("attribution", options.attribution.toString());
223
+ }
224
+
225
+ if ("markers" in options) {
226
+ let markerStr = "";
227
+
228
+ const hasIcon = "markerIcon" in options;
229
+
230
+ if (hasIcon) {
231
+ markerStr += `icon:${options.markerIcon}|`;
232
+ }
233
+
234
+ if (hasIcon && "markerAnchor" in options) {
235
+ markerStr += `anchor:${options.markerAnchor}|`;
236
+ }
237
+
238
+ if (hasIcon && options.hiDPI) {
239
+ markerStr += `scale:2|`;
240
+ }
241
+
242
+ const markerList = Array.isArray(options.markers[0])
243
+ ? options.markers
244
+ : [options.markers];
245
+ markerStr += markerList
246
+ .map((m) => staticMapMarkerToString(m, !hasIcon))
247
+ .join("|");
248
+ endpoint.searchParams.set("markers", markerStr);
249
+ }
250
+
251
+ if ("path" in options) {
252
+ let pathStr = "";
253
+
254
+ pathStr += `fill:${options.pathFillColor ?? "none"}|`;
255
+
256
+ if ("pathStrokeColor" in options) {
257
+ pathStr += `stroke:${options.pathStrokeColor}|`;
258
+ }
259
+
260
+ if ("pathWidth" in options) {
261
+ const pathWidth = options.pathWidth / (options.hiDPI ? 2 : 1);
262
+ pathStr += `width:${pathWidth.toString()}|`;
263
+ }
264
+
265
+ pathStr += simplifyAndStringify(options.path);
266
+ endpoint.searchParams.set("path", pathStr);
267
+ }
268
+
269
+ endpoint.searchParams.set("key", options.apiKey ?? config.apiKey);
270
+
271
+ return endpoint.toString();
272
+ }
273
+
274
+ /**
275
+ * Construct the URL for a static map using a bounding box
276
+ * Note: this function does not fetch the binary content of the image since
277
+ * the purpose of a static map is generally to have its URL as a `src` property of a <img/> element.
278
+ * If a path is provided and is too long, it will be simplified in an accurate way.
279
+ * @param boundingBox
280
+ * @param options
281
+ * @returns
282
+ */
283
+ function bounded(
284
+ boundingBox: BBox,
285
+ options: BoundedStaticMapOptions = {}
286
+ ): string {
287
+ const style = options.style ?? defaults.mapStyle;
288
+ const scale = options.hiDPI ? "@2x" : "";
289
+ const format = options.format ?? "png";
290
+ let width = ~~(options.width ?? 1024);
291
+ let height = ~~(options.height ?? 1024);
292
+
293
+ if (options.hiDPI) {
294
+ width = ~~(width / 2);
295
+ height = ~~(height / 2);
296
+ }
297
+
298
+ const endpoint = new URL(
299
+ `maps/${encodeURIComponent(style)}/static/${boundingBox[0]},${
300
+ boundingBox[1]
301
+ },${boundingBox[2]},${boundingBox[3]}/${width}x${height}${scale}.${format}`,
302
+ defaults.maptilerApiURL
303
+ );
304
+
305
+ if ("attribution" in options) {
306
+ endpoint.searchParams.set("attribution", options.attribution.toString());
307
+ }
308
+
309
+ if ("padding" in options) {
310
+ endpoint.searchParams.set("padding", options.padding.toString());
311
+ }
312
+
313
+ if ("markers" in options) {
314
+ let markerStr = "";
315
+
316
+ const hasIcon = "markerIcon" in options;
317
+
318
+ if (hasIcon) {
319
+ markerStr += `icon:${options.markerIcon}|`;
320
+ }
321
+
322
+ if (hasIcon && "markerAnchor" in options) {
323
+ markerStr += `anchor:${options.markerAnchor}|`;
324
+ }
325
+
326
+ if (hasIcon && options.hiDPI) {
327
+ markerStr += `scale:2|`;
328
+ }
329
+
330
+ const markerList = Array.isArray(options.markers[0])
331
+ ? options.markers
332
+ : [options.markers];
333
+ markerStr += markerList
334
+ .map((m) => staticMapMarkerToString(m, !hasIcon))
335
+ .join("|");
336
+ endpoint.searchParams.set("markers", markerStr);
337
+ }
338
+
339
+ if ("path" in options) {
340
+ let pathStr = "";
341
+
342
+ pathStr += `fill:${options.pathFillColor ?? "none"}|`;
343
+
344
+ if ("pathStrokeColor" in options) {
345
+ pathStr += `stroke:${options.pathStrokeColor}|`;
346
+ }
347
+
348
+ if ("pathWidth" in options) {
349
+ const pathWidth = options.pathWidth / (options.hiDPI ? 2 : 1);
350
+ pathStr += `width:${pathWidth.toString()}|`;
351
+ }
352
+
353
+ pathStr += simplifyAndStringify(options.path);
354
+ endpoint.searchParams.set("path", pathStr);
355
+ }
356
+
357
+ endpoint.searchParams.set("key", options.apiKey ?? config.apiKey);
358
+
359
+ return endpoint.toString();
360
+ }
361
+
362
+ /**
363
+ * Construct the URL for a static map automatically fitted around the provided path or markers.
364
+ * Note: this function does not fetch the binary content of the image since
365
+ * the purpose of a static map is generally to have its URL as a `src` property of a <img/> element.
366
+ * If a path is provided and is too long, it will be simplified in an accurate way.
367
+ * @param options
368
+ * @returns
369
+ */
370
+ function automatic(options: AutomaticStaticMapOptions = {}): string {
371
+ if (!("markers" in options) && !("path" in options)) {
372
+ throw new Error(
373
+ "Automatic static maps require markers and/or path to be created."
374
+ );
375
+ }
376
+
377
+ const style = options.style ?? defaults.mapStyle;
378
+ const scale = options.hiDPI ? "@2x" : "";
379
+ const format = options.format ?? "png";
380
+ let width = ~~(options.width ?? 1024);
381
+ let height = ~~(options.height ?? 1024);
382
+
383
+ if (options.hiDPI) {
384
+ width = ~~(width / 2);
385
+ height = ~~(height / 2);
386
+ }
387
+
388
+ const endpoint = new URL(
389
+ `maps/${encodeURIComponent(
390
+ style
391
+ )}/static/auto/${width}x${height}${scale}.${format}`,
392
+ defaults.maptilerApiURL
393
+ );
394
+
395
+ if ("attribution" in options) {
396
+ endpoint.searchParams.set("attribution", options.attribution.toString());
397
+ }
398
+
399
+ if ("padding" in options) {
400
+ endpoint.searchParams.set("padding", options.padding.toString());
401
+ }
402
+
403
+ if ("markers" in options) {
404
+ let markerStr = "";
405
+
406
+ const hasIcon = "markerIcon" in options;
407
+
408
+ if (hasIcon) {
409
+ markerStr += `icon:${options.markerIcon}|`;
410
+ }
411
+
412
+ if (hasIcon && "markerAnchor" in options) {
413
+ markerStr += `anchor:${options.markerAnchor}|`;
414
+ }
415
+
416
+ if (hasIcon && options.hiDPI) {
417
+ markerStr += `scale:2|`;
418
+ }
419
+
420
+ const markerList = Array.isArray(options.markers[0])
421
+ ? options.markers
422
+ : [options.markers];
423
+ markerStr += markerList
424
+ .map((m) => staticMapMarkerToString(m, !hasIcon))
425
+ .join("|");
426
+ endpoint.searchParams.set("markers", markerStr);
427
+ }
428
+
429
+ if ("path" in options) {
430
+ let pathStr = "";
431
+
432
+ pathStr += `fill:${options.pathFillColor ?? "none"}|`;
433
+
434
+ if ("pathStrokeColor" in options) {
435
+ pathStr += `stroke:${options.pathStrokeColor}|`;
436
+ }
437
+
438
+ if ("pathWidth" in options) {
439
+ const pathWidth = options.pathWidth / (options.hiDPI ? 2 : 1);
440
+ pathStr += `width:${pathWidth.toString()}|`;
441
+ }
442
+
443
+ pathStr += simplifyAndStringify(options.path);
444
+ endpoint.searchParams.set("path", pathStr);
445
+ }
446
+
447
+ endpoint.searchParams.set("key", options.apiKey ?? config.apiKey);
448
+
449
+ return endpoint.toString();
450
+ }
451
+
452
+ /**
453
+ * The **staticMaps** namespace contains an synchronous function build image URL of static map, as specified by the [MapTiler Static Map API](https://docs.maptiler.com/cloud/api/static-maps/).
454
+ * The URL of static maps can then be used within a `<img />` markup element, as the `src` property value.
455
+ */
456
+ const staticMaps = {
457
+ centered,
458
+ bounded,
459
+ automatic,
460
+ };
461
+
462
+ export { staticMaps };
package/tsconfig.json ADDED
@@ -0,0 +1,10 @@
1
+ {
2
+ "compilerOptions": {
3
+ "moduleResolution": "Node",
4
+ "target": "es6",
5
+ "declaration": true,
6
+ "allowSyntheticDefaultImports": true,
7
+ "resolveJsonModule": true
8
+ }
9
+
10
+ }
package/typedoc.json ADDED
@@ -0,0 +1,10 @@
1
+ {
2
+ "entryPoints": ["./src/index.ts"],
3
+ "name": "MapTiler Client JS",
4
+ "out": "docs",
5
+ "excludePrivate": true,
6
+ "excludeProtected": true,
7
+ "excludeExternals": true,
8
+ "excludeNotDocumented": false,
9
+ "excludeInternal": true
10
+ }