About

The ISO 3166 Updates API is a custom-built, open-source and free to use RESTful 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.
A Medium article is available here.

Attributes

There are four main attributes returned from the API:

  • Change: overall summary of change/update made.
  • Description of Change: more in-depth info about the change/update that was made.
  • Date Issued: date that the change was published/communicated.
  • Source: 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.

Query String Parameters

There are three main query string parameters that can be passed through several of the endpoints of the API:

  • sortBy: sort the output results by publication date (Date Issued), either descending or ascending. By default, the updates data will be returned alphabetically, according to ISO 3166 2 letter country code, but you can order by date. The parameter accepts two values: dateDesc and dateAsc - sorting the output by date descending or ascending, respectively. If an invalid value input then the output is sorted by country code. This can be appended to all of the endpoints, e.g /api/all?sortBy=dateDesc, /api/year/2010-2015?sortBy=dateAsc, /api/date_range/2019-01-01?sortBy="" (sorted by country code).
  • 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 updates data in the Change and Desc of Change attributes. This can only be used in the /api/search endpoint. 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/canton?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 updates 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/addition?excludeMatchScore=1, /api/search/New York?excludeMatchScore=1 (default=0).

Endpoints

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

All

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

https://iso3166-updates.vercel.app/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/date_range endpoints.

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

https://iso3166-updates.vercel.app/api/alpha/AD
https://iso3166-updates.vercel.app/api/alpha/DE
https://iso3166-updates.vercel.app/api/alpha/MEX
https://iso3166-updates.vercel.app/api/alpha/PRY
https://iso3166-updates.vercel.app/api/alpha/DE,674
https://iso3166-updates.vercel.app/api/alpha/MEX,768
https://iso3166-updates.vercel.app/api/alpha/PR/year/2018
https://iso3166-updates.vercel.app/api/alpha/TO,TW,TV/date_range/2003-01-01,2009-01-01

Country Name

The /api/country_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 endpoint.

https://iso3166-updates.vercel.app/api/country_name/{input_country_name}

https://iso3166-updates.vercel.app/api/country_name/Ireland
https://iso3166-updates.vercel.app/api/country_name/Jamaica
https://iso3166-updates.vercel.app/api/country_name/Panama,Rwanda,Zambia
https://iso3166-updates.vercel.app/api/country_name/Tajikistan/year/2015-2022

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, all updates less than or greater than an input year or updates excluding an input year. This endpoint can also be used in conjunction with the /api/alpha endpoint.

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

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

Date Range

The /api/date_range endpoint returns all updates/changes to all countries/territories and their subdivision data and naming conventions from a specified date range, inclusive; e.g. /api/date_range/2007-08-08,2007-12-31 will return all updates for all countries from the 8th Aug 2007 until 31st Dec 2007, inclusive. The endpoint can also accept single date value which will act as the starting point to get updates from, with the present day being the end date. The endpoint can also be used in conjunction with the /api/alpha endpoint.

https://iso3166-updates.vercel.app/api/date_range/{input_date_range}

https://iso3166-updates.vercel.app/api/date_range/2004-06-12,2010-09-20?sortBy=dateDesc
https://iso3166-updates.vercel.app/api/date_range/2012-02-17,2012-12-31
https://iso3166-updates.vercel.app/api/date_range/2019-12-18
https://iso3166-updates.vercel.app/api/date_range/2002-08-23,2010-11-10/alpha/FR
https://iso3166-updates.vercel.app/api/date_range/2000-01-01/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 are solely developed and maintained by me : ).