Geo v2
geo-v2

Search Cities (v2)

Search for cities by name prefix for autocomplete functionality.

Authentication Required:

  • Requires a valid x-api-key header.

Cost:

  • Free Tier: 1 Credit per request.
  • Paid Tiers (Entry, High): 0 Credits (Unlimited).

Use it to help users select the correct city before making astrology calculations.

Example usage:

  • /api/v2/geo/search?q=par → Returns Paris (FR), Paris (US), Paraná, etc.
  • /api/v2/geo/search?q=london&country=GB → Returns only London, UK
  • /api/v2/geo/search?q=Jingzhou%2C%20Hubei → Returns Jingzhou in Hubei, China
  • /api/v2/geo/search?q=Hubei%20Jingzhou → Also returns Jingzhou in Hubei, China
  • /api/v2/geo/search?q=Jingzhou%20City%2C%20Hubei%20Province → Accepts optional administrative suffixes

Results are sorted by population (largest cities first).

Note: This is the new v2 endpoint. The v1 endpoint (/api/v1/geo/search) remains free without API key until February 3, 2026, after which it will be deprecated.

get/api/v2/geo/search

Request

  • Base URL: https://api.freeastroapi.com (the document declares no server; this is the origin it was published from)
  • URL: https://api.freeastroapi.com/api/v2/geo/search
  • Auth: none declared

Query parameters

qstring required

City name prefix with an optional state/province qualifier (e.g., 'Jingzhou, Hubei', 'Hubei Jingzhou', 'Jingzhou City, Hubei Province', or 'Jingzhou, Hubei, CN')

Example:Jingzhou City, Hubei Province
limitinteger

Maximum results to return (1-50)

countrystring nullable

Filter by ISO country code (e.g., 'US', 'FR')

Response

Successful Response

countinteger required

Changes

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