471K+
Login
Start building
Dashboard
471K+
Dashboard
  1. Home
  2. Glossary
  3. Country codes

Country Codes Explained: ISO 3166-1 Alpha-2, Alpha-3 and Numeric Codes (Full 2026 List)

This guide covers ISO 3166-1, the country codes used in software. Telephone calling codes are a different standard and have their own guide.

Updated Standard: ISO 3166-1 12 min read

Quick answer

A country code is a short, standardised identifier for a country, territory or area of geographical interest. In software, “country code” almost always means ISO 3166-1, which assigns every entry three codes: alpha-2 (two letters, US, GB, IN), alpha-3 (three letters, USA, GBR, IND) and numeric-3 (three digits, 840, 826, 356). ISO 3166-1 currently covers 249 countries, territories and areas, and alpha-2 is the most widely used form: it powers country top-level domains, locale identifiers, currency codes, shipping labels and API responses. Telephone country codes such as +1, +44 and +91 are a different standard  — ITU-T E.164 — and are not part of ISO 3166.

#Key takeaways

  • ISO 3166-1 is the country code standard used in software. It defines three parallel code sets, alpha-2, alpha-3 and numeric-3, for the same 249 countries, territories and areas.
  • Alpha-2 is the default in APIs, databases, ccTLDs (.de, .in), locale tags (en-US, pt-BR) and ISO 4217 currency codes (USD = US + D). Use it unless you have a specific reason not to.
  • Alpha-3 is for humans, numeric-3 is for machines. Alpha-3 (DEU, IND) reads better in reports and passports; numeric-3 (276, 356) is script-independent and matches the UN Statistics Division M49 codes, so it survives transliteration and renaming.
  • Calling codes are not ISO codes. +44, +91 and +1 come from ITU-T E.164 and do not map one-to-one to countries: 25 countries and territories share +1 under the North American Numbering Plan, Russia and Kazakhstan share +7, and +672 covers four separate ISO codes (CC, CX, HM, NF).
  • The UK’s official alpha-2 code is GB, not UK. UK is only “exceptionally reserved”. The domain .uk is the famous exception where the ccTLD does not match the ISO code.
  • Some codes are reserved, not assigned. EU, UK and AC are exceptionally reserved; AA, QM to QZ, XA to XZ and ZZ are user-assigned and safe for private, internal values.
  • Country codes change. Turkey became Türkiye in 2022, Swaziland became Eswatini (SZ) in 2018, and the Netherlands Antilles (AN) was withdrawn in 2010. Treat the list as data you refresh, not a constant you hardcode.
  • Former countries have their own standard, ISO 3166-3: CSHH for Czechoslovakia, SUHH for the Soviet Union, ANHH for the Netherlands Antilles.
  • You can resolve a visitor’s country code at request time from their IP address. The ipstack API returns it in the country_code field of every lookup, alongside country_name, continent_code and location.calling_code.

#The country code standards at a glance

The seven code systems people mean when they say "country code", and who maintains each.
Standard What it identifies Format Examples Maintained by
ISO 3166-1 alpha-2Country / territory2 lettersUS, GB, IN, DE, BRISO 3166/MA
ISO 3166-1 alpha-3Country / territory3 lettersUSA, GBR, IND, DEU, BRAISO 3166/MA
ISO 3166-1 numericCountry / territory3 digits (keep leading zeros)840, 826, 356, 276, 076ISO 3166/MA, aligned to UN M49
ISO 3166-2Subdivision (state, province, region)alpha-2 + hyphen + 1 to 3 charactersUS-CA, GB-ENG, IN-MHISO 3166/MA
ISO 3166-3Former country4 lettersCSHH, SUHHISO 3166/MA
ITU-T E.164 calling codeTelephone numbering plan"+" and 1 to 3 digits+1, +44, +91, +49, +672ITU
ccTLDInternet country domaindot + 2 letters.de, .in, .br (.uk for GB)IANA, derived from alpha-2

ISO 3166-1 in numbers: 249 codes currently assigned. Alphabetic codes first published in 1974, numeric codes added in 1981, maintained by the ISO 3166 Maintenance Agency (ISO 3166/MA), which updates the list when the United Nations notifies a new member state or a name change.

#Country code list: alpha-2, alpha-3, numeric and calling code

