Resolve a place

Turn a place name into the normalized entity Invokely uses, with its official codes (INE, Idescat, NUTS, ISO, US FIPS) and parent. Use it when a name is ambiguous or you want to confirm which entity a number refers to. The other tools accept names directly, so this call is optional. Ambiguous names prefer the municipality ("Barcelona" is the city); the province and region come back in alternatives. Ask for "provincia de Barcelona" to get the province. US states are regions, US counties are provinces and US cities (incorporated places of 10,000 or more residents, coded by 7-digit Census GEOID) are municipalities under their state. Names shared by several places of the same level, such as "Washington County" or "Springfield", return an AMBIGUOUS_PLACE error with suggestions; add the state ("Washington County, Oregon", "Springfield, IL") or pass a suggested id. A bare city name that is also a state or another place ("New York", "Washington") keeps meaning that place: ask for "New York City" or "Washington, UT". Example: {"name": "Mataró"}. Returns {match: {id, name, level, country, population, parent, codes}, alternatives: [{id, name, level}]}.

get/api/v1/places/resolve

Request

  • Base URL: https://invokely.ai
  • URL: https://invokely.ai/api/v1/places/resolve
  • Auth: one of:
    • HTTP bearer
    • API key in header x-api-key
    • none

Query parameters

namestring required

Place name or id.

countrystring

ISO 3166-1 alpha-2 code that disambiguates the place, for example ES or US.

level'municipality' | 'province' | 'region' | 'country' | 'supranational'

Preferred level. US cities are municipalities, US counties provinces and US states regions.

Response

Success. The body is {"data": ...}; the remaining allowance is in the x-invokely-remaining header.

dataunknown required

Changes

No recorded changes to this operation across all 1 revision of this API.