About
The ISO 3166-2 API is a custom-built, open-source and free to use RESTful API wrapper for the iso3166-2 repo
and dataset that stores the latest and most up-to-date ISO 3166-2 subdivision data for 5,046 subdivisions across ~250 countries/territories represented in the ISO 3166-2 standard.
The API supports supports a plethora of bespoke, informative and useful attributes and data, which are discussed further below.
A demo of the API and Python software is available
here.
iso3166-2 software homepage/repo is available
here.
A Medium article is available here.
Attributes
There are seven main attributes returned from the API:
- Name - official subdivision name
- Local/other name - subdivision name in local language or any alternative name/nickname it is commonly known by
- Parent Code - subdivision parent code
- Type - subdivision type e.g. region, state, canton, parish etc
- Latitude/Longitude - subdivision coordinates
- Flag - subdivision flag from the iso3166-flag-icons repo; this is another ISO 3166 related custom-built and bespoke dataset of over 3500 regional/subdivision flags
- History - historical updates/changes to the subdivision code and naming conventions, as per the custom-built and bespoke iso3166-updates repo
Query String Parameters
There are several query string parameters that can be passed through several of the endpoints of the API:
- filter_attributes: this parameter allows you to filter the outputs from the various endpoints by only including a subset of the required attributes. A single attribute or comma separated list of attributes can be input. The supported attribute values are listed above.
- likeness: this is a value between 1 and 100 that increases or reduces the % of similarity/likeness that the inputted search terms have to match to the subdivision data in the subdivision name and subdivision local/other name attributes. Similarly, it can be used to convey the % of similarity/likeness that the inputted search terms have to match to the country of the associated subdivisions. This can be used in the /api/search and /api/country_name endpoints. Having a higher value should return more exact and less matches and having a lower value will return less exact but more matches, e.g /api/search/Paris?likeness=50, /api/search/Bremen,Saxony?likeness=90 (default=100).
- excludeMatchScore: exclude the matchScore attribute from the search results when using the /api/search endpoint. The match score is the % of a match each returned subdivision data object is to the search terms, with 100% being an exact match. By default the match score is excluded from the results; set excludeMatchScore=0 to include it, e.g /api/search/Bucharest?excludeMatchScore=0. When included, results are returned as a list ordered by descending match score rather than as a nested object.
- limit: this allows you to limit the total number of countries returned from the API call. This is only available in the /api/all endpoint. By default, when calling the /api/all endpoint, all of the available data is called so this param allows you to get a faster small subset of the data. The endpoint accepts an integer value representing the total number of countries to return, e.g /api/all?limit=10, /api/all?limit=50 etc.
- format: output format for the response, one of json (default), csv or geojson. csv returns a downloadable CSV file with one row per subdivision and geojson returns a GeoJSON FeatureCollection with lat/lng as Point geometry, which works directly in QGIS, Mapbox and Leaflet. Supported on /api/all, /api/alpha, /api/subdivision, /api/search, /api/search_geo, /api/country_name, /api/coords and /api/random, e.g /api/alpha/DE?format=csv, /api/alpha/FR?format=geojson. /api/list_subdivisions supports json and csv only, as it returns codes rather than attributes.
- lang: filter the localOtherName attribute to only include entries in the given ISO 639 language code, e.g /api/all?lang=fra, /api/alpha/DE?lang=deu. Supported on all data endpoints. An unrecognised ISO 639 code returns a 400 error.
- page / pageSize: paginate the /api/all response. Pagination only activates when one of these is explicitly provided. page is 1-indexed (default=1) and pageSize accepts 1-250 (default=50). The response is wrapped in a {"data": {...}, "page": N, "pageSize": N, "totalPages": N, "totalCountries": N} envelope, e.g /api/all?page=2&pageSize=25. Pagination is applied before the format conversion, so combining it with format=csv or format=geojson returns just that page, with the metadata in the X-Page, X-Page-Size, X-Total-Pages and X-Total-Countries response headers.
- radius: search radius in kilometers for the /api/search_geo endpoint, e.g /api/search_geo/39.4178,-2.6232?radius=100 (default=50).
All responses include the Access-Control-Allow-Origin: * header, so the API can be called directly from browser JavaScript on any origin without a proxy. Successful GET data responses also carry Cache-Control: public, max-age=3600 and an ETag — sending that ETag back in an If-None-Match header returns a 304 Not Modified instead of re-downloading the payload. /api/random is the exception and is served with Cache-Control: no-store, as a cached response would hand the same "random" subdivision to every caller until it expired.
Two endpoints are rate limited per caller and return a 429 once the limit is exceeded: /api/coords (30 requests per minute, as it proxies the third-party OpenStreetMap Nominatim service) and /api/all (300 requests per minute, as it returns the entire ~2.6MB dataset in one response). All other endpoints are served from local data and are not rate limited.
Endpoints
The ISO 3166-2 API currently has 7 main endpoints, /all, /alpha, /subdivision, /search, /country_name, /list_subdivisions, and /search_geo. A description of each along with a few examples are below. There are also several supporting endpoints: /coords returns the subdivision at a given latitude/longitude, /random returns a single random subdivision, /stats returns live dataset statistics, /version returns the iso3166-2 package version the API is serving data from and /spec serves the OpenAPI specification. Bulk lookups that exceed URL length limits can use POST /api/subdivision with a JSON body of up to 500 subdivision codes.
All
The /api/all endpoint returns all ISO 3166-2 subdivision data for all countries/territories. The list of countries supported is according
to the ISO 3166-1 standard. The endpoint will
return all data available but to limit the data and return the top X country data you can pass in the ?limit query string parameter e.g
?limit=100 will limit to the first 100 countries and their data.
https://iso3166-2-api.vercel.app/api/all
https://iso3166-2-api.vercel.app/api/all?limit=50
Alpha
The /api/alpha endpoint returns all ISO 3166-2 subdivision data for a country/territory according to its ISO 3166-1 alpha-2, alpha-3 or numeric country code.
A comma separated list of country codes can also be input.
https://iso3166-2-api.vercel.app/api/alpha/{input_alpha}
https://iso3166-2-api.vercel.app/api/alpha/AD
https://iso3166-2-api.vercel.app/api/alpha/DE
https://iso3166-2-api.vercel.app/api/alpha/MEX
https://iso3166-2-api.vercel.app/api/alpha/PRY
https://iso3166-2-api.vercel.app/api/alpha/DE,674
https://iso3166-2-api.vercel.app/api/alpha/MEX,768
Subdivision
The /api/subdivision endpoint returns all ISO 3166-2 subdivision data for an input subdivision code or name. A comma separated list of subdivision code can also be input.
https://iso3166-2-api.vercel.app/api/subdivision/{input_subdivision}
https://iso3166-2-api.vercel.app/api/subdivision/GB-ABC
https://iso3166-2-api.vercel.app/api/subdivision/US-VA,US-WY
https://iso3166-2-api.vercel.app/api/subdivision/CZ-642,CZ-805
https://iso3166-2-api.vercel.app/api/subdivision/AU-NSW,AU-WA,AU-VIC
Search
The /api/search endpoint returns all subdivision data to a country/territory that contain the sought search terms in their subdivision code, name or local/other name
attributes. A comma separated list of search terms can also be input. By default the API will look for an exact match, but the % of likeness to the input search terms
found in the subdivision data can be amended via the 'likeness' query string parameter, lowering this value will expand the search space for the terms; a value between
0 and 100 is accepted. Additionally you can pass in the 'excludeMatchScore' parameter which will exclude the 'Match Score' attribute from the search results which
conveys the % match the subdivision object names are to the input search terms; the outputs will be sorted alphabetically by country code in this case. By default the
output will be sorted by % match descending.
https://iso3166-2-api.vercel.app/api/search/{input_search_term}
https://iso3166-2-api.vercel.app/api/search/Kingston
https://iso3166-2-api.vercel.app/api/search/Kyoto,JP-13,愛知県
https://iso3166-2-api.vercel.app/api/search/western?likeness=80
https://iso3166-2-api.vercel.app/api/search/Yorkshire?filter=name,localOtherName,type
https://iso3166-2-api.vercel.app/api/search/new york,new jersey,new hampshire?excludeMatchScore=0
https://iso3166-2-api.vercel.app/api/search/Wakanda
Search Geo
The /api/search_geo endpoint returns all subdivision data for subdivisions whose latitude/longitude coordinates are approximately equal to the input coordinates.
A comma separated lat,lng string must be input. You can optionally pass a ?radius parameter (in kilometers) to control the search radius; the default radius is 50 km.
https://iso3166-2-api.vercel.app/api/search_geo/{input_latlng}
https://iso3166-2-api.vercel.app/api/search_geo/39.4178,-2.6232
https://iso3166-2-api.vercel.app/api/search_geo/-35.4884,149.0027
https://iso3166-2-api.vercel.app/api/search_geo/37.9567,-4.8477?radius=25
Country Name
The /api/country_name endpoint returns all ISO 3166-2 subdivision data for a country/territory via its country name, as it
is commonly known in English. A comma separated list of country names can also be input.
https://iso3166-2-api.vercel.app/api/country_name/{input_country_name}
https://iso3166-2-api.vercel.app/api/country_name/Ireland
https://iso3166-2-api.vercel.app/api/country_name/Jamaica
https://iso3166-2-api.vercel.app/api/country_name/Panama,Rwanda,Zambia
List Subdivisions
The /api/list_subdivisions endpoint returns all ISO 3166-2 subdivision codes for all countries/territories. The list of countries supported is according
to the ISO 3166-1 standard. You can also pass in a specific
country to get its subdivision codes from via its alpha-2, alpha-3 or numeric country codes.
https://iso3166-2-api.vercel.app/api/list_subdivisions
https://iso3166-2-api.vercel.app/api/list_subdivisions
https://iso3166-2-api.vercel.app/api/list_subdivisions/MA
https://iso3166-2-api.vercel.app/api/list_subdivisions/US
https://iso3166-2-api.vercel.app/api/list_subdivisions/ZA
https://iso3166-2-api.vercel.app/api/list_subdivisions/SK
Contributing
Contributions, enhancements or feedback to the software and or API are more than welcome! You can raise an Issue or make a pull request on the GitHub Repo or email amckenna41@qub.ac.uk.
Credits
The Python software and accompanying API are solely developed and maintained by me : ).