The table below covers the most frequently looked-up countries. ISO 3166-1 assigns codes to 249 entries in total.

Download CSV Download JSON
All 249 ISO 3166-1 entries, with each entry's calling code and ccTLD.
Country Alpha-2 Alpha-3 Numeric Calling code ccTLD
AfghanistanAFAFG004+93.af
Åland IslandsAXALA248+358.ax
AlbaniaALALB008+355.al
AlgeriaDZDZA012+213.dz
American SamoaASASM016+1.as
AndorraADAND020+376.ad
AngolaAOAGO024+244.ao
AnguillaAIAIA660+1.ai
AntarcticaAQATA010+672.aq
Antigua & BarbudaAGATG028+1.ag
ArgentinaARARG032+54.ar
ArmeniaAMARM051+374.am
ArubaAWABW533+297.aw
AustraliaAUAUS036+61.au
AustriaATAUT040+43.at
AzerbaijanAZAZE031+994.az
BahamasBSBHS044+1.bs
BahrainBHBHR048+973.bh
BangladeshBDBGD050+880.bd
BarbadosBBBRB052+1.bb
BelarusBYBLR112+375.by
BelgiumBEBEL056+32.be
BelizeBZBLZ084+501.bz
BeninBJBEN204+229.bj
BermudaBMBMU060+1.bm
BhutanBTBTN064+975.bt
BoliviaBOBOL068+591.bo
Bosnia & HerzegovinaBABIH070+387.ba
BotswanaBWBWA072+267.bw
Bouvet IslandBVBVT074—.bv
BrazilBRBRA076+55.br
British Indian Ocean TerritoryIOIOT086+246.io
British Virgin IslandsVGVGB092+1.vg
BruneiBNBRN096+673.bn
BulgariaBGBGR100+359.bg
Burkina FasoBFBFA854+226.bf
BurundiBIBDI108+257.bi
CambodiaKHKHM116+855.kh
CameroonCMCMR120+237.cm
CanadaCACAN124+1.ca
Cape VerdeCVCPV132+238.cv
Caribbean NetherlandsBQBES535+599.bq
Cayman IslandsKYCYM136+1.ky
Central African RepublicCFCAF140+236.cf
ChadTDTCD148+235.td
ChileCLCHL152+56.cl
ChinaCNCHN156+86.cn
Christmas IslandCXCXR162+61.cx
Cocos (Keeling) IslandsCCCCK166+61.cc
ColombiaCOCOL170+57.co
ComorosKMCOM174+269.km
Congo - BrazzavilleCGCOG178+242.cg
Congo - KinshasaCDCOD180+243.cd
Cook IslandsCKCOK184+682.ck
Costa RicaCRCRI188+506.cr
Côte d’IvoireCICIV384+225.ci
CroatiaHRHRV191+385.hr
CubaCUCUB192+53.cu
CuraçaoCWCUW531+599.cw
CyprusCYCYP196+357.cy
Czechia (Czech Republic)CZCZE203+420.cz
DenmarkDKDNK208+45.dk
DjiboutiDJDJI262+253.dj
DominicaDMDMA212+1.dm
Dominican RepublicDODOM214+1.do
EcuadorECECU218+593.ec
EgyptEGEGY818+20.eg
El SalvadorSVSLV222+503.sv
Equatorial GuineaGQGNQ226+240.gq
EritreaERERI232+291.er
EstoniaEEEST233+372.ee
EswatiniSZSWZ748+268.sz
EthiopiaETETH231+251.et
Falkland IslandsFKFLK238+500.fk
Faroe IslandsFOFRO234+298.fo
FijiFJFJI242+679.fj
FinlandFIFIN246+358.fi
FranceFRFRA250+33.fr
French GuianaGFGUF254+594.gf
French PolynesiaPFPYF258+689.pf
French Southern TerritoriesTFATF260+262.tf
GabonGAGAB266+241.ga
GambiaGMGMB270+220.gm
GeorgiaGEGEO268+995.ge
GermanyDEDEU276+49.de
GhanaGHGHA288+233.gh
GibraltarGIGIB292+350.gi
GreeceGRGRC300+30.gr
GreenlandGLGRL304+299.gl
GrenadaGDGRD308+1.gd
GuadeloupeGPGLP312+590.gp
GuamGUGUM316+1.gu
GuatemalaGTGTM320+502.gt
GuernseyGGGGY831+44.gg
GuineaGNGIN324+224.gn
Guinea-BissauGWGNB624+245.gw
GuyanaGYGUY328+592.gy
HaitiHTHTI332+509.ht
Heard & McDonald IslandsHMHMD334+672.hm
HondurasHNHND340+504.hn
Hong Kong SAR ChinaHKHKG344+852.hk
HungaryHUHUN348+36.hu
IcelandISISL352+354.is
IndiaININD356+91.in
IndonesiaIDIDN360+62.id
IranIRIRN364+98.ir
IraqIQIRQ368+964.iq
IrelandIEIRL372+353.ie
Isle of ManIMIMN833+44.im
IsraelILISR376+972.il
ItalyITITA380+39.it
JamaicaJMJAM388+1.jm
JapanJPJPN392+81.jp
JerseyJEJEY832+44.je
JordanJOJOR400+962.jo
KazakhstanKZKAZ398+7.kz
KenyaKEKEN404+254.ke
KiribatiKIKIR296+686.ki
KuwaitKWKWT414+965.kw
KyrgyzstanKGKGZ417+996.kg
LaosLALAO418+856.la
LatviaLVLVA428+371.lv
LebanonLBLBN422+961.lb
LesothoLSLSO426+266.ls
LiberiaLRLBR430+231.lr
LibyaLYLBY434+218.ly
LiechtensteinLILIE438+423.li
LithuaniaLTLTU440+370.lt
LuxembourgLULUX442+352.lu
Macao SAR ChinaMOMAC446+853.mo
MadagascarMGMDG450+261.mg
MalawiMWMWI454+265.mw
MalaysiaMYMYS458+60.my
MaldivesMVMDV462+960.mv
MaliMLMLI466+223.ml
MaltaMTMLT470+356.mt
Marshall IslandsMHMHL584+692.mh
MartiniqueMQMTQ474+596.mq
MauritaniaMRMRT478+222.mr
MauritiusMUMUS480+230.mu
MayotteYTMYT175+262.yt
MexicoMXMEX484+52.mx
MicronesiaFMFSM583+691.fm
MoldovaMDMDA498+373.md
MonacoMCMCO492+377.mc
MongoliaMNMNG496+976.mn
MontenegroMEMNE499+382.me
MontserratMSMSR500+1.ms
MoroccoMAMAR504+212.ma
MozambiqueMZMOZ508+258.mz
Myanmar (Burma)MMMMR104+95.mm
NamibiaNANAM516+264.na
NauruNRNRU520+674.nr
NepalNPNPL524+977.np
NetherlandsNLNLD528+31.nl
New CaledoniaNCNCL540+687.nc
New ZealandNZNZL554+64.nz
NicaraguaNINIC558+505.ni
NigerNENER562+227.ne
NigeriaNGNGA566+234.ng
NiueNUNIU570+683.nu
Norfolk IslandNFNFK574+672.nf
North KoreaKPPRK408+850.kp
North MacedoniaMKMKD807+389.mk
Northern Mariana IslandsMPMNP580+1.mp
NorwayNONOR578+47.no
OmanOMOMN512+968.om
PakistanPKPAK586+92.pk
PalauPWPLW585+680.pw
Palestinian TerritoriesPSPSE275+970.ps
PanamaPAPAN591+507.pa
Papua New GuineaPGPNG598+675.pg
ParaguayPYPRY600+595.py
PeruPEPER604+51.pe
PhilippinesPHPHL608+63.ph
Pitcairn IslandsPNPCN612+64.pn
PolandPLPOL616+48.pl
PortugalPTPRT620+351.pt
Puerto RicoPRPRI630+1.pr
QatarQAQAT634+974.qa
RéunionREREU638+262.re
RomaniaROROU642+40.ro
RussiaRURUS643+7.ru
RwandaRWRWA646+250.rw
SamoaWSWSM882+685.ws
San MarinoSMSMR674+378.sm
São Tomé & PríncipeSTSTP678+239.st
Saudi ArabiaSASAU682+966.sa
SenegalSNSEN686+221.sn
SerbiaRSSRB688+381.rs
SeychellesSCSYC690+248.sc
Sierra LeoneSLSLE694+232.sl
SingaporeSGSGP702+65.sg
Sint MaartenSXSXM534+1.sx
SlovakiaSKSVK703+421.sk
SloveniaSISVN705+386.si
Solomon IslandsSBSLB090+677.sb
SomaliaSOSOM706+252.so
South AfricaZAZAF710+27.za
South Georgia & South Sandwich IslandsGSSGS239+500.gs
South KoreaKRKOR410+82.kr
South SudanSSSSD728+211.ss
SpainESESP724+34.es
Sri LankaLKLKA144+94.lk
St. BarthélemyBLBLM652+590.bl
St. HelenaSHSHN654+290.sh
St. Kitts & NevisKNKNA659+1.kn
St. LuciaLCLCA662+1.lc
St. MartinMFMAF663+590.mf
St. Pierre & MiquelonPMSPM666+508.pm
St. Vincent & GrenadinesVCVCT670+1.vc
SudanSDSDN729+249.sd
SurinameSRSUR740+597.sr
Svalbard & Jan MayenSJSJM744+47.sj
SwedenSESWE752+46.se
SwitzerlandCHCHE756+41.ch
SyriaSYSYR760+963.sy
TaiwanTWTWN158+886.tw
TajikistanTJTJK762+992.tj
TanzaniaTZTZA834+255.tz
ThailandTHTHA764+66.th
Timor-LesteTLTLS626+670.tl
TogoTGTGO768+228.tg
TokelauTKTKL772+690.tk
TongaTOTON776+676.to
Trinidad & TobagoTTTTO780+1.tt
TunisiaTNTUN788+216.tn
Türkiye (Turkey)TRTUR792+90.tr
TurkmenistanTMTKM795+993.tm
Turks & Caicos IslandsTCTCA796+1.tc
TuvaluTVTUV798+688.tv
U.S. Outlying IslandsUMUMI581+1.um
U.S. Virgin IslandsVIVIR850+1.vi
UgandaUGUGA800+256.ug
UkraineUAUKR804+380.ua
United Arab EmiratesAEARE784+971.ae
United KingdomGBGBR826+44.uk
United StatesUSUSA840+1.us
UruguayUYURY858+598.uy
UzbekistanUZUZB860+998.uz
VanuatuVUVUT548+678.vu
Vatican CityVAVAT336+39.va
VenezuelaVEVEN862+58.ve
VietnamVNVNM704+84.vn
Wallis & FutunaWFWLF876+681.wf
Western SaharaEHESH732+212.eh
YemenYEYEM887+967.ye
ZambiaZMZMB894+260.zm
ZimbabweZWZWE716+263.zw
Two traps in this table.

