Developer/Maintainer: AJ

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,049 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 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 three main 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 returned for each object, e.g /api/search/Bucharest?excludeMatchScore=1, /api/search/Oregon?excludeMatchScore=1 (default=0).

Endpoints

The ISO 3166-2 API currently has 6 main endpoints, /all, /alpha, /subdivision, /search, /country_name, and /list_subdivisions. A description of each along with a few examples are below.

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.

https://iso3166-2-api.vercel.app/api/all

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

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 : ).