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, alpha-3 and numeric variations of the ISO 3166-1 country codes, this will return all the
subdivision data for the sought country. The country name can also be used to search for the sought country's subdivision data. Finally, the ISO 3166-2
subdivision name and code can be used to search for a sought subdivision.
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 6 endpoints:
| Endpoint | Description |
|---|---|
| https://iso3166-2-api.vercel.app/api/all | Return all subdivision 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 separated 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 separated 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 separated 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 separated list of subdivision names can also be input. |
| https://iso3166-2-api.vercel.app/api/list_subdivisions | Return all subdivision codes for all countries. |
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 ISO 3166-1 2 letter alpha-2, 3 letter alpha-3 or numeric country codes.
A comma separated 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
separated 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 separated
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
separated 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
list subdivision codes
The /list_subdivisions endpoint returns all the subdivision codes for all countries.
https://iso3166-2-api.vercel.app/api/list_subdivisions
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 were solely developed by me : ).