geodata

geodata

国家、州和城市数据、实时汇率及 IP 地理位置查询，只需一个 API 密钥。geodata 是 ApogeoAPI REST API 的轻量客户端：你只需提供 API 密钥，八个 工具即可覆盖所有查询场景——查询单个国家的完整详情、分页浏览国家目录、按名称搜索、 查询某个国家下的州和城市、查询某个国家货币的当前汇率、查询 IP 地址的地理位置，以及一个涵盖所有三个层级的搜索框。

每次成功调用都会原样返回上游 JSON， 与 API 返回的内容完全一致。传递过程中不会重塑、重命名或汇总数据，因此客户端看到的就是服务返回的内容。

配置

两个环境变量用于控制客户端：

• APOGEOAPI_KEY（必需）——你的 API 密钥，每次请求都会通过 X-API-Key 请求头发送。未设置时， 所有工具都会报错 APOGEOAPI_KEY is not set，且不会发出请求。
• APOGEOAPI_BASE_URL（可选）——API 基础 URL。默认值 为 https://api.apogeoapi.com。

工具

• get_country ——按 ISO2/ISO3 code 获取完整国家数据： 名称、首都、地区、人口、货币、实时 USD 汇率、时区和电话区号。可选参数 base （例如 EUR）可更改汇率的货币基准。
• list_countries ——分页浏览全部 250 多个国家的目录。存在时，可选参数 page、limit 和 base 会作为查询参数发送。
• search_countries ——搜索名称与部分 query 匹配的国家。
• get_states ——获取指定 country 代码对应的所有州／省。
• get_cities ——通过数字 state_id 获取某个州的所有城市。
• get_currency_rate ——获取某个 country 货币的实时 USD 汇率（每 4 小时更新一次），可选参数为 base。
• geolocate_ip ——查询 IPv4／IPv6 ip 的国家、地区、城市、坐标、时区和欧盟成员资格。
• global_search ——通过一个 query 同时搜索国家、州和城市。

验证失败时会在发出请求前返回具体错误消息：code must be a non-empty string、 country must be a non-empty string、 query must be a non-empty string、 ip must be a non-empty string 或 state_id must be a positive integer。上游返回非 2xx 响应时会报错 apogeoapi error: HTTP <status>； API 无法访问时会报错 apogeoapi unreachable。

端点来源

四个请求路径由供应商网站上的操作示例明确指定：

• GET /v1/countries/{code}（可选 ?base=）
• GET /v1/countries
• GET /v1/countries/{country}/currency-rate
• GET /v1/ip/{ip}

其余四个路径为重构路径，并标注为此类：它们遵循网站记录的集合模式，但没有操作示例明确指定。

• GET /v1/countries?search=<query> ——重构路径 （供 search_countries 使用）
• GET /v1/countries/{country}/states ——重构路径 （供 get_states 使用）
• GET /v1/states/{state_id}/cities ——重构路径 （供 get_cities 使用）
• GET /v1/search?q=<query> ——重构路径 （供 global_search 使用）

对于 list_countries，集合端点及其查询参数格式有明确依据，而 page／limit／base 参数名称则为重构内容。

命令行

每个工具都是一个子命令，接受一个 JSON 参数字符串：

export APOGEOAPI_KEY="<your key>"
npx @reneturcios/geodata get_country '{"code":"US"}'
npx @reneturcios/geodata get_country '{"code":"FR","base":"EUR"}'
npx @reneturcios/geodata list_countries '{"page":1,"limit":50}'
npx @reneturcios/geodata search_countries '{"query":"united"}'
npx @reneturcios/geodata get_states '{"country":"US"}'
npx @reneturcios/geodata get_cities '{"state_id":42}'
npx @reneturcios/geodata get_currency_rate '{"country":"DE"}'
npx @reneturcios/geodata geolocate_ip '{"ip":"8.8.8.8"}'
npx @reneturcios/geodata global_search '{"query":"paris"}'
npx @reneturcios/geodata --version

输出为工具的结果文本（成功时为上游 JSON）。退出代码：成功时为 0，运行时错误（包括验证错误、缺少密钥或上游错误）时为 1，用法错误时为 2。

MCP 服务

npx -y @reneturcios/geodata mcp

MCP 客户端配置（通过客户端的环境变量提供密钥）：

{
  "mcpServers": {
    "geodata": {
      "command": "npx",
      "args": ["-y", "@reneturcios/geodata", "mcp"],
      "env": {
        "APOGEOAPI_KEY": "<your key>"
      }
    }
  }
}

Docker

docker run -i -e APOGEOAPI_KEY="<your key>" ghcr.io/cloudcorprecords/geodata
docker run --rm -e APOGEOAPI_KEY="<your key>" ghcr.io/cloudcorprecords/geodata get_country '{"code":"US"}'

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (fake fetch only, no network)
npm run dev     # run the CLI from source

许可证

MIT ——版权所有 (c) 2026 Rene Turcios