Back to Docs

City Search

City Search

City Search (Autocomplete)

Search cities, localities, and suburbs so users can select the correct location before making astrology calculations.

State or province filtering: Use a city-first query such as Jingzhou, Hubei, a province-first query such as Hubei Jingzhou, optional suffixes as in Jingzhou City, Hubei Province, or include the country as in Jingzhou, Hubei, CN. The province is returned in the state field.
Note: To ensure fast performance, broad queries (less than 4 characters, e.g., "San") are automatically limited to 5 results. Be specific (e.g., "San Francisco") for more results.
Indian localities: Geo V2 can return Indian cities, localities, and suburbs directly from the search query. The optional country parameter is only for narrowing ambiguous global matches.

Endpoint

GEThttps://api.freeastroapi.com/api/v2/geo/search

Requires an x-api-key header.

Live Geo V2 Test

Top 5 results update as you type.

Query Parameters

Parameter
q
Type
string
Required
Yes
Description
City name prefix with an optional state or province qualifier. Accepted forms include Jingzhou, Hubei; Hubei Jingzhou; Jingzhou City, Hubei Province; and Jingzhou, Hubei, CN. Minimum 2 characters.
Parameter
limit
Type
integer
Required
No
Description
Maximum results to return. Default: 10, Maximum: 50. Note: For search queries shorter than 4 characters, the limit is automatically capped at 5 for performance.
Parameter
country
Type
string
Required
No
Description
Optional ISO 3166-1 alpha-2 country filter for narrowing ambiguous global matches. Not required for Indian cities, localities, or suburbs.

Code Examples

# Search for cities starting with "paris"
curl -H "x-api-key: YOUR_API_KEY" "https://api.freeastroapi.com/api/v2/geo/search?q=paris&limit=5"

# Select a same-name city by state or province
curl -G -H "x-api-key: YOUR_API_KEY"   --data-urlencode "q=Jingzhou, Hubei"   --data-urlencode "limit=5"   "https://api.freeastroapi.com/api/v2/geo/search"

# The state or province can also come first
curl -G -H "x-api-key: YOUR_API_KEY"   --data-urlencode "q=Hubei Jingzhou"   --data-urlencode "limit=5"   "https://api.freeastroapi.com/api/v2/geo/search"

# Optional English administrative suffixes are accepted
curl -G -H "x-api-key: YOUR_API_KEY"   --data-urlencode "q=Jingzhou City, Hubei Province"   --data-urlencode "limit=5"   "https://api.freeastroapi.com/api/v2/geo/search"

# Search Indian localities and suburbs without a country filter
curl -H "x-api-key: YOUR_API_KEY" "https://api.freeastroapi.com/api/v2/geo/search?q=mulund&limit=5"

India Districts

Indian places include an additional district field when district data is available. This helps distinguish places with the same city or locality name, such as Vangaon in Palghar versus Aurangabad.

For non-Indian results, district is returned as null. Existing fields remain unchanged, so clients can continue reading name, country, state, coordinates, timezone, and population.

Existing unqualified searches such as Mumbai, Vangaon, or Mulund, with or without country=IN, keep their current behavior. Qualified queries such as Mumbai, Maharashtra and Maharashtra Mumbai narrow matches by state; GeoCity checks the complete input as a place name first to preserve existing multiword locality searches.

Response Fields

Field
results
Type
array
Description
List of matching cities
Field
results[].name
Type
string
Description
City name
Field
results[].country
Type
string
Description
ISO country code
Field
results[].state
Type
string | null
Description
State, province, region, or first-level administrative area when available
Field
results[].district
Type
string | null
Description
District for Indian places only. Non-Indian results return null.
Field
results[].lat
Type
float
Description
Latitude
Field
results[].lng
Type
float
Description
Longitude
Field
results[].timezone
Type
string
Description
IANA timezone identifier (e.g., 'Europe/Paris')
Field
results[].population
Type
integer
Description
City population (used for sorting)
Field
count
Type
integer
Description
Number of results returned

Sample Response

{
  "results": [
    {
      "name": "Vāngaon",
      "country": "IN",
      "state": "Maharashtra",
      "district": "Palghar",
      "lat": 19.87621,
      "lng": 72.76267,
      "timezone": "Asia/Kolkata",
      "population": 0
    },
    {
      "name": "Vangaon",
      "country": "IN",
      "state": "Maharashtra",
      "district": "Aurangabad",
      "lat": 20.56385,
      "lng": 75.36115,
      "timezone": "Asia/Kolkata",
      "population": 0
    }
  ],
  "count": 2
}

💡 Recommended Usage

Use this endpoint to build city autocomplete in your application:

  1. User starts typing a city name in your form
  2. After 2+ characters, call this endpoint with the input
  3. Display results as a dropdown for the user to select from
  4. When user selects a city, use the lat, lng, and timezone values in your astrology API calls

This ensures users always select a valid city that the API can resolve, avoiding coordinate lookup errors.

Next Steps

Natal Chart

Calculate a natal chart with city data

BaZi Chart

Calculate Chinese Four Pillars