地理位置与时区API文档

提供城市信息搜索、国家/省份/城市层级获取以及指定日期、经纬度的时区查询服务。支持全球城市地理信息查询。

接口说明

本API提供城市信息搜索、国家/省份/城市层级获取以及指定日期、经纬度的时区查询服务。

基本信息

  • 基础URL： https://chart.12sign.top
  • Content-Type：： application/json (所有请求的响应类型)

主要接口列表

  • 城市搜索： GET /api/search
  • 获取国家列表：： GET /api/countries
  • 根据ID获取城市信息：： GET /api/city/<city_id>
  • 获取省份/州列表：： GET /api/states/<country_id>
  • 获取城市列表：： GET /api/cities/<state_id>
  • 获取时区信息：： GET /api/timezone

API 端点详情

1. 城市搜索

  • 接口URL： /api/search
  • 请求方式： GET
  • 描述：： 根据城市名称（英文或中文）模糊搜索城市信息。

请求参数

参数名 类型 必选 说明
name string 是 要搜索的城市名称（支持英文或中文）。例如："beijing" 或 "北京"。

返回参数

参数名 类型 说明
[root] array of object 匹配的城市列表。每个对象包含城市详情及国家/省份名称。
id integer 城市唯一ID。
name string 城市英文名称。
cnname string 城市中文名称（如果存在）。
latitude number 城市纬度。
longitude number 城市经度。
timezone string 城市默认时区名称（IANA Time Zone Database 格式，如 "Asia/Shanghai"）。
state_name string 所属省份/州名称。
country_name string 所属国家名称。
... 其他城市字段

请求示例

GET /api/search?name=beijing
GET /api/search?name=北京

返回示例

[
    {
        "id": 12345,
        "name": "Beijing",
        "cnname": "北京",
        "latitude": 39.9042,
        "longitude": 116.4074,
        "timezone": "Asia/Shanghai",
        "state_name": "Beijing",
        "country_name": "China",
        "level": 3,
        "parent": 98765
    },
    {
        "id": 54321,
        "name": "Beijing",
        "cnname": null,
        "latitude": 34.5678,
        "longitude": -87.6543,
        "timezone": "America/Chicago",
        "state_name": "Alabama",
        "country_name": "United States",
        "level": 3,
        "parent": 67890
    }
]

2. 获取国家列表

  • 接口URL： /api/countries
  • 请求方式： GET
  • 描述：： 获取所有国家列表。中国 (China) 会优先排序。

请求参数

无

返回参数

参数名 类型 说明
[root] array of object 国家列表。
id integer 国家ID。
name string 国家名称。

请求示例

GET /api/countries

返回示例

[
    {
        "id": 1,
        "name": "China"
    },
    {
        "id": 2,
        "name": "United States"
    },
    {
        "id": 3,
        "name": "Afghanistan"
    },
    ...
]

3. 根据ID获取城市信息

  • 接口URL： /api/city/<city_id>
  • 请求方式：： GET
  • 描述：： 根据城市唯一ID获取其详细信息。

URL 参数

参数名 类型 说明
city_id integer 要查询的城市ID。

返回参数

参数名 类型 说明
id integer 城市唯一ID。
name string 城市英文名称。
cnname string 城市中文名称（如果存在）。
latitude number 城市纬度。
longitude number 城市经度。
timezone string 城市默认时区名称（IANA Time Zone Database 格式）。
state_name string 所属省份/州名称。
country_name string 所属国家名称。
... 其他城市字段

请求示例

GET /api/city/12345

成功返回示例

{
    "id": 12345,
    "name": "Beijing",
    "cnname": "北京",
    "latitude": 39.9042,
    "longitude": 116.4074,
    "timezone": "Asia/Shanghai",
    "state_name": "Beijing",
    "country_name": "China",
    "level": 3,
    "parent": 98765
}

错误返回示例 (404 Not Found)

{
    "success": false,
    "message": "城市不存在"
}

4. 获取省份/州列表

  • 接口URL： /api/states/<country_id>
  • 请求方式：： GET
  • 描述：： 根据国家ID获取其下属的省份/州列表。

URL 参数

参数名 类型 说明
country_id integer 国家ID。

返回参数

参数名 类型 说明
[root] array of object 省份/州列表。
id integer 省份/州ID。
name string 省份/州名称。

请求示例

GET /api/states/1

返回示例

[
    {
        "id": 98765,
        "name": "Beijing"
    },
    {
        "id": 87654,
        "name": "Shanghai"
    },
    ...
]

5. 获取城市列表

  • 接口URL：： /api/cities/<state_id>
  • 请求方式：： GET
  • 描述：： 根据省份/州ID获取其下属的城市列表。

URL 参数

参数名 类型 说明
state_id integer 省份/州ID。

返回参数

参数名 类型 说明
[root] array of object 城市列表。
id integer 城市ID。
name string 城市名称。
latitude number 城市纬度。
longitude number 城市经度。
timezone string 城市默认时区名称（IANA Time Zone Database 格式）。

请求示例

GET /api/cities/98765

返回示例