The United Kingdom is GB in ISO 3166-1 but uses .uk as its domain, the best-known mismatch between the two systems. And numeric codes are always three digits: Australia is 036, not 36, and Brazil is 076, not 76. Strip the leading zero and joins against UN or customs datasets silently fail.

ISO 3166-1 assigns codes to 249 countries, territories and areas, all listed above. Numeric codes are always three digits (Australia is 036, Brazil is 076), and Bouvet Island (BV) has no assigned calling code.

#What is a country code?

A country code is a short, standardised identifier for a country, territory or area of geographical interest. The most widely used country code standard is ISO 3166-1, which gives every entry three parallel codes: a two-letter code (alpha-2), a three-letter code (alpha-3) and a three-digit numeric code. This standard is typically helpful for programming, communication, and data processing fields. These codes are also helpful in the aviation domain. The ISO-3166-1 alpha-2 is the most commonly used standard for communication and data processing purposes.

ISO 3166-1 currently assigns codes to 249 countries, territories and areas. The alphabetic codes were first published in 1974 and numeric codes were added in 1981. The list is maintained by the ISO 3166 Maintenance Agency (ISO 3166/MA), which issues an update whenever the United Nations notifies a new member state, a name change or a withdrawal — which is why country codes should be treated as reference data you refresh, not constants you hardcode.

