Geocoding

AstroAPI provides a geocoding endpoint to search for places and get their coordinates. This is useful for converting location names to latitude/longitude values required by calculation endpoints.

Search for Places

Search for cities, towns, and other places by name:

curl -X GET "https://api.astroapi.cloud/api/geocoding/search?q=Amsterdam" \
  -H "X-Api-Key: your-api-key"

Query Parameters

Parameter	Required	Description
q	Yes	Search query (2-100 characters)
limit	No	Maximum results (1-10, default: 5)
lang	No	Language code (default: "en")

Response

{
  "data": [
    {
      "id": "node_123456",
      "name": "Amsterdam",
      "displayName": "Amsterdam, North Holland, Netherlands",
      "latitude": 52.3676,
      "longitude": 4.9041,
      "country": "Netherlands",
      "countryCode": "NL",
      "state": "North Holland",
      "city": "Amsterdam"
    }
  ]
}

Response Fields

Field	Description
id	Unique identifier (OpenStreetMap ID)
name	Primary place name
displayName	Full formatted name with region and country
latitude	Latitude coordinate
longitude	Longitude coordinate
country	Country name
countryCode	ISO 2-letter country code
state	State/province/region name
city	City name (if applicable)

Code Examples

JavaScript

async function searchPlace(query) {
  const response = await fetch(
    `https://api.astroapi.cloud/api/geocoding/search?q=${encodeURIComponent(query)}`,
    {
      headers: {
        "X-Api-Key": "your-api-key"
      }
    }
  );
  const { data } = await response.json();
  return data;
}

// Usage
const results = await searchPlace("London");
const { latitude, longitude } = results[0];
console.log(`London: ${latitude}, ${longitude}`);

Python

import requests

def search_place(query):
    response = requests.get(
        "https://api.astroapi.cloud/api/geocoding/search",
        params={"q": query},
        headers={"X-Api-Key": "your-api-key"}
    )
    return response.json()["data"]

# Usage
results = search_place("Paris")
place = results[0]
print(f"Paris: {place['latitude']}, {place['longitude']}")

Using with Natal Chart

Combine geocoding with natal chart calculation:

// Step 1: Search for birthplace
const places = await searchPlace("New York");
const birthplace = places[0];

// Step 2: Calculate natal chart
const response = await fetch("https://api.astroapi.cloud/api/calc/natal", {
  method: "POST",
  headers: {
    "X-Api-Key": "your-api-key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    datetime: "1990-06-15T14:30:00",
    latitude: birthplace.latitude,
    longitude: birthplace.longitude,
    timezone: "America/New_York"
  })
});

Language Support

The geocoding endpoint supports multiple languages for place names. Use the lang parameter:

# German
curl "https://api.astroapi.cloud/api/geocoding/search?q=Munich&lang=de"

# French
curl "https://api.astroapi.cloud/api/geocoding/search?q=Munich&lang=fr"

Supported language codes include: en, de, fr, es, it, nl, pt, ru, ja, zh, and more.

Caching

Geocoding results are cached for 24 hours to improve performance. The same search query will return cached results without hitting the upstream geocoding service.

Rate Limits

Geocoding requests count towards your API rate limits. See Rate Limits for details.