Converting between ISO country codes (alpha-2, alpha-3, numeric)

US, USA, and 840 are the same country in three ISO 3166-1 formats: alpha-2, alpha-3, and numeric. The one you have is rarely the one the next system wants.

Alpha-2 or alpha-3 in, everything out

/alpha/{code} takes either two- or three-letter codes and returns all of them, plus the name:

curl https://countries.dev/alpha/US     # works with USA too

{ "name": "United States of America", "alpha2Code": "US", "alpha3Code": "USA", "numericCode": "840" }

So converting alpha-2 → alpha-3 (or back) is a single call — read the field you need:

const c = await fetch("https://countries.dev/alpha/US").then((r) => r.json());
c.alpha3Code; // "USA"
c.numericCode; // "840"

Numeric or name in

Have the numeric code? Use the numeric endpoint (leading zeros optional):

curl https://countries.dev/numericcode/840

Have a name and need a code? /name/{name} does a substring match and returns the record with all three codes.

If you only want the codes back, trim the rest: ?fields=alpha2Code,alpha3Code,numericCode.

Lookup docs →