[
    {
        "id": 12345,
        "name": "Beijing",
        "latitude": 39.9042,
        "longitude": 116.4074,
        "timezone": "Asia/Shanghai"
    },
    {
        "id": 12346,
        "name": "Changping",
        "latitude": 40.2173,
        "longitude": 116.2307,
        "timezone": "Asia/Shanghai"
    },
    ...
]

6. 获取时区信息

  • 接口URL： /api/timezone
  • 请求方式：： GET
  • 描述：： 根据指定的日期和经纬度获取该时刻该地点的时区信息。

请求参数

参数名 类型 必选 说明
year integer 是 年份。
month integer 是 月份 (1-12)。
day integer 是 日期 (1-31)。
lat number 是 地点纬度。
lon number 是 地点经度。

返回参数

参数名 类型 说明
timezone_name string 时区名称 (IANA Time Zone Database 格式，例如 "Asia/Shanghai")。
utc_offset string 该日期该时区相对于UTC的偏移量，格式为 "+HH:MM" 或 "-HH:MM"。
is_dst boolean 在该日期是否处于夏令时。
error string (错误时存在) 错误信息。

请求示例

GET /api/timezone?year=2024&month=3&day=15&lat=39.9042&lon=116.4074

成功返回示例

{
    "timezone_name": "Asia/Shanghai",
    "utc_offset": "+08:00",
    "is_dst": false
}

错误返回示例 (400 Bad Request)

{
    "error": "Invalid parameters"
}
{
    "error": "无法获取时区信息"
}

Python测试代码示例

import requests
import json

BASE_URL = "https://chart.12sign.top/api"

def test_search_city():
    print("--- 测试 /api/search 接口 ---")
    response = requests.get(f"{BASE_URL}/search?name=beijing")
    print(f"英文搜索 'beijing' 状态码: {response.status_code}")
    print(f"响应: {json.dumps(response.json(), ensure_ascii=False, indent=2)[:500]}...")
    
    response = requests.get(f"{BASE_URL}/search?name=北京")
    print(f"中文搜索 '北京' 状态码: {response.status_code}")
    print(f"响应: {json.dumps(response.json(), ensure_ascii=False, indent=2)[:500]}...")

def test_get_countries():
    print("\n--- 测试 /api/countries 接口 ---")
    response = requests.get(f"{BASE_URL}/countries")
    print(f"获取国家列表状态码: {response.status_code}")
    print(f"响应: {json.dumps(response.json(), ensure_ascii=False, indent=2)[:500]}...")

def test_get_city_by_id():
    print("\n--- 测试 /api/city/ 接口 ---")
    # 假设北京的ID是12345 (实际ID需从/api/search结果中获取)
    city_id_to_test = 12345 # 替换为实际存在的城市ID
    response = requests.get(f"{BASE_URL}/city/{city_id_to_test}")
    print(f"获取城市ID {city_id_to_test} 状态码: {response.status_code}")
    if response.status_code == 200:
        print(f"响应: {json.dumps(response.json(), ensure_ascii=False, indent=2)}")
    else:
        print(f"错误响应: {response.text}")

def test_get_states():
    print("\n--- 测试 /api/states/ 接口 ---")
    # 假设中国的ID是1 (实际ID需从/api/countries结果中获取)
    country_id_to_test = 1 # 替换为实际存在的国家ID
    response = requests.get(f"{BASE_URL}/states/{country_id_to_test}")
    print(f"获取国家ID {country_id_to_test} 的省份列表状态码: {response.status_code}")
    print(f"响应: {json.dumps(response.json(), ensure_ascii=False, indent=2)[:500]}...")

def test_get_cities():
    print("\n--- 测试 /api/cities/ 接口 ---")
    # 假设北京省的ID是98765 (实际ID需从/api/states结果中获取)
    state_id_to_test = 98765 # 替换为实际存在的省份ID
    response = requests.get(f"{BASE_URL}/cities/{state_id_to_test}")
    print(f"获取省份ID {state_id_to_test} 的城市列表状态码: {response.status_code}")
    print(f"响应: {json.dumps(response.json(), ensure_ascii=False, indent=2)[:500]}...")

def test_get_timezone():
    print("\n--- 测试 /api/timezone 接口 ---")
    params = {
        "year": 2024,
        "month": 3,
        "day": 15,
        "lat": 39.9042,
        "lon": 116.4074
    }
    response = requests.get(f"{BASE_URL}/timezone", params=params)
    print(f"获取时区信息状态码: {response.status_code}")
    print(f"响应: {json.dumps(response.json(), ensure_ascii=False, indent=2)}")

if __name__ == "__main__":
    test_search_city()
    test_get_countries()
    test_get_city_by_id()
    test_get_states()
    test_get_cities()
    test_get_timezone()

注意事项

  • 经纬度使用小数格式，东经北纬为正，西经南纬为负。
  • /api/search 接口支持中英文城市名称模糊搜索。
  • /api/countries 接口会将 "China" 优先排序。
  • 城市/省份/国家的ID是唯一标识符，应通过层级接口（如 /api/countries, /api/states）或搜索接口获取。
  • /api/timezone 接口需要精确的日期和经纬度信息来计算时区。该接口提供时区查询功能。
  • API 错误通常通过HTTP状态码（如 400, 404, 500）和JSON格式的错误信息返回。