What is ISO 3166-1 alpha-2?

In ISO-3166-1 standard, the two-letter country code definition is alpha-2, representing two-letter codes for countries and their territories. This standard was defined under ISO standard in 1974 for the first time, including the special areas of geographical interests, and is a more commonly used standard compared to ISO alpha-3 and ISO numeric standards. In addition, ISO-3166-1 alpha-2 is more prominently used for the internet’s country code top-level domain, and it is the code the Universal Postal Union uses to identify destination countries in international mail.

Alpha-2 has become the default country identifier across the web because so many other standards are built on top of it:

  • Country code top-level domains (ccTLDs) — .de for Germany, .in for India, .br for Brazil. The main exception is the United Kingdom, whose ISO code is GB but whose domain is .uk.
  • Locale identifiers (BCP 47) — en-US, en-GB, pt-BR and fr-CA all combine an ISO 639-1 language code with an ISO 3166-1 alpha-2 region code.
  • Currency codes (ISO 4217) — the first two letters are usually the country’s alpha-2 code: USD, JPY, INR, CHF.
  • Payment, shipping and tax systems — address forms, customs declarations, VAT registration prefixes and card-network country fields all expect alpha-2.
  • API responses — including ipstack, which returns country_code (alpha-2) on every IP lookup. See the API documentation, geolocation API and free IP API.

