Geocoding

AstroAPI fornisce un endpoint di geocoding per cercare luoghi e ottenere le loro coordinate. Questo è utile per convertire i nomi dei luoghi in valori di latitudine/longitudine richiesti dagli endpoint di calcolo.

Ricerca di Luoghi

Cerca città, paesi e altri luoghi per nome:

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

Parametri della Query

Parametro	Obbligatorio	Descrizione
q	Sì	Query di ricerca (2-100 caratteri)
limit	No	Numero massimo di risultati (1-10, predefinito: 5)
lang	No	Codice lingua (predefinito: "en")

Risposta

{
  "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"
    }
  ]
}

Campi della Risposta

Campo	Descrizione
id	Identificatore univoco (ID OpenStreetMap)
name	Nome principale del luogo
displayName	Nome completo formattato con regione e paese
latitude	Coordinata di latitudine
longitude	Coordinata di longitudine
country	Nome del paese
countryCode	Codice paese ISO a 2 lettere
state	Nome dello stato/provincia/regione
city	Nome della città (se applicabile)

Esempi di Codice

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;
}

// Utilizzo
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"]

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

Utilizzo con il Tema Natale

Combina il geocoding con il calcolo del tema natale:

// Passo 1: Cerca il luogo di nascita
const places = await searchPlace("New York");
const birthplace = places[0];

// Passo 2: Calcola il tema natale
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"
  })
});

Supporto Linguistico

L'endpoint di geocoding supporta più lingue per i nomi dei luoghi. Usa il parametro lang:

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

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

I codici lingua supportati includono: en, de, fr, es, it, nl, pt, ru, ja, zh e altri.

Caching

I risultati del geocoding vengono memorizzati nella cache per 24 ore per migliorare le prestazioni. La stessa query di ricerca restituirà risultati memorizzati nella cache senza interrogare il servizio di geocoding upstream.

Limiti di Utilizzo

Le richieste di geocoding vengono conteggiate verso i tuoi limiti di utilizzo API. Consulta Limiti di Utilizzo per i dettagli.