geodata

geodata

国、州、都市のデータ、最新の通貨レート、IP ジオロケーションを、1 つの API キーで利用できます。geodata は ApogeoAPI REST API の薄いクライアントです。API キーを用意するだけで、8 つのツールを使ってあらゆる検索に対応できます。国の詳細情報、ページ分割された国のカタログ、名前による検索、国に属する州や都市、国の通貨の現在の為替レート、IP アドレスの位置情報、そして国・州・都市の 3 つすべてを対象にした 1 つの検索ボックスを利用できます。

成功した呼び出しでは、上流の JSON が API から送信されたとおりに返されます。処理の過程で形を変えたり、名前を変更したり、要約したりすることはないため、クライアントに表示されるのはサービスから返された内容そのものです。

Configuration

2 つの環境変数でクライアントを制御します。

• APOGEOAPI_KEY（必須）— API キーです。すべてのリクエストで X-API-Key ヘッダーとして送信されます。設定されていない場合、すべてのツールは APOGEOAPI_KEY is not set で失敗し、リクエストは送信されません。
• APOGEOAPI_BASE_URL（任意）— API のベース URL です。デフォルトは https://api.apogeoapi.com です。

Tools

• 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 に対応する国、地域、都市、座標、タイムゾーン、EU 加盟状況を取得します。
• global_search — 1 つの 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 が返されます。

Endpoint provenance

4 つのリクエストパスは、ベンダーサイトの実行例で確認されています。

• GET /v1/countries/{code}（任意の ?base= 付き）
• GET /v1/countries
• GET /v1/countries/{country}/currency-rate
• GET /v1/ip/{ip}

残りの 4 つのパスは再構成したものとして明記しています。サイトに記載されたコレクションのパターンに沿っていますが、実行例では確認されていません。

• 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 パラメーター名は再構成したものです。

CLI

各ツールは、1 つの 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 server

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"}'

Development

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

License

MIT — Copyright (c) 2026 Rene Turcios