get/v1/cities

Search cities, one entry per place

Operation: listCities
Authentication: API key

The same capture `/v1/airports` serves, deduplicated to one entry per city.

**Why this is not just a flag on `/v1/airports`.** That endpoint carries a `municipality` and already ranks on it, so `Nairobi` resolves there — but it returns *airports*, and Osaka is 420 of them. A picker built on it offers 420 Osakas and no way to choose between them. This returns the city once, with the codes you would act on attached.

Scoped to cities with a **bookable** airport, an IATA code and scheduled service: 3,965 of them. The other ~34,000 municipalities in the capture are airfields, heliports and closed strips, and a city list built from those is a list of places nobody can fly to.

Matching is case- and accent-insensitive, so `sao paulo` finds `São Paulo` — but the name returned is the source’s spelling, because a picker that answers `Sao Paulo` has silently renamed a city.

**Not metered**, like everything else on this tag: no eligibility work is done.

Request

Parameters

qquerystring

country_iso2querystring

limitqueryinteger

Responses

200Matching cities, ranked: exact name, then prefix, then substring.

citiesCity[]required

countsobjectrequired

sourcestringrequired

OurAirports, community-maintained — derived from the same capture `/v1/airports` serves, and a reference rather than a government publication.

next_cursorstringnullrequired

400The request body or query failed validation.

errorobjectrequired

401No key, an unknown key, a revoked key, or a key whose tenant is not active. All four return an identical body on purpose: distinguishing them would let a caller discover which partners we have.

errorobjectrequired

403The key is valid but does not hold the scope this route requires.

errorobjectrequired

404Not found, or not yours. A resource belonging to another tenant answers 404 rather than 403, because 403 would confirm the record exists.

errorobjectrequired

Example

curl

curl -X GET https://api.haavisa.com/v1/cities \
  -H "Authorization: Bearer $HAAVISA_API_KEY"

More in Reference

Something unclear? The eligibility guide explains the model behind the answers; the errors guide covers the envelope.