Геокодирование

AstroAPI предоставляет эндпоинт геокодирования для поиска мест и получения их координат. Это полезно для преобразования названий мест в значения широты и долготы, необходимые для эндпоинтов расчётов.

Поиск мест

Поиск городов, посёлков и других мест по названию:

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

Параметры запроса

Параметр	Обязателен	Описание
q	Да	Поисковый запрос (2–100 символов)
limit	Нет	Максимальное количество результатов (1–10, по умолчанию: 5)
lang	Нет	Код языка (по умолчанию: "en")

Ответ

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

Поля ответа

Поле	Описание
id	Уникальный идентификатор (ID OpenStreetMap)
name	Основное название места
displayName	Полное форматированное название с регионом и страной
latitude	Координата широты
longitude	Координата долготы
country	Название страны
countryCode	Двухбуквенный код страны ISO
state	Название штата/провинции/региона
city	Название города (если применимо)

Примеры кода

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

// Использование
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"]

# Использование
results = search_place("Paris")
place = results[0]
print(f"Paris: {place['latitude']}, {place['longitude']}")

Использование с натальной картой

Совместите геокодирование с расчётом натальной карты:

// Шаг 1: Поиск места рождения
const places = await searchPlace("New York");
const birthplace = places[0];

// Шаг 2: Расчёт натальной карты
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"
  })
});

Поддержка языков

Эндпоинт геокодирования поддерживает несколько языков для названий мест. Используйте параметр lang:

# Немецкий
curl "https://api.astroapi.cloud/api/geocoding/search?q=Munich&lang=de"

# Французский
curl "https://api.astroapi.cloud/api/geocoding/search?q=Munich&lang=fr"

Поддерживаемые коды языков: en, de, fr, es, it, nl, pt, ru, ja, zh и другие.

Кэширование

Результаты геокодирования кэшируются на 24 часа для повышения производительности. Один и тот же поисковый запрос возвращает кэшированные результаты без обращения к вышестоящему сервису геокодирования.

Ограничения запросов

Запросы геокодирования учитываются в ваших ограничениях запросов к API. Подробнее см. в разделе Ограничения запросов.