ISO 3166-1 alpha-3 and numeric codes: when to use which

All three ISO 3166-1 code sets describe the same 249 entries. They differ in what they optimise for.

  • Alpha-3 (USA, GBR, IND, DEU) is easier for a human to associate with a country name at a glance, which is why it appears on passports, in sports broadcasting, in SWIFT/BIC codes and in most financial and government reporting. Use it where people read the code.
  • Numeric-3 (840, 826, 356, 276) is script-independent — it carries no Latin-alphabet assumption. It is also identical to the UN Statistics Division M49 codes, which makes it the safest key for joining against UN, World Bank and customs datasets. Use it for machine-to-machine exchange.
  • Alpha-2 (US, GB, IN, DE) is the shortest and by far the most widely supported. Use it as your default in databases, APIs and front-end forms.

One practical rule: store one canonical code and derive the rest. Storing alpha-2 and mapping to alpha-3 or numeric on read avoids the classic bug where three columns drift out of sync after a rename.

Reserved, user-assigned and former country codes

Not every two-letter combination in ISO 3166-1 is an assigned country. Four categories matter in practice:

  • Officially assigned — the 249 live codes (US, GB, IN, DE…). These are the only ones that identify a current country, territory or area.
  • Exceptionally reserved — combinations held back for a specific purpose. EU for the European Union, UK for the United Kingdom (alongside the official GB), and AC for Ascension Island are the ones you will meet most often. Treating EU as a country in a database is a frequent modelling mistake.
  • User-assigned — AA, QM–QZ, XA–XZ and ZZ are permanently free for private use. If you need an internal value for “unknown”, “multi-region” or a test fixture, use one of these.
  • Formerly used (ISO 3166-3) — when a country ceases to exist, its old code moves to ISO 3166-3 as a four-letter code: CSHH (Czechoslovakia), SUHH (Soviet Union), ANHH (Netherlands Antilles, withdrawn in 2010), YUCS (Yugoslavia).

Recent changes worth knowing: Turkey was renamed Türkiye in 2022 (the code TR is unchanged), Swaziland became Eswatini in 2018 (SZ unchanged), and Macedonia became North Macedonia in 2019 (MK unchanged). Names change far more often than codes — another argument for storing the code, not the name.

Why do we need a country code?

Country codes exist because country names are unreliable data. “United States”, “USA”, “U.S.A.”, “États-Unis” and “米国” all refer to the same place; US and 840 refer to it unambiguously in every language, every character set and every system. However, the alpha-2 country code representation is highly helpful for written communication and data representation. Country code importance was even emphasized with the arrival of the internet when domain names services were allotted based on country codes to identify the web traffic from different countries. Now country code is equally important in communication as well as on the web.

In practice, country codes are what make these everyday operations possible:

  • Routing and personalisation — serving the right language, currency, tax rate and legal notice to each visitor.
  • Compliance and access control — GDPR consent flows, sanctions screening, age-gating and geo-restricted licensing all key off a country code.
  • Payments and fraud scoring — comparing the billing-address country with the IP country is one of the oldest and most effective fraud signals.
  • Logistics — shipping labels, customs declarations and postal routing all carry alpha-2 codes.
  • Analytics and reporting — joining internal data to UN, World Bank or Eurostat datasets requires a shared country key.

#Country codes in software: how to store and validate them

