POST /geo/resolve

Finds the Lowest Common Ancestor (LCA) of a list of place names — the most specific geographic region that contains all of them.

Costs 1 credit per request.

Request

POST /geo/resolve
Authorization: Bearer gaz_<api-key>
Content-Type: text/plain
X-Min-Score: 0.6   (optional)

Body: newline-separated list of place names (plain text).

Cuiabá
Sinop
Rondonópolis

Headers

Header	Type	Default	Description
Authorization	string	required	Bearer gaz_<api-key>
X-Min-Score	float	0.6	Minimum similarity score (0.0–1.0) for a name to be considered resolved. Names below this threshold are skipped and counted in unresolved.

Response

{
  "region": "Mato Grosso",
  "type": "state",
  "region_id": 3457419,
  "unresolved": 0,
  "total": 3
}

Fields

Field	Type	Description
region	string	Name of the common ancestor region
type	string	world | country | state | city
region_id	integer	Place ID — use with GET /geo/place/{id}
unresolved	integer	Number of input names that couldn’t be matched above X-Min-Score
total	integer	Total number of input names sent

Error Responses

Status	Description
401	Missing or invalid API key
402	Insufficient credits
404	No common region found (all inputs resolved to places with no common ancestor, or all unresolved)
422	Empty request body
429	Rate limit exceeded

404 body

{
  "detail": {
    "message": "No common region found",
    "unresolved": 1,
    "total": 3
  }
}

Examples

Basic usage

curl -X POST https://api.gazetteer.dev/geo/resolve \
  -H "Authorization: Bearer gaz_..." \
  -H "Content-Type: text/plain" \
  --data "Paris
Lyon
Marseille"

{
  "region": "France",
  "type": "country",
  "region_id": 3017382,
  "unresolved": 0,
  "total": 3
}

With a stricter similarity threshold

Raise X-Min-Score to reject ambiguous matches:

curl -X POST https://api.gazetteer.dev/geo/resolve \
  -H "Authorization: Bearer gaz_..." \
  -H "X-Min-Score: 0.8" \
  -H "Content-Type: text/plain" \
  --data "São Paulo
Campinas"

Interpreting unresolved

A non-zero unresolved count means some inputs were skipped. The LCA was computed only over the resolved subset. If confidence matters, check:

confidence = (total - unresolved) / total