Skip to content

Commit

Permalink
GO-633 updated geocoding API
Browse files Browse the repository at this point in the history
  • Loading branch information
zdila committed Oct 1, 2024
1 parent 4d5269a commit 8d75709
Show file tree
Hide file tree
Showing 4 changed files with 117 additions and 64 deletions.
27 changes: 27 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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)
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -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",
Expand Down
148 changes: 87 additions & 61 deletions src/services/geocoding.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand All @@ -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.
Expand Down Expand Up @@ -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,
Expand All @@ -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(
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -443,27 +431,26 @@ async function byId(
options: ByIdGeocodingOptions = {},
): Promise<GeocodingSearchResult> {
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
Expand All @@ -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] ?? "");
Expand All @@ -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<GeocodingConfiguration> {
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<GeocodingType[]> {
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)
Expand All @@ -512,6 +536,8 @@ const geocoding = {
reverse,
byId,
batch,
getConfiguration,
getTypes,
};

export { geocoding };

0 comments on commit 8d75709

Please sign in to comment.