Last Updated: April 2024
Developer/Maintainer: AJ

About

The ISO 3166 Updates API is a custom-built, open-source and free to use API for the iso3166-updates repo that returns the latest and historical updates/changes to the ISO 3166-1 and ISO 3166-2 country codes and naming conventions, as per the ISO 3166 newsletter (https://www.iso.org/iso-3166-country-codes.html) and Online Browsing Platform (OBP) (https://www.iso.org/obp/ui).

A demo of the API and Python software is available here.
Source code available here.

Attributes

There are four main attributes returned from the API:

  • Edition/Newsletter: name and or edition of newsletter that the ISO 3166 change/update was communicated in (pre 2013), or the link to the country's ISO Online Browsing Platform page.
  • Date Issued: date that the change was communicated.
  • Code/Subdivision change: overall summary of change/update made.
  • Description of change: more in-depth info about the change/update that was made.

Endpoints

The ISO 3166 Updates API currently has 5 main endpoints, /all, /alpha, /name, /year and /months:

Endpoint Description
https://iso3166-updates.com/api/all Return all updates/changes to a country/territory and its subdivision data and naming conventions for all countries listed in the ISO 3166.
https://iso3166-updates.com/api/alpha/{input_alpha} Return all updates/changes to a country/territory and its subdivision data and naming conventions for input ISO 3166-1 alpha-2, alpha-3 or numeric country codes. A comma separated list of country codes can also be input.
https://iso3166-updates.com/api/name/{input_name} Return all updates/changes to a country/territory and its subdivision data and naming conventions for input country name, as it is commonly known in English. A comma separated list of country names can also be input.
https://iso3166-updates.com/api/year/{input_year} Return all updates/changes to all countries/territories and their subdivision data and naming conventions for a particular year, list of years, year range or all updates less than or greater than an input year.
https://iso3166-updates.com/api/alpha/{input_alpha}/year/{input_year}, https://iso3166-updates.com/api/year/{input_year}/alpha/{input_alpha} Return all updates/changes to a country/territory and its subdivision data and naming conventions for input ISO 3166-1 alpha-2, alpha-3 or numeric country code, for an input year, list of years, year range or all updates less than or greater than an input year. A comma separated list of country codes can also be input.
https://iso3166-updates.com/api/name/{input_name}/year/{input_year}, https://iso3166-updates.com/api/year/{input_year}/name/{input_name} Return all updates/changes to a country/territory and its subdivision data and naming conventions for input country name, as it is commonly known in English, for an input year, list of years, year range or all updates less than or greater than an input year. A comma separated list of country names can also be input.
https://iso3166-updates.com/api/months/{input_months} Return all updates/changes to all countries/territories and their subdivision data and naming conventions from the previous number of months from the present day, inclusive, e.g. /api/months/12 will return all updates for all countries from the past 12 months. The endpoint can also accept a month range which will get all updates/changes that were published within the specified range, e.g. /api/months/12-36.
https://iso3166-updates.com/api/months/{input_months}/alpha/{input_alpha}, https://iso3166-updates.com/api/alpha/{input_alpha}/months/{input_months} Return all updates/changes to a country/territory and its subdivision data and naming conventions for input ISO 3166-1 alpha-2, alpha-3 or numeric country codes from the previous number of months from the present day, inclusive, e.g. /api/months/36/alpha/EG will return all updates for Egypt from the past 36 months.

All

The /api/all endpoint returns all updates/changes data for all countries/territories in the ISO 3166. The list of countries supported is according to the ISO 3166-1 standard.

https://iso3166-updates.com/api/all

Alpha

The /api/alpha endpoint returns all updates/changes to a country/territory and its subdivision data and naming conventions for an input ISO 3166-1 alpha-2, alpha-3 or numeric country code. A comma separated list of country codes can also be input. This endpoint can also be used in conjunction with the /api/year and /api/months endpoints.

https://iso3166-updates.com/api/alpha/{input_alpha}

https://iso3166-updates.com/api/alpha/AD
https://iso3166-updates.com/api/alpha/DE
https://iso3166-updates.com/api/alpha/MEX
https://iso3166-updates.com/api/alpha/PRY
https://iso3166-updates.com/api/alpha/DE,674
https://iso3166-updates.com/api/alpha/MEX,768
https://iso3166-updates.com/api/alpha/PR/year/2018
https://iso3166-updates.com/api/alpha/TO,TW,TV/months/24

Name

The /api/name endpoint returns all updates/changes to a country/territory and its subdivision data and naming conventions for an input country name, as it is commonly known in English. A comma separated list of country names can also be input. This endpoint can also be used in conjunction with the /api/year and /api/months endpoints.

https://iso3166-updates.com/api/name/{input_name}

https://iso3166-updates.com/api/name/Ireland
https://iso3166-updates.com/api/name/Jamaica
https://iso3166-updates.com/api/name/Panama,Rwanda,Zambia
https://iso3166-updates.com/api/name/Tajikistan/year/2015-2022
https://iso3166-updates.com/api/name/Senegal,Suriname,Sri lanka/months/60

Year

The /api/year endpoint returns all updates/changes to all countries/territories and their subdivision data and naming conventions for a particular year, list of years, year range or all updates less than or greater than an input year. This endpoint can also be used in conjunction with the /api/alpha and /api/name endpoints.

https://iso3166-updates.com/api/year/{input_year}

https://iso3166-updates.com/api/year/2014
https://iso3166-updates.com/api/year/2007,2011,2022
https://iso3166-updates.com/api/year/2000-2005
https://iso3166-updates.com/api/year/<2021
https://iso3166-updates.com/api/year/>2005/alpha/AF,LV,UG

Months

The /api/months endpoint returns all updates/changes to all countries/territories and their subdivision data and naming conventions from an input number of months from the present day, inclusive, e.g. /api/months/12 will return all updates for all countries from the past 12 months. The endpoint can also accept a month range to get updates/changes from. The endpoint can also be used in conjunction with the /api/alpha and /api/name endpoints.

https://iso3166-updates.com/api/months/{input_months}

https://iso3166-updates.com/api/months/12
https://iso3166-updates.com/api/months/24
https://iso3166-updates.com/api/months/6-24
https://iso3166-updates.com/api/months/6/alpha/FR
https://iso3166-updates.com/api/months/60/alpha/DZA,MDA,POL

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