City Search

City Search (Autocomplete)

Search for cities by name prefix to build autocomplete functionality. Perfect for helping users select the correct city before making astrology calculations.

Free Endpoint

This endpoint is completely free and does not require an API key. Use it to improve your user experience without using API credits.

Endpoint

GEThttps://astro-api-1qnc.onrender.com/api/v1/geo/search

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.
country	string	No	Filter by ISO 3166-1 alpha-2 country code (e.g., 'US', 'FR', 'GB').

Code Examples

# Search for cities starting with "paris"
curl "https://astro-api-1qnc.onrender.com/api/v1/geo/search?q=paris&limit=5"

# Filter by country code
curl "https://astro-api-1qnc.onrender.com/api/v1/geo/search?q=london&country=GB&limit=3"

Response Fields

Field	Type	Description
results	array	List of matching cities
results[].name	string	City name
results[].country	string	ISO country code
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": "Paris",
      "country": "FR",
      "lat": 48.85341,
      "lng": 2.3488,
      "timezone": "Europe/Paris",
      "population": 2138551
    },
    {
      "name": "Paris",
      "country": "US",
      "lat": 33.66094,
      "lng": -95.55551,
      "timezone": "America/Chicago",
      "population": 24782
    }
  ],
  "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