ApiToll

← Catalog

Country Data.

Comprehensive ISO country reference in one call. 250 countries, 12+ data points each. Tolerant resolver accepts ISO-2, ISO-3, or fuzzy name. $0.001 per call.

Endpoints
GET /v1/country/:iso2 strict ISO-2 lookup
GET /v1/country/resolve/:input flexible (ISO-2, ISO-3, name)
Price
0.001 USDC per successful call
Source
mledoze/countries snapshot
License
ODbL (Open Database License)
Refresh
Quarterly — ISO codes occasionally change
Coverage
250 countries, 12+ fields per country
Auth
None. x402 payment is the auth.

Try the sandbox →   Same response shape, test USDC on Base Sepolia. Get a test wallet drip.

What you get

JSON. Same shape on every call.

{
  "status": "success",
  "country": {
    "iso2":   "US",
    "iso3":   "USA",
    "name":   "United States",
    "official_name": "United States of America",
    "capital":   "Washington, D.C.",
    "region":    "Americas",
    "subregion": "North America",
    "currencies": [{"code":"USD","name":"United States dollar","symbol":"$"}],
    "languages":  [{"code":"eng","name":"English"}],
    "calling_codes": ["+1"],
    "timezones": ["UTC-12:00", "UTC-11:00", "UTC-10:00", ...],
    "population": 329484123,
    "area_km2":   9372610,
    "lat":        38, "lng": -97,
    "borders":    ["CAN","MEX"],
    "flag_emoji": "..."
  },
  "meta": { "source": "mledoze/countries snapshot", "source_license": "ODbL", "record_count": 250 }
}

Why pay

Public sources exist. Hosting them is the work.

  1. restcountries.com is rate-limited and frequently down.

    It's the obvious free alternative and it gets hammered. We snapshot the same canonical dataset and serve it from local SQLite. Sub-millisecond, never down.

  2. Maintaining your own snapshot is real work.

    ISO codes change — North Macedonia in 2019, eSwatini in 2018. We refresh quarterly and disclose the snapshot date in meta.last_updated.

  3. One call gives 12+ data points.

    Codes, capital, multi-currency, multi-language, calling codes, all timezones, area, population, lat/lng, borders, flag. Replaces five lookups across three sources.

Use cases

What agents do with this.

  1. Phone-number formatting.

    Resolve "what's the calling code for Senegal?" → +221. Pair with libphonenumber for input parsing.

  2. Pricing localization.

    "What currencies does Switzerland use?" → CHF, EUR. Multi-currency answer matters; this is not a 1:1 country-currency map.

  3. Address validation preflight.

    Confirm an ISO-2 code resolves to a real country before calling a paid address API. Cheap pre-filter.

  4. Compliance routing.

    Get the canonical ISO codes before sending to sanctions / KYC services. North Macedonia gets MK now, not formerly.

Honest framing

What it is not.

Good for: reference lookups, localization, pre-flight validation, anything where "the ISO answer" is the right answer.

Not good for:

  • Real-time political data (this is a snapshot, not a feed)
  • Disputed-territory rulings (we ship what mledoze ships)
  • Currency exchange rates — that's our FX service

The calling-code resolver currently returns the first country mapped to a root prefix (so +1 may resolve to a +1-area-code country other than the US). Strict ISO-2 lookup is unaffected.

Try it

Right now.

One line to see the 402 challenge (no wallet needed):

curl -i https://apitoll.io/v1/country/US
curl -i https://apitoll.io/v1/country/resolve/USA

When you're ready to actually pay, send a signed X-PAYMENT header (most agent SDKs do this for you). See the agent primer for full setup. Or hit the sandbox first.

Discovery

Pricing rationale

$0.001 per call. Reference data is high-frequency in agentic flows — agents look up countries dozens of times per session for localization. Cheap on purpose. We can raise once usage signals what the real value is.