Countries

Look up, search, and validate ISO 3166-1 country codes. Covers all UN member states with names, regions, currencies, and subdivisions.

apicrate-lookup-country

Look up a single country by its ISO 3166-1 code. Accepts alpha-2, alpha-3, or numeric codes.

Credit cost: 1 credit per call.

Parameters

Parameter	Type	Required	Description
code	str	Yes	ISO 3166-1 code: alpha-2 (US), alpha-3 (USA), or numeric (840).

Example

Request:

{
  "name": "apicrate-lookup-country",
  "arguments": {
    "code": "US"
  }
}

Response:

{
  "alpha2": "US",
  "alpha3": "USA",
  "numeric": "840",
  "name": "United States",
  "official_name": "United States of America",
  "region": "Americas",
  "sub_region": "Northern America",
  "capital": "Washington, D.C.",
  "currencies": ["USD"],
  "languages": ["en"],
  "calling_codes": ["+1"]
}

Errors

• Country not found – the code does not match any ISO 3166-1 alpha-2, alpha-3, or numeric code.

apicrate-search-countries

Search and filter countries by region, sub-region, or free-text name query.

Credit cost: 3 credits per call. Returns up to 250 results.

Parameters

Parameter	Type	Required	Description
region	str	No	Filter by region (e.g. Europe, Americas, Asia).
sub_region	str	No	Filter by sub-region (e.g. Northern America, Western Europe).
query	str	No	Free-text search against country names (e.g. united).

Example

Filter by region – request:

{
  "name": "apicrate-search-countries",
  "arguments": {
    "region": "Europe"
  }
}

Response (truncated):

{
  "count": 44,
  "results": [
    {
      "alpha2": "DE",
      "name": "Germany",
      "region": "Europe",
      "sub_region": "Western Europe"
    },
    {
      "alpha2": "FR",
      "name": "France",
      "region": "Europe",
      "sub_region": "Western Europe"
    },
    {
      "alpha2": "PL",
      "name": "Poland",
      "region": "Europe",
      "sub_region": "Eastern Europe"
    }
  ]
}

Search by name – request:

{
  "name": "apicrate-search-countries",
  "arguments": {
    "query": "united"
  }
}

Response:

{
  "count": 3,
  "results": [
    {
      "alpha2": "AE",
      "name": "United Arab Emirates",
      "region": "Asia",
      "sub_region": "Western Asia"
    },
    {
      "alpha2": "GB",
      "name": "United Kingdom",
      "region": "Europe",
      "sub_region": "Northern Europe"
    },
    {
      "alpha2": "US",
      "name": "United States",
      "region": "Americas",
      "sub_region": "Northern America"
    }
  ]
}

Errors

No tool-specific errors. An empty results list is returned when no countries match the filters.

apicrate-validate-country-codes

Validate one or more country codes in a single call. Each code is checked against all ISO 3166-1 formats (alpha-2, alpha-3, numeric).

Credit cost: 1 credit per code. A request with 5 codes costs 5 credits. Maximum 50 codes per call.

Parameters

Parameter	Type	Required	Description
codes	list[str]	Yes	List of codes to validate. Maximum 50 items. Each code is matched against alpha-2, alpha-3, and numeric formats.

Example

Request:

{
  "name": "apicrate-validate-country-codes",
  "arguments": {
    "codes": ["US", "DEU", "ZZZ"]
  }
}

Response:

{
  "count": 3,
  "results": [
    {
      "code": "US",
      "valid": true,
      "alpha2": "US",
      "name": "United States"
    },
    {
      "code": "DEU",
      "valid": true,
      "alpha2": "DE",
      "name": "Germany"
    },
    {
      "code": "ZZZ",
      "valid": false,
      "alpha2": null,
      "name": null
    }
  ]
}

Errors

• Empty list – codes must contain at least one item.

• Over 50 limit – no more than 50 codes per request.