@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,239 @@
1
+ import { BBox, Feature, 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 GeocodingOptions = {
19
+ /**
20
+ * Custom mapTiler Cloud API key to use instead of the one in global `config`
21
+ */
22
+ apiKey?: string;
23
+
24
+ /**
25
+ * Only search for results in the specified area.
26
+ */
27
+ bbox?: BBox;
28
+
29
+ /**
30
+ * Prefer results close to a specific location.
31
+ */
32
+ proximity?: Position;
33
+
34
+ /**
35
+ * Prefer results in specific language. It’s possible to specify multiple values.
36
+ */
37
+ language?: LanguageGeocodingString | Array<LanguageGeocodingString>;
38
+ };
39
+
40
+ export type Coordinates = Position;
41
+
42
+ export type FeatureHierarchy = {
43
+ /**
44
+ * Unique feature ID
45
+ */
46
+ id: string;
47
+
48
+ /**
49
+ * Localized feature name
50
+ */
51
+ text: string;
52
+ };
53
+
54
+ export type GeocodingFeature = Feature & {
55
+ /**
56
+ * Bounding box of the original feature as [w, s, e, n] array
57
+ */
58
+ bbox: BBox;
59
+
60
+ /**
61
+ * A [lon, lat] array of the original feature centeroid
62
+ */
63
+ center: Coordinates;
64
+
65
+ /**
66
+ * Formatted (including the hierarchy) and localized feature full name
67
+ */
68
+ place_name: string;
69
+
70
+ /**
71
+ * Localized feature name
72
+ */
73
+ text: string;
74
+
75
+ /**
76
+ * Feature hierarchy
77
+ */
78
+ context?: Array<FeatureHierarchy>;
79
+
80
+ /**
81
+ * Address number, if applicable
82
+ */
83
+ address?: string;
84
+ };
85
+
86
+ export type GeocodingSearchResult = {
87
+ type: "FeatureCollection";
88
+
89
+ /**
90
+ * Array of features found
91
+ */
92
+ features: Array<GeocodingFeature>;
93
+
94
+ /**
95
+ * Tokenized search query
96
+ */
97
+ query: Array<string>;
98
+
99
+ /**
100
+ * Attribution of the result
101
+ */
102
+ attribution: string;
103
+ };
104
+
105
+ /**
106
+ * Performs a forward geocoding query to MapTiler API.
107
+ * Providing a human readable place name (of a city, country, street, etc.), the function returns
108
+ * a list of candidate locations including longitude and latitude.
109
+ * Learn more on the MapTiler API reference page: https://docs.maptiler.com/cloud/api/geocoding/#search-by-name-forward
110
+ * @param query
111
+ * @param options
112
+ * @returns
113
+ */
114
+ async function forward(
115
+ query: string,
116
+ options: GeocodingOptions = {}
117
+ ): Promise<GeocodingSearchResult> {
118
+ if (typeof query !== "string" || query.trim().length === 0) {
119
+ throw new Error("The query must be a non-empty string");
120
+ }
121
+
122
+ const endpoint = new URL(
123
+ `geocoding/${encodeURIComponent(query)}.json`,
124
+ defaults.maptilerApiURL
125
+ );
126
+ endpoint.searchParams.set("key", options.apiKey ?? config.apiKey);
127
+
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
+ }
135
+
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
+ }
150
+
151
+ const urlWithParams = endpoint.toString();
152
+ const res = await callFetch(urlWithParams);
153
+
154
+ if (!res.ok) {
155
+ throw new ServiceError(
156
+ res,
157
+ res.status in customMessages ? customMessages[res.status] : ""
158
+ );
159
+ }
160
+
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;
170
+
171
+ /**
172
+ * Prefer results in specific language. It’s possible to specify multiple values.
173
+ */
174
+ language?: LanguageGeocodingString | Array<LanguageGeocodingString>;
175
+ };
176
+
177
+ /**
178
+ * 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.)
180
+ * Learn more on the MapTiler API reference page: https://docs.maptiler.com/cloud/api/geocoding/#search-by-coordinates-reverse
181
+ * @param position
182
+ * @param options
183
+ * @returns
184
+ */
185
+ async function reverse(
186
+ position: Position,
187
+ options: ReverseGeocodingOptions = {}
188
+ ): Promise<GeocodingSearchResult> {
189
+ if (!Array.isArray(position) || position.length < 2) {
190
+ throw new Error("The position must be an array of form [lng, lat].");
191
+ }
192
+
193
+ const endpoint = new URL(
194
+ `geocoding/${position[0]},${position[1]}.json`,
195
+ defaults.maptilerApiURL
196
+ );
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
+
211
+ endpoint.searchParams.set("language", languages);
212
+ }
213
+
214
+ const urlWithParams = endpoint.toString();
215
+ const res = await callFetch(urlWithParams);
216
+
217
+ if (!res.ok) {
218
+ throw new ServiceError(
219
+ res,
220
+ res.status in customMessages ? customMessages[res.status] : ""
221
+ );
222
+ }
223
+
224
+ const obj = await res.json();
225
+ return obj as GeocodingSearchResult;
226
+ }
227
+
228
+ /**
229
+ * The **geocoding** namespace contains asynchronous functions to call the [MapTiler Geocoding API](https://docs.maptiler.com/cloud/api/geocoding/).
230
+ * The **Geocoding API** provides ways to get geographic coordinates from a human-readable search query of a place (forward geocoding)
231
+ * and to get the location details (country, city, street, etc.) from a geographic coordinate (reverse geocoding);
232
+ */
233
+ const geocoding = {
234
+ forward,
235
+ reverse,
236
+ language: LanguageGeocoding,
237
+ };
238
+
239
+ export { geocoding };
@@ -0,0 +1,139 @@
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 };
@@ -0,0 +1,87 @@
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
+ }