letstool/http2country repository overview

⁠http2country

Lightweight HTTP gateway that looks up countries by ISO 3166-1 code through a JSON REST API.

Send a POST /api/v1/country request with an ISO2, ISO3, or numeric country code, get back structured JSON with 38 fields: identity, geography, languages, currencies, calling codes, TLDs, GDP, Gini, and a full legal framework (EU/EEA/Schengen, GDPR, VAT, OFAC sanctions, FATF status, and more).

The database is built automatically from a gzipped CSV served by the letstool CDN and refreshed every 24 hours. No MaxMind license, no manual setup.

The binary embeds a web UI (dark/light mode, 15 languages, RTL support) and an OpenAPI 3.1 spec — no external files, no runtime dependencies.

⁠Quick start

docker run -p 8080:8080 letstool/http2country:latest

Open http://localhost:8080⁠ to use the web UI, or query the API directly:

# Lookup by ISO2
curl -s -X POST http://localhost:8080/api/v1/country \
  -H "Content-Type: application/json" \
  -d '{"country":"FR"}' | jq

# Lookup by ISO3
curl -s -X POST http://localhost:8080/api/v1/country \
  -H "Content-Type: application/json" \
  -d '{"country":"DEU"}' | jq

# Lookup by numeric code
curl -s -X POST http://localhost:8080/api/v1/country \
  -H "Content-Type: application/json" \
  -d '{"country":"392"}' | jq

Example response:

{
  "status": "SUCCESS",
  "answer": {
    "iso2": "FR",
    "iso3": "FRA",
    "numeric_code": "250",
    "name_common": "France",
    "name_official": "French Republic",
    "flag_emoji": "🇫🇷",
    "region": "Europe",
    "subregion": "Western Europe",
    "capital": "Paris",
    "area_sq_km": 551695.0,
    "landlocked": false,
    "borders": ["AND", "BEL", "DEU", "ITA", "LUX", "MCO", "ESP", "CHE"],
    "language_codes": ["fr"],
    "currency_codes": ["EUR"],
    "calling_codes": ["+33"],
    "gdp_per_capita_usd": 43658.98,
    "legal_eu": true,
    "legal_schengen": true,
    "legal_gdpr": true,
    "legal_vat_rate": 20.0,
    "legal_vat_name": "TVA",
    "legal_ofac": false,
    "legal_fatf": ""
  }
}

⁠Configuration

CLI flags take priority over environment variables.

Proxy is supported via the standard HTTPS_PROXY, HTTP_PROXY, and NO_PROXY environment variables (same behaviour as curl).

docker run -p 8080:8080 \
  -v ./db:/data:rw \
  -e LISTEN_ADDR=0.0.0.0:8080 \
  letstool/http2country:latest

⁠Peer sync mode

Set COUNTRY_DB_URL to another running http2country instance to download the database directly from its /db/country endpoint instead of fetching from the CDN. Useful for air-gapped environments or clusters where only one node hits the CDN.

docker run -p 8080:8080 \
  -e COUNTRY_DB_URL=http://upstream-host:8080 \
  -v ./db:/data:rw \
  letstool/http2country:latest

⁠Persistent storage

Mount a volume to /data to cache the database across container restarts:

docker run -p 8080:8080 \
  -e LISTEN_ADDR=0.0.0.0:8080 \
  -v ./db:/data:rw \
  letstool/http2country:latest

On restart, if the cached country.mmdb is recent enough, it is reloaded immediately without refetching.

⁠Repo

https://github.com/letstool/http2country⁠

⁠License

This project is licensed under the Apache License, Version 2.0⁠.

Copyright (c) 2026 letstool.net

⁠See also

Country data aggregated from public sources including the ISO 3166 Maintenance Agency, World Bank Open Data, UN membership records, FATF public lists, and OFAC/EU sanctions registries. This project is not affiliated with or endorsed by any of these organisations.