---
title: "Resolve a place"
method: GET
path: "/api/v1/places/resolve"
---

# Resolve a place

`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

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}]}.

## Query parameters

- `name` string, required
- `country` string
- `level` 'municipality' | 'province' | 'region' | 'country' | 'supranational'

## Response `200`

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

- Data
  - `data` unknown, required

## Other responses

- `400`: Invalid argument (INVALID_ARGUMENT).
- `401`: The API key or token is invalid or revoked (UNAUTHORIZED).
- `402`: Allowance used up (QUOTA_EXHAUSTED), or the plan does not include the REST API (PLAN_REQUIRED: Free keys; use the MCP server or upgrade to Builder).
- `404`: Unknown indicator or place, or no data (INDICATOR_NOT_FOUND, PLACE_NOT_FOUND, AMBIGUOUS_PLACE, NO_DATA). hint and suggestions say what to try next.
- `429`: Rate limited (RATE_LIMITED). Retry after retry_after_seconds.

---

[API](https://skmtc.dev/invokely/apis/invokely-statistics-api.md) · [All operations](https://skmtc.dev/invokely/apis/invokely-statistics-api/llms.txt) · [OpenAPI document](https://skmtc.dev/invokely/apis/invokely-statistics-api/revisions/3b0f775bccb6?raw)