If you are building anything that touches more than one country, four decisions save you most of the pain:

  • Store alpha-2 as a fixed-length CHAR(2), uppercase. ISO 3166-1 alpha-2 codes are always uppercase; normalise on write so "gb" and "GB" cannot both exist.
  • Validate against a real list, not a regex. ^[A-Z]{2}$ accepts ZQ, XB and 427 nonexistent combinations. Validate against the assigned set.
  • Keep the list as data you can update, a table, a config file or a library refreshed on a schedule, never as a hardcoded enum in application code.
  • Never store the country name as the key. Store the code, resolve the display name at render time in the user's language.

A minimal validation example in Python:

VALID = {"US", "GB", "IN", "DE", "BR"}   # load the full 249-code set from your reference table

def normalise_country_code(value: str) -> str:
    code = (value or "").strip().upper()
    if code not in VALID:
        raise ValueError(f"{value!r} is not an assigned ISO 3166-1 alpha-2 code")
    return code

#Why a calling code is not a country code

Scope

The phrase "country code" is used in two completely different contexts, and mixing them up is the most common mistake on this topic. ISO 3166-1 codes (GB, IND, 826) identify countries in data. Calling codes (+44, +91) route telephone calls and are defined by ITU-T E.164.

How to dial an international number

To dial internationally from a landline you dial three things in order: your country's international access prefix, the destination country calling code, then the national number (dropping any leading trunk zero).

There is no single global access prefix. 011 is the prefix used in the United States, Canada and the rest of the North American Numbering Plan; most of Europe, Asia and Africa use 00; Japan uses 010; Australia uses 0011.

For example, calling a London landline (020 7946 0018) from the United States:

011      44         20            7946 0018
access   country    area code     local number
prefix   code (UK)  (0 dropped)

Country code for mobile communication

On a mobile, the access prefix is replaced by a + sign, followed by the country calling code, then the national number. Writing numbers in this form is the E.123 international notation. Storing them as E.164 (digits only, no spaces) is what lets WhatsApp, Telegram, SMS gateways and 2FA providers deliver to any country.

For example, a UK mobile written nationally as 07911 123456 becomes:

  • Display (E.123): +44 7911 123456
  • Storage (E.164): +447911123456 — leading 0 removed, no spaces

Always store phone numbers in E.164 and store the country separately as an ISO 3166-1 alpha-2 code. A calling code is not a country: +1 alone cannot tell you whether a number is American, Canadian or Jamaican. See our guide to country code numbers.

It is tempting to treat +44 as “the code for the UK” and be done with it. The mapping does not hold:

  • One calling code, many countries. 25 countries and territories share +1 under the North American Numbering Plan: the US, Canada, Jamaica, the Bahamas, the Dominican Republic and 20 more. Russia and Kazakhstan share +7.
  • One calling code, several ISO codes. +672 covers the Australian external territories, which hold four distinct ISO codes: CC (Cocos Islands), CX (Christmas Island), HM (Heard & McDonald Islands) and NF (Norfolk Island).
  • Calling codes vary in length. They are one to three digits (+1, +44, +971), so you cannot parse them by taking a fixed number of characters.
  • Numbers travel. A person with a +44 number can be sitting anywhere on earth, so a calling code tells you where a number was issued, never where the user is now.

If you need to know where a request is actually coming from, resolve it from the IP address instead, which is what the next section covers.

#How to get a visitor's country code from their IP address

Asking users to select their country is slow and often wrong. Resolving it from the IP address at request time gives you an ISO 3166-1 alpha-2 code before the page renders. The ipstack API returns it in the country_code field of every lookup:

curl "https://api.ipstack.com/134.201.250.155?access_key=YOUR_ACCESS_KEY"

A trimmed response. The country fields are returned on every plan, including the free tier:

{
  "ip": "134.201.250.155",
  "continent_code": "NA",
  "continent_name": "North America",
  "country_code": "US",
  "country_name": "United States",
  "region_code": "CA",
  "region_name": "California",
  "city": "Los Angeles",
  "location": {
    "capital": "Washington D.C.",
    "country_flag_emoji": "🇺🇸",
    "calling_code": "1",
    "is_eu": false
  }
}

Note that a single response gives you both systems at once: country_code is the ISO 3166-1 alpha-2 code and location.calling_code is the ITU calling code, plus is_eu, which answers the "do I need a GDPR consent banner?" question directly.

Get a free API key

The free plan is 100 requests a month.

In Python

import requests

