Type mismatch with actual geocoding search results

[wpf500]

Hi there,

I think there are a few problems with the geocoding search result related types. I would expect to be able to assign the result from a forward or reverse geocode with the type GeocodingSearchResult

// Copy/paste a search result, e.g. https://api.maptiler.com/geocoding/13.404671781826039,51.94999513721038.json?language=de
const result: GeocodingSearchResult = {
  type: 'FeatureCollection',
 // etc.
}

This should compile, but there are currently three problems with the library types which prevent this, with the mismatch also reflected in the documentation. Below I've laid out the problems and proposed updates to the types, but I don't know if these accurately reflect the intended data model from your API, so they might not be correct.

We are trying to assign types to our test fixture data. At the moment our workaround is just to trick the compiler, but it would be a lot nicer if the types could be used properly.

const fixture1 = { ... } as unknown as GeocodingSearchResult;

Problem 1

GeocodingSearchResult['query'] is a Array<string>, but when reverse geocoding the query is a [number, number]

Error:

Type 'number' is not assignable to type 'string'.ts(2322)

Example data:

{
  // ...other properties
  query: [6.055619932005584, 46.233004881941895]
}

Docs: https://docs.maptiler.com/cloud/api/geocoding/#searchresults-query

Simple solution: GeocodingSearchResult['query'] could be changed to Array<string | number>

Better solution?: split forward and reverse GeocodingSearchResult

type GeocodingSearchResult<T> = {
    type: "FeatureCollection";
    /**
     * Array of features found
     */
    features: Array<GeocodingFeature>;
    /**
     * Tokenized search query
     */
    query: T;
    /**
     * Attribution of the result
     */
    attribution: string;
};

type ForwardGeocodingSearchResult = GeocodingSearchResult<string[]>;
type ReverseGeocodingSearchResult = GeocodingSearchResult<[number, number]>;

Problem 2

place_type_name is not allowed in GeocodingFeature['properties']

Error:

Object literal may only specify known properties, and 'place_type_name' does not exist in type 'FeatureProperties'.ts(2353)
index.d.ts(158, 5): The expected type comes from property 'properties' which is declared here on type 'GeocodingFeature'

Example data:

properties: {
  ref: 'osm:w77073776',
  country_code: 'ch',
  kind: 'place',
  place_type_name: ['address'], // Causes error
},

Docs: https://docs.maptiler.com/cloud/api/geocoding/#FeatureProperties

Solution: add place_type_name to FeatureProperties, but by renaming original FeatureProperties to FeaturePropertiesBase so type definition only extends to GeocodingFeature['properties'] and not FeatureHierarchy

type FeaturePropertiesBase = {
 // ...
};
type FeatureProperties = FeaturePropertiesBase & {
    /**
     * Localized type of the place name
     */
    place_type_name?: string[];
}
type FeatureHierarchy = FeaturePropertiesBase & FeatureBase;

Problem 3

country_code is required in FeatureHierarchy, but not present in all contexts (e.g. continental_marine)

Error:

Type '{ ref: string; id: string; text: string; wikidata: string; categories: string[]; language: string; 'osm:tags': { population: string; place: string; wikipedia: string; sqkm: string; }; text_en: string; language_en: string; }' is not assignable to type 'FeatureHierarchy'.
  Property 'country_code' is missing in type '{ ref: string; id: string; text: string; wikidata: string; categories: string[]; language: string; 'osm:tags': { population: string; place: string; wikipedia: string; sqkm: string; }; text_en: string; language_en: string; }' but required in type 'FeaturePropertiesBase'.ts(2322)
maptiler-client.d.ts(912, 5): 'country_code' is declared here.

Example data:

{
  ref: 'osm:n25871341',
  id: 'continental_marine.1',
  text: 'Europe',
  wikidata: 'Q46',
  categories: ['continent'],
  language: 'en',
  'osm:tags': {
    population: '739165030',
    place: 'continent',
    wikipedia: 'eo:Eŭropo',
    sqkm: '10180000',
  },
  text_en: 'Europe',
  language_en: 'en',
  // no country_code property
},

Docs: https://docs.maptiler.com/cloud/api/geocoding/#context-country-code

Solution: make country_code optional? I guess this probably isn't ideal as in most cases country_code is expected, and listed in your docs as required

[katemihalikova]

Hello, thanks for reporting these problems! We had a look at it and are currently investigating, which also includes syncing with the owner of the affected API. We will let you know when these problems get addressed.

You've already provided workaround steps for the first problem, the same can be done for the second problem (... as unknown as ...). To work around the third problem, please treat the property as optional for now.