About
The ISO 3166-2 API is a custom-built, open-source and free to use RESTful API that provides programmatic access to a plethora of subdivision data attributes for all ISO 3166-2 countries/territories.
For each country, the API returns its subdivisions' codes, names, local names, types, parent codes, latitude/longitudes and flags. The API accepts the alpha 2 letter, 3 letter and numeric variations
of the ISO 3166-1 country codes as well as via the ISO 3166-2 subdivision codes. It can also accept the country name and subdivision name, as they are commonly known in English.
A demo of the API and Python software is available here.
Source code available here.
Attributes
The list of data attributes supported by the API for each ISO 3166-2 code entry, along with a description of each is below:
- Code - subdivision code, according to the ISO 3166-2.
- Name - subdivision name.
- Local name - subdivision name in country's local languages.
- Type - subdivision type e.g. region, state, canton, parish etc.
- Parent code - the parent regional/subdivision code for subdivision, if applicable.
- Latitude/Longitude - the coordinates for the subdivision, according to Google Maps API.
- Flag - URL for subdivision flag (from iso3166-flag-icons repo), if applicable.
Endpoints
The ISO 3166-2 API currently has the following 3 endpoints:
| Endpoint | Description |
|---|---|
| https://iso3166-2-api.vercel.app/api/all | Return all suddivision data attributes for all countries in the ISO 3166-2. |
| https://iso3166-2-api.vercel.app/api/alpha/{input_alpha} | Return all subdivision data attributes for country/countries with the matching ISO 3166-1 2 letter alpha-2, 3 letter alpha-3 or numeric country code. A comma seperated list of country codes can also be input. |
| https://iso3166-2-api.vercel.app/api/country_name/{input_country_name} | Return all subdivision data attributes for input country name, as it is commonly known in English. A comma seperated list of country names can also be input. |
| https://iso3166-2-api.vercel.app/api/subdivision/{input_subdivision_code} | Return the subdivision data for a specific input via its ISO 3166-2 code. A comma seperated list of subdivision codes can also be input. |
| https://iso3166-2-api.vercel.app/api/name/{input_subdivision_name} | Return all subdivision data attributes for input subdivision name, as it is commonly known in English. A comma seperated list of subdivision names can also be input. |
all
The /all endpoint returns all the subdivision data attribute values for all ISO 3166-2 countries. The list of countries supported is according to the
ISO 3166-1 standard.
https://iso3166-2-api.vercel.app/api/all
country alpha code
The /alpha endpoint returns all the subdivision data attribute values for the country with the matching 2 letter alpha-2, 3 letter alpha-3 or numeric country codes.
A comma seperated list of varying country codes can also be input.
https://iso3166-2-api.vercel.app/api/alpha/{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/YEM,ZAF,ZMB
https://iso3166-2-api.vercel.app/api/alpha/558,690,807
https://iso3166-2-api.vercel.app/api/alpha/GN,KEN,434
country name
The /country_name endpoint returns all the subdivision data attribute values for a country according to its name as it is commonly known in English. A comma
seperated list of country names can also be input.
https://iso3166-2-api.vercel.app/api/country_name/{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
Subdivision Code
The /subdivision endpoint returns all the subdivision data for the inputted subdivision, according to its ISO 3166-2 subdivision code. A comma seperated
list of codes can also be input.
https://iso3166-2-api.vercel.app/api/subdivision/{subdivision}
https://iso3166-2-api.vercel.app/api/subdivision/GB-ABD
https://iso3166-2-api.vercel.app/api/subdivision/LV-041
https://iso3166-2-api.vercel.app/api/subdivision/UZ-NG,UZ-TK,UZ-XO
subdivision name
The /name endpoint returns all the subdivision data attribute values for a country according to its subdivision name, as it is commonly known in English. A comma
seperated list of subdivision names can also be input. This endpoint also has the likeness score (`?likeness=`) query string parameter that can be appended to the URL.
This can be set between 1 - 100, representing a % of likeness to the input name the return subdivisions should be, e.g: a likeness score of 90 will return fewer
potential matches whose name only match to a high degree compared to a score of 10 which will create a larger search space, thus returning more potential subdivision
matches. A default likeness of 100 (exact match) is used, if no match found then this is reduced to 90.
https://iso3166-2-api.vercel.app/api/name/{input_subdivision_name}
https://iso3166-2-api.vercel.app/api/name/Satakunta
https://iso3166-2-api.vercel.app/api/name/Cavan?likeness=70
https://iso3166-2-api.vercel.app/api/name/Goiás,ParaÃba,São Paulo
Credits
The Python software and accompanying API were solely developed by me : ).
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.