r = requests.get("https://api.ipstack.com/134.201.250.155",
                 params={"access_key": "YOUR_ACCESS_KEY", "fields": "country_code,country_name"})
print(r.json()["country_code"])   # -> US

In JavaScript

const res = await fetch(
  `https://api.ipstack.com/check?access_key=${KEY}&fields=country_code,country_name`
);
const { country_code } = await res.json();   // -> "US"

The /check endpoint resolves the requester's own IP, so you do not need to extract it yourself. A bulk endpoint is available on paid plans for looking up up to 50 addresses in a single call.

#Common country code mistakes (and how to avoid them)

Seven mistakes that break country data, what each one breaks, and the fix.
MistakeWhy it breaksDo this instead
Using UK as the code for the United KingdomUK is exceptionally reserved, not assigned. Strict validators and ISO-based datasets reject it.Use GB. Accept UK as an alias on input, normalise to GB on write.
Treating EU as a countryEU is a reserved code for the European Union, not a country. It has no entry in country datasets.Model region membership separately, or use the is_eu flag returned by ipstack.
Dropping leading zeros from numeric codesAustralia is 036, not 36. Stored as an integer, joins against UN/customs data fail silently.Store numeric codes as a 3-character string, never as an integer.
Confusing country codes with language codesen, de and fr are ISO 639-1 language codes. "en" is not a country; the UK is GB.Keep language and country separate; combine only in locale tags like en-GB.
Deriving country from the calling code+1 covers 25 countries; +7 covers two. The mapping is not one-to-one.Store the ISO alpha-2 code alongside the E.164 number.
Hardcoding the list in application codeNames and entries change (Türkiye 2022, Eswatini 2018, AN withdrawn 2010). A shipped enum goes stale.Load the list from a table or maintained library and refresh it on a schedule.
Storing the country name as the keyNames are translated, renamed and spelled inconsistently; joins and dedupes break.Store the alpha-2 code; resolve the display name at render time.

#Popular questions and prompts about country codes

These are the questions developers and analysts actually type into Google and AI assistants about country codes. Each gets a direct, self-contained answer.

“Is the country code for the UK GB or UK?”

GB. The officially assigned ISO 3166-1 alpha-2 code for the United Kingdom is GB (alpha-3 GBR, numeric 826). UK is only "exceptionally reserved", so strict ISO validators reject it. The confusion comes from the .uk domain, which is the best-known case of a ccTLD diverging from the standard.

“What is the difference between ISO 3166-1 alpha-2 and alpha-3?”

Both identify the same 249 countries and territories. Alpha-2 uses two letters (DE, IN) and is the default in APIs, ccTLDs and locale tags. Alpha-3 uses three letters (DEU, IND), is easier for people to associate with a country name, and is preferred in passports, sport and statistics.

“How many country codes are there?”

ISO 3166-1 currently assigns codes to 249 countries, territories and areas of geographical interest, more than the 193 UN member states, because the standard also covers dependencies and special areas such as Hong Kong (HK), Puerto Rico (PR) and Antarctica (AQ).

“Is +1 a country code?”

+1 is a calling code, not an ISO country code. It is shared by 25 countries and territories in the North American Numbering Plan, including the United States (US), Canada (CA), Jamaica (JM) and the Bahamas (BS). Calling codes come from ITU-T E.164; ISO 3166 codes come from ISO.

“How do I detect a user's country code from their IP address?”

Send the IP address to a geolocation API and read the ISO alpha-2 field from the response. With ipstack: GET https://api.ipstack.com/{ip}?access_key=YOUR_KEY returns country_code ("US"), country_name, continent_code and location.calling_code. Use the /check endpoint to resolve the requester's own address.

“Which country code should I store in my database?”

Store ISO 3166-1 alpha-2 as an uppercase CHAR(2) and derive alpha-3, numeric and display names from it. It is the shortest code, the most widely supported by libraries and APIs, and the one your input forms and third-party services will already speak.

Prompt: “Write a prompt that validates and normalises country codes”

A pattern that works well with any coding assistant. Naming every input form the function must accept is what stops the model guessing.

You are a senior backend engineer. Write a [language] function that accepts a country identifier, an ISO 3166-1 alpha-2 code, alpha-3 code, numeric code, or common country name, and returns the canonical uppercase alpha-2 code, raising a typed error for anything unassigned. Handle the UK→GB alias, preserve leading zeros on numeric codes, and include unit tests.

