# 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:

```bash
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

```bash
npx -y @reneturcios/geodata mcp
```

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

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

## Docker

```bash
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

```bash
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