地理编码

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	唯一标识符（OpenStreetMap ID）
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;
}

// 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']}")

与本命盘结合使用

将地理编码与本命盘计算结合使用：

// 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"
  })
});

语言支持

地理编码端点支持多种语言的地名显示。使用 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 速率限制。详情请参阅速率限制。