GO-750-improved-geocoding-types-limit-jsdoc

CHANGELOG.md

@@ -1,35 +1,55 @@
 # MapTiler Client Changelog
 
+## UNRELEASED
+
+### New Features
+
+- Improved geocoding types and limit documentation
+
 ## 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)

src/services/geocoding.ts

@@ -33,13 +33,17 @@ export type CommonForwardAndReverseGeocodingOptions =
     apiKey?: string;
 
     /**
-     * Maximum number of results to show. Must be between 1 and 10. Default is 5 for forward and 1 for reverse geocoding.
+     * Maximum number of results to show. Must be between 1 and 10.
+     * For reverse geocoding with multiple `types` this must not be set or must be set to 1.
+     * Default is 5 for forward and 1 for reverse geocoding.
      */
     limit?: number;
 
     /**
-     * Filter of feature types to return.
+     * Features of specified types to return.
      * If not specified, feature of all available types except `poi` are returned (`types = ["poi"]`, `excludeTypes = true`).
+     * In case of reverse geocoding if just a single type is specified, then multiple nearby features of the single type can be returned,
+     * otherwise single feature for every specified type (or default types) can be returned.
      */
     types?: (
       | "country"
@@ -259,7 +263,7 @@ export type GeocodingSearchResult = {
 
 function addLanguageGeocodingOptions(
   searchParams: URLSearchParams,
-  options: LanguageGeocodingOptions,
+  options: LanguageGeocodingOptions
 ) {
   const { language } = options;
 
@@ -278,7 +282,7 @@ function addLanguageGeocodingOptions(
 }
 
 function toValidGeocodingLanguageCode(
-  lang: string | LanguageInfo,
+  lang: string | LanguageInfo
 ): string | null {
   let langInfo: LanguageInfo | null = null;
 
@@ -301,7 +305,7 @@ function toValidGeocodingLanguageCode(
 
 function addCommonForwardAndReverseGeocodingOptions(
   searchParams: URLSearchParams,
-  options: CommonForwardAndReverseGeocodingOptions,
+  options: CommonForwardAndReverseGeocodingOptions
 ) {
   const { apiKey, limit, types, excludeTypes } = options;
 
@@ -324,7 +328,7 @@ function addCommonForwardAndReverseGeocodingOptions(
 
 function addForwardGeocodingOptions(
   searchParams: URLSearchParams,
-  options: GeocodingOptions,
+  options: GeocodingOptions
 ) {
   addCommonForwardAndReverseGeocodingOptions(searchParams, options);
 
@@ -337,7 +341,7 @@ function addForwardGeocodingOptions(
   if (proximity !== undefined) {
     searchParams.set(
       "proximity",
-      proximity === "ip" ? proximity : proximity.join(","),
+      proximity === "ip" ? proximity : proximity.join(",")
     );
   }
 
@@ -365,15 +369,15 @@ function addForwardGeocodingOptions(
  */
 async function forward(
   query: string,
-  options: GeocodingOptions = {},
+  options: GeocodingOptions = {}
 ): Promise<GeocodingSearchResult> {
   if (typeof query !== "string" || query.trim().length === 0) {
     throw new Error("The query must be a non-empty string");
   }
 
   const endpoint = new URL(
     `geocoding/${encodeURIComponent(query)}.json`,
-    defaults.maptilerApiURL,
+    defaults.maptilerApiURL
   );
 
   const { searchParams } = endpoint;
@@ -403,15 +407,15 @@ async function forward(
  */
 async function reverse(
   position: Position,
-  options: ReverseGeocodingOptions = {},
+  options: ReverseGeocodingOptions = {}
 ): Promise<GeocodingSearchResult> {
   if (!Array.isArray(position) || position.length < 2) {
     throw new Error("The position must be an array of form [lng, lat].");
   }
 
   const endpoint = new URL(
     `geocoding/${position[0]},${position[1]}.json`,
-    defaults.maptilerApiURL,
+    defaults.maptilerApiURL
   );
 
   addCommonForwardAndReverseGeocodingOptions(endpoint.searchParams, options);
@@ -440,7 +444,7 @@ async function reverse(
  */
 async function byId(
   id: string,
-  options: ByIdGeocodingOptions = {},
+  options: ByIdGeocodingOptions = {}
 ): Promise<GeocodingSearchResult> {
   const endpoint = new URL(`geocoding/${id}.json`, defaults.maptilerApiURL);
   endpoint.searchParams.set("key", options.apiKey ?? config.apiKey);
@@ -470,7 +474,7 @@ async function byId(
  */
 async function batch(
   queries: string[],
-  options: GeocodingOptions = {},
+  options: GeocodingOptions = {}
 ): Promise<GeocodingSearchResult[]> {
   if (!queries.length) {
     return [];
@@ -482,7 +486,7 @@ async function batch(
 
   const endpoint = new URL(
     `geocoding/${joinedQuery}.json`,
-    defaults.maptilerApiURL,
+    defaults.maptilerApiURL
   );
 
   const { searchParams } = endpoint;