#Conclusion

Country codes look trivial until a rename, a reserved code or a shared calling code quietly corrupts your data. The short version: use ISO 3166-1 alpha-2 as your canonical country identifier, derive alpha-3 and numeric from it, keep the list as refreshable reference data rather than hardcoded values, and never treat a telephone calling code as a country.

When you need to know which country a request is actually coming from, resolve it at runtime: the ipstack API returns the ISO alpha-2 country_code — along with region, city, currency, timezone and an is_eu flag — from a single IP lookup, starting free. Get a free API key and try it against your own traffic. See also JSON IP API, pricing and MCP, and the API glossary for the terms used here.

#FAQs

What is a country code?

A country code is a short, standardised identifier for a country or territory. In software it usually means an ISO 3166-1 code: alpha-2 (two letters, e.g. US), alpha-3 (three letters, e.g. USA) or numeric-3 (three digits, e.g. 840). ISO 3166-1 covers 249 countries, territories and areas.

What is ISO 3166-1 alpha-2?

ISO 3166-1 alpha-2 is the two-letter country code standard: US, GB, IN, DE. First published in 1974 and maintained by the ISO 3166 Maintenance Agency, it is the most widely used country identifier on the web, underpinning ccTLDs, locale tags and ISO 4217 currency codes.

Is a country code the same as a phone country code?

No. Phone codes such as +44 and +91 are ITU-T E.164 calling codes, assigned by the International Telecommunication Union. ISO 3166-1 codes (GB, IN) identify countries in data. They do not map one-to-one: 25 countries share +1, and +672 spans four different ISO codes.

Why is the UK's country code GB and not UK?

Because ISO 3166-1 derives codes from official country names, and the official name is the "United Kingdom of Great Britain and Northern Ireland". UK is exceptionally reserved rather than assigned. The .uk domain predates and diverges from the standard.

How many country codes are there in ISO 3166-1?

There are 249 officially assigned alpha-2 codes. That is more than the 193 UN member states because the standard also covers territories, dependencies and special areas of geographical interest, such as Hong Kong (HK), Puerto Rico (PR) and Greenland (GL).

Can I use AA, XX or ZZ as a custom country code?

Yes. AA, QM to QZ, XA to XZ and ZZ are permanently user-assigned in ISO 3166-1, meaning ISO will never allocate them to a real country. They are the correct choice for internal values such as "unknown", "multi-region" or test data. Never invent an unassigned code.

Do country codes ever change?

The codes themselves rarely change, but names and entries do. Turkey became Türkiye in 2022, Swaziland became Eswatini in 2018, and the Netherlands Antilles (AN) was withdrawn in 2010 and moved to ISO 3166-3 as ANHH. Refresh your country list on a schedule.

How do I get the country code from an IP address?

Call an IP geolocation API. ipstack returns the ISO 3166-1 alpha-2 code in the country_code field of every lookup, GET https://api.ipstack.com/{ip}?access_key=YOUR_KEY, along with country_name, continent_code, region_code and location.calling_code.

What is the difference between ISO 3166-1, 3166-2 and 3166-3?

ISO 3166-1 codes countries and territories (US, USA, 840). ISO 3166-2 codes their subdivisions, states, provinces and regions, as alpha-2 plus a suffix (US-CA, GB-ENG, IN-MH). ISO 3166-3 codes countries that no longer exist, using four letters (CSHH for Czechoslovakia).

#Sources

  • ISO 3166-1 — Codes for the representation of names of countries and their subdivisions. iso.org
  • ITU-T E.164 — The international public telecommunication numbering plan. itu.int
  • UN M49 — Standard country or area codes for statistical use, which the ISO numeric codes align to. unstats.un.org

Related guides

Find your own code

What is your country code?

The two-letter ISO code for the country you are in, and the one call that returns it.

Read the guide
Calling codes

What is a country code number?

+1, +44 and +91: the ITU dialling prefixes, and why they do not map one-to-one to countries.

Read the guide
API reference

ipstack API documentation

The base URL, the three endpoints and every field a lookup returns.

Read the guide

Resolve a visitor's country code at request time

One lookup returns the ISO alpha-2 code, the country name, the continent and the calling code together. The free plan is 100 requests a month.

Get a free API key