GET /geo/search

Performs a fuzzy search across all place names and returns the best matches ranked by similarity and population.

Useful for autocomplete, debugging resolution issues, or exploring the place database.

Costs 1 credit per request.

Request

GET /geo/search?q={term}&limit={n}
Authorization: Bearer gaz_<api-key>

Query Parameters

Parameter	Type	Default	Description
q	string	required	Search term
limit	integer	5	Maximum number of results to return

Response

[
  {
    "id": 3448439,
    "name": "São Paulo",
    "type": "city",
    "score": 0.909,
    "population": 12252023
  },
  {
    "id": 3448433,
    "name": "São Paulo",
    "type": "state",
    "score": 0.909,
    "population": 44396484
  }
]

Fields

Field	Type	Description
id	integer	Place ID
name	string	Official place name
type	string	world | country | state | city
score	float	Similarity score (0.0–1.0)
population	integer	Population count

Results are sorted by score DESC, population DESC.

Error Responses

Status	Description
401	Missing or invalid API key
402	Insufficient credits
429	Rate limit exceeded

Examples

Search for a city

curl "https://api.gazetteer.dev/geo/search?q=cuiab%C3%A1&limit=3" \
  -H "Authorization: Bearer gaz_..."

[
  { "id": 3952981, "name": "Cuiabá", "type": "city", "score": 1.0, "population": 615297 }
]

Handling typos

The search tolerates minor typos and missing accents:

curl "https://api.gazetteer.dev/geo/search?q=sao+paulo" \
  -H "Authorization: Bearer gaz_..."

Results with score below PostgreSQL’s pg_trgm threshold (~0.3) are automatically excluded.