City Search

City Search (Autocomplete)

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

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

Search query

Top 5 results update as you type.

Query Parameters

Parameter	Type	Required	Description
q	string	Yes	Search query (city name prefix). Minimum 2 characters.
limit	integer	No	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.
country	string	No	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"

# 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.

Response Fields

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

User starts typing a city name in your form
After 2+ characters, call this endpoint with the input
Display results as a dropdown for the user to select from
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