State (Country Subdivision) Codes

The API uses ISO 3166-2 subdivision codes (without country code) for the "state" field in our API requests and responses. This page clarifies edge cases and exceptions to that rule.

In several countries where there are several levels of subdivisions the API may support some but not all of them.

Subdivisions in countries with multiple layers

In countries with multiple layers of subdivisions with ISO 3166-2 codes, we may support some but not all.
Country CodeCountry NameDescription
CZCzech RepublicRegions are supported.
Districts are not supported.
ESSpainProvinces and autonomous cities are supported.
Autonomous communities are not supported.
FRFranceMetropolitan departments are supported.
Metropolitan Regions, Overseas Departments, and Dependency and overseas territorial collectivities are not supported.
GBUnited KingdomTwo-tier counties are supported.
Unitary authorities are supported.
One custom state "XGL" (Greater London) covers the City of London and the 32 London boroughs.
Metropolitan counties are supported, with the following custom codes:

XGMGreater Manchester
XSYSouth Yorkshire
XTWTyne and Wear
XWMWest Midlands
XWYWest Yorkshire

London Boroughs are not supported.
Metropolitan Districts are not supported.
Countries are not supported.
IEIrelandCounties are supported.
Provinces are not supported.
ITItalyProvinces are supported.
Regions are not supported.
NLNetherlandsProvinces are supported.
Countries and Special Municipalities are not supported.
PHPhilippinesProvinces are supported.
One custom province "NCR" covers Metro Manila.

Regions are not supported.
SGSingaporeOne custom state "SG" is supported.
Districts are not supported.
TWTaiwanDistricts are supported, with the exception of:

KHQ(see KHH)
TXQ(see TXG)
TNQ(see TNN)

Note that TPQ refers to New Taipei City.

Municipalities are supported.
All currently assigned special municipalities are supported.

Two custom codes cover additional counties:

LCHLienchiang County (incl. Lienchiang and Matsu Islands)
KNMKinmen County (incl. Kinmen and Quemoy)

Subdivisions included in ISO 3166-1

Some country subdivisions also have a dedicated ISO 3166-1 country code. In this case, the same code is used as both the country and state code.

United States Outlying Areas

Country CodeCountry NameState Code
ASAmerican SamoaAS
MPNorthern Mariana IslandsMP
PRPuerto RicoPR
UMUnited States Minor Outlying IslandsUM
VIUS Virgin IslandsVI

United Kingdom Crown Dependencies

Country CodeCountry NameState Code
IMIsle of ManIM