diff --git a/CHANGELOG.md b/CHANGELOG.md index dd8d9af..0d47250 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,35 +1,62 @@ # MapTiler Client Changelog +## 2.1.0 + +### New Features + +- Added `getConfiguration` and `getTypes` functions to geocoding API +- Geocoding `types` is no more an enumeration but just a `string` + +### Bug Fixes + +### Others + +- Languages are now listed in the Client library + ## 2.0.0 + ### New Features + - Added `matching_text` and `matching_place_name` properties to geocoding feature response - Added `road` to geocoding `types` + ### Bug Fixes + ### Others + - Languages are now listed in the Client library ## 1.8.1 + ### Bug Fixes + - The QuickLRU dependency is not CJS compatible to it is now fully bundled into the CJS bundle ### Others + - Moved somes wrongly positioned deps into devDep ## 1.8.0 + ### New Features + - Rework of the elevation API to be improve developper experience (new module `elevation`) - Expoing some geo math with the new `math` module - synchronized geocoding types with current geocoding API - added `excludeTypes` option to geocoding API ## 1.7.0 + ### New Features + - DEM elevation API (https://github.com/maptiler/maptiler-client-js/pull/24) ### Bug Fixes + - `geocoding.byId` can now be used with the apiKey (https://github.com/maptiler/maptiler-client-js/pull/27) - the Typescript types are now properly exported (https://github.com/maptiler/maptiler-client-js/pull/25) ### Others + - the Typescript `moduleResolution` is now `"Bundler"` (used to be `"Node"`) (https://github.com/maptiler/maptiler-client-js/pull/28) - updated some dev-dependencies (https://github.com/maptiler/maptiler-client-js/pull/28) diff --git a/package-lock.json b/package-lock.json index 6df56d3..407abbb 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@maptiler/client", - "version": "2.0.0", + "version": "2.1.0", "lockfileVersion": 2, "requires": true, "packages": { "": { "name": "@maptiler/client", - "version": "2.0.0", + "version": "2.1.0", "license": "BSD-3-Clause", "dependencies": { "quick-lru": "^7.0.0" diff --git a/package.json b/package.json index fb84b00..994caa5 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@maptiler/client", - "version": "2.0.0", + "version": "2.1.0", "description": "Javascript & Typescript wrapper to MapTiler Cloud API", "module": "dist/maptiler-client.mjs", "types": "dist/maptiler-client.d.ts", diff --git a/src/services/geocoding.ts b/src/services/geocoding.ts index fa2f067..81ce1d7 100644 --- a/src/services/geocoding.ts +++ b/src/services/geocoding.ts @@ -28,7 +28,7 @@ export type LanguageGeocodingOptions = { export type CommonForwardAndReverseGeocodingOptions = LanguageGeocodingOptions & { /** - * Custom MapTiler Cloud API key to use instead of the one in global `config` + * Custom MapTiler Cloud API key to use instead of the one in global `config`. */ apiKey?: string; @@ -39,25 +39,9 @@ export type CommonForwardAndReverseGeocodingOptions = /** * Filter of feature types to return. - * If not specified, feature of all available types except `poi` are returned (`types = ["poi"]`, `excludeTypes = true`). + * If not specified, default types are used. */ - types?: ( - | "country" - | "region" - | "subregion" - | "county" - | "joint_municipality" - | "joint_submunicipality" - | "municipality" - | "municipal_district" - | "locality" - | "neighbourhood" - | "place" - | "postal_code" - | "address" - | "road" - | "poi" - )[]; + types?: string[]; /** * Set to `true` to use all available feature types except those mentioned in `types`. Default value is `false` if `types` is specified. @@ -257,6 +241,19 @@ export type GeocodingSearchResult = { attribution: string; }; +export type GeocodingType = { + /** Name of the type */ + type: string; + + /** Tells if the type is included per default if no types parameter is explicitly provided */ + default: boolean; +}; + +export type GeocodingConfiguration = { + /** All available geocoding types */ + types: GeocodingType[]; +}; + function addLanguageGeocodingOptions( searchParams: URLSearchParams, options: LanguageGeocodingOptions, @@ -280,23 +277,18 @@ function addLanguageGeocodingOptions( function toValidGeocodingLanguageCode( lang: string | LanguageInfo, ): string | null { - let langInfo: LanguageInfo | null = null; - - if (lang === Language.AUTO.flag) { - // equal to the string "auto" - langInfo = getAutoLanguage(); - } else if (typeof lang === "string") { - langInfo = getLanguageInfoFromCode(lang); - } else if (isLanguageInfo(lang)) { - langInfo = - lang.flag === Language.AUTO.flag + const langInfo = + lang === Language.AUTO.flag + ? getAutoLanguage() + : typeof lang === "string" + ? getLanguageInfoFromCode(lang) + : isLanguageInfo(lang) + ? lang.flag === Language.AUTO.flag ? getAutoLanguage() - : getLanguageInfoFromFlag(lang.flag); - } + : getLanguageInfoFromFlag(lang.flag) + : null; - if (!langInfo) return null; - if (langInfo.geocoding) return langInfo.code; - return null; + return langInfo?.geocoding ? langInfo.code : null; } function addCommonForwardAndReverseGeocodingOptions( @@ -358,7 +350,9 @@ function addForwardGeocodingOptions( * Performs a forward geocoding query to MapTiler API. * Providing a human readable place name (of a city, country, street, etc.), the function returns * a list of candidate locations including longitude and latitude. + * * Learn more on the MapTiler API reference page: https://docs.maptiler.com/cloud/api/geocoding/#search-by-name-forward + * * @param query * @param options * @returns @@ -376,27 +370,23 @@ async function forward( defaults.maptilerApiURL, ); - const { searchParams } = endpoint; - - addForwardGeocodingOptions(searchParams, options); + addForwardGeocodingOptions(endpoint.searchParams, options); - const urlWithParams = endpoint.toString(); - - const res = await callFetch(urlWithParams); + const res = await callFetch(endpoint.toString()); if (!res.ok) { throw new ServiceError(res, customMessages[res.status] ?? ""); } - const obj: GeocodingSearchResult = await res.json(); - - return obj; + return await res.json(); } /** * Perform a reverse geocoding query to MapTiler API. * Providing a longitude and latitude, this function returns a set of human readable information about this place (country, city, street, etc.) + * * Learn more on the MapTiler API reference page: https://docs.maptiler.com/cloud/api/geocoding/#search-by-coordinates-reverse + * * @param position * @param options * @returns @@ -416,24 +406,22 @@ async function reverse( addCommonForwardAndReverseGeocodingOptions(endpoint.searchParams, options); - const urlWithParams = endpoint.toString(); - - const res = await callFetch(urlWithParams); + const res = await callFetch(endpoint.toString()); if (!res.ok) { throw new ServiceError(res, customMessages[res.status] ?? ""); } - const obj: GeocodingSearchResult = await res.json(); - - return obj; + return await res.json(); } /** * Perform a geocoding query to MapTiler API to obtain fature by its ID. * Providing a feature ID, this function returns a feature which includes its full geometry. * Note that the feature ID is not stable and it changes when the database is re-indexed. + * * Learn more on the MapTiler API reference page: https://docs.maptiler.com/cloud/api/geocoding/#search-by-feature-id + * * @param id * @param options * @returns @@ -443,27 +431,26 @@ async function byId( options: ByIdGeocodingOptions = {}, ): Promise { const endpoint = new URL(`geocoding/${id}.json`, defaults.maptilerApiURL); + endpoint.searchParams.set("key", options.apiKey ?? config.apiKey); addLanguageGeocodingOptions(endpoint.searchParams, options); - const urlWithParams = endpoint.toString(); - - const res = await callFetch(urlWithParams); + const res = await callFetch(endpoint.toString()); if (!res.ok) { throw new ServiceError(res, customMessages[res.status] ?? ""); } - const obj: GeocodingSearchResult = await res.json(); - - return obj; + return await res.json(); } /** * Perform a batch geocoding query to MapTiler API. * Provide multiple queries in the array. Each query can be forward, reverse or by feature ID. + * * Learn more on the MapTiler API reference page: https://docs.maptiler.com/cloud/api/geocoding/#batch-geocoding + * * @param queries * @param options * @returns @@ -485,13 +472,9 @@ async function batch( defaults.maptilerApiURL, ); - const { searchParams } = endpoint; + addForwardGeocodingOptions(endpoint.searchParams, options); - addForwardGeocodingOptions(searchParams, options); - - const urlWithParams = endpoint.toString(); - - const res = await callFetch(urlWithParams); + const res = await callFetch(endpoint.toString()); if (!res.ok) { throw new ServiceError(res, customMessages[res.status] ?? ""); @@ -502,6 +485,47 @@ async function batch( return queries.length === 1 ? [obj] : obj; } +/** + * Get geocoding service configuration. + * + * Learn more on the MapTiler API reference page: https://docs.maptiler.com/cloud/api/geocoding/#get-configuration + * + * @returns + */ +async function getConfiguration(): Promise { + const res = await callFetch( + new URL("geocoding/configuration", defaults.maptilerApiURL).toString(), + ); + + if (!res.ok) { + throw new ServiceError(res); + } + + return await res.json(); +} + +/** + * Get all available geocoding types. + * + * Learn more on the MapTiler API reference page: https://docs.maptiler.com/cloud/api/geocoding/#get-types + * + * @returns + */ +async function getTypes(): Promise { + const res = await callFetch( + new URL( + "geocoding/configuration/types", + defaults.maptilerApiURL, + ).toString(), + ); + + if (!res.ok) { + throw new ServiceError(res); + } + + return await res.json(); +} + /** * The **geocoding** namespace contains asynchronous functions to call the [MapTiler Geocoding API](https://docs.maptiler.com/cloud/api/geocoding/). * The **Geocoding API** provides ways to get geographic coordinates from a human-readable search query of a place (forward geocoding) @@ -512,6 +536,8 @@ const geocoding = { reverse, byId, batch, + getConfiguration, + getTypes, }; export { geocoding };