io.github.CloudCorpRecords/geodata

geodata

Country, state and city data, live currency rates and IP geolocation, behind one API key. geodata is a thin client for the ApogeoAPI REST API: you bring an API key, and eight tools cover the whole lookup surface — a single country in full detail, the paginated country catalogue, name search, the states and cities underneath a country, the current exchange rate for a country's currency, where an IP address lives, and one search box that spans all three levels.

Every successful call returns the upstream JSON exactly as the API sent it. Nothing is reshaped, renamed or summarised on the way through, so what your client sees is what the service returned.

Configuration

Two environment variables control the client:

• APOGEOAPI_KEY (required) — your API key, sent on every request as the X-API-Key header. When it is not set, every tool fails with APOGEOAPI_KEY is not set and no request is made.
• APOGEOAPI_BASE_URL (optional) — API base URL. Defaults to https://api.apogeoapi.com.

Tools

• get_country — full country data by ISO2/ISO3 code: name, capital, region, population, currency, live USD rate, timezones and phone code. An optional base (for example EUR) changes the currency base for rates.
• list_countries — the paginated catalogue of all 250+ countries. Optional page, limit and base are sent as query parameters when present.
• search_countries — countries matching a partial query name.
• get_states — all states/provinces for a country code.
• get_cities — all cities for a state, addressed by its numeric state_id.
• get_currency_rate — the live USD exchange rate for a country's currency (updated every 4 hours), with an optional base.
• geolocate_ip — country, region, city, coordinates, timezone and EU membership for an IPv4/IPv6 ip.
• global_search — one query searched across countries, states and cities at once.

Validation fails before any request with a specific message: 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, or state_id must be a positive integer. An upstream non-2xx reply fails with apogeoapi error: HTTP <status> and an unreachable API with apogeoapi unreachable.

Endpoint provenance

Four request paths are pinned by the vendor site's worked examples:

• GET /v1/countries/{code} (with optional ?base=)
• GET /v1/countries
• GET /v1/countries/{country}/currency-rate
• GET /v1/ip/{ip}

The remaining four paths are reconstructions, labelled as such: they follow the site's documented collection pattern but are not pinned by a worked example.

• GET /v1/countries?search=<query> — reconstruction (used by search_countries)
• GET /v1/countries/{country}/states — reconstruction (used by get_states)
• GET /v1/states/{state_id}/cities — reconstruction (used by get_cities)
• GET /v1/search?q=<query> — reconstruction (used by global_search)

For list_countries, the collection endpoint and its query style are pinned, while the page / limit / base parameter names are a reconstruction.

CLI

Each tool is a subcommand taking one JSON argument string:

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

Output is the tool's result text (the upstream JSON on success). Exit codes: 0 on success, 1 on a runtime error (including a validation, missing-key or upstream failure), 2 on a usage error.

MCP server

npx -y @reneturcios/geodata mcp

MCP client config (provide the key through the client's environment):

{
  "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