如何在 GeoCity 中按州或省份搜索城市

多个城市可能使用相同的名称。例如，搜索 Jingzhou 时，可能会返回位于 Hubei、Anhui、Guangdong 和 Hebei 的地点。GeoCity 支持两种处理方式：

• 搜索 Jingzhou，返回所有匹配地点，再让用户选择。
• 搜索 Jingzhou, Hubei 或 Hubei Jingzhou，只返回 Hubei 的匹配结果。

无论使用哪种方式，省份都会在响应的 state 字段中返回。 地点选项可以显示为 name, state, country。

state 字段表示什么

state 是一级行政区的通用响应字段：

对于印度地点，响应还可能包含 district。对于中国城市，district 通常为 null，省份则通过 state 返回。

1. 使用可选的州或省份搜索

调用 GET /api/v2/geo/search。可以把城市写在前面并用逗号分隔，也可以把可识别的州或省份写在前面：

curl --get "https://api.freeastroapi.com/api/v2/geo/search" \
  -H "x-api-key: $FREE_ASTRO_API_KEY" \
  --data-urlencode "q=Jingzhou, Hubei" \
  --data-urlencode "limit=10"

支持以下写法：

省份在前的写法适用于可识别的行政区，并非只支持 Hubei。例如，Sichuan Chengdu、Guangdong Shenzhen 和 Zhejiang Hangzhou 都使用同一套逻辑。也可以添加可选的英文行政区后缀，例如 Jingzhou City, Hubei Province 和 Hubei Province Jingzhou City。GeoCity 会先把完整文本作为现有城市或地点名称进行搜索；只有没有结果时，才会移除可选后缀，或把开头的词重新解释为州或省份，因此现有的多词地点搜索不会受到影响。你也可以继续使用可选的两位 country 查询参数，例如 country=CN。

API key 必须保存在服务器端。不要在浏览器 JavaScript 或公开环境变量中暴露它。

2. 从 state 读取省份

湖北省的结果包含以下数据：

{
  "name": "Jingzhou",
  "country": "CN",
  "state": "Hubei",
  "district": null,
  "lat": 30.35028,
  "lng": 112.19028,
  "timezone": "Asia/Shanghai",
  "population": 1052282
}

字段名必须保持为 state。不要寻找单独的 province 字段。

3. 生成界面上显示的地点名称

使用 name、state 和 country 生成主要标签：

function formatLocation(result) {
  return [result.name, result.state, result.country]
    .filter(Boolean)
    .join(", ");
}

如果搜索未限定省份的 Jingzhou，用户将看到：

Jingzhou, Hubei, CN
Jingzhou, Anhui, CN
Jingzhou, Guangdong, CN
Jingzhou, Hebei, CN

.filter(Boolean) 会忽略缺失值，避免出现多余的逗号。

4. 显示自动补全结果列表

下面的 React 示例与 GeoCity 文档中的地点显示方式一致：

function GeoResults({ results, onSelect }) {
  return (
    <div className="geo-results">
      {results.map((result) => (
        <button
          key={`${result.lat}-${result.lng}`}
          type="button"
          onClick={() => onSelect(result)}
          className="geo-result"
        >
          <strong>
            {[result.name, result.state, result.country]
              .filter(Boolean)
              .join(", ")}
          </strong>

          <span>
            {result.lat}, {result.lng} · {result.timezone}
          </span>
        </button>
      ))}
    </div>
  );
}

城市可能拥有相同的 name、state，甚至 country，因此 React key 建议使用经纬度。

5. 在可用时显示印度地区

印度地点可能同时包含 state 和 district：

{
  "name": "Vangaon",
  "country": "IN",
  "state": "Maharashtra",
  "district": "Palghar",
  "lat": 19.8814722,
  "lng": 72.7624167,
  "timezone": "Asia/Kolkata"
}

如果需要区分具体地区，可以使用更详细的格式化函数：

function formatDetailedLocation(result) {
  return [
    result.name,
    result.district,
    result.state,
    result.country
  ]
    .filter(Boolean)
    .join(", ");
}

该函数会返回 Vangaon, Palghar, Maharashtra, IN。

现有的印度城市和地点搜索行为保持不变。Mumbai、Vangaon 或 Mulund 等查询，无论是否带有 country=IN，都会保持原有的匹配和排序。使用 Mumbai, Maharashtra 或 Maharashtra Mumbai 这样的邦限定查询时，GeoCity 也会先检查完整输入是否为地点名称，之后才按 state 缩小结果范围。

6. 保存完整的选中结果，而不只是城市名称

用户选择 Jingzhou, Hubei, CN 后，应保存完整的结果对象。在后续占星请求中使用其中的 lat、lng 和 timezone。经纬度可以消除同名城市歧义，时区则为依赖日期和时间的计算提供必要的位置上下文。

如果用户已经知道省份，请在 q 中发送 Jingzhou, Hubei 或 Hubei Jingzhou。如果不知道，则搜索 Jingzhou，显示每个选项中返回的 state，再让用户选择。

推荐的用户流程

1. 用户输入 Jingzhou, Hubei 或 Hubei Jingzhou。
2. 服务器调用 GET /api/v2/geo/search。
3. GeoCity 识别省份限定条件并筛选匹配结果。
4. 界面读取结果中的 state。
5. 选项显示为 name, state, country。
6. 用户选择 Jingzhou, Hubei, CN。
7. 应用保存并使用所选结果的 lat、lng 和 timezone。

你可以在下方直接试用 GeoCity V2 城市搜索，也可以打开完整的城市搜索文档查看请求参数和示例。