API

The main API endpoint displays the API documentation and homepage and forms the base URL for the 5 other endpoints: https://iso3166-updates.vercel.app/api

The other endpoints available in the API are:

Below are some example usage of the API and the above endpoints, utilising the Python Requests library.

Query String Parameters

There are 3 main query string parameters available throughout the API that can be appended to your GET request:

  • likeness - this is a parameter 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 be used with 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/canton?likeness=90 (default=100).

  • sortBy - this parameter allows you to sort the output results by publication date (Date Issued), ascending or descending. By default, the updates data will be returned alphabetically, according to their ISO 3166 2 letter country code. The parameter accepts the values: dateAsc and dateDesc, which will sort the objects ascending or descending, respectively. A countryCode attribute is added to each object to identify the corresponding country. This can be appended to all of the endpoints, e.g /api/all?sortBy=dateAsc /api/year/2010-2015?sortBy=dateDesc, /api/date_range/2019-01-01?sortBy (default=””).

  • excludeMatchScore - this parameter allows you to 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, but setting this parameter to True will exclude the attribute and sort the results by country code, e.g /api/search/addition?excludeMatchScore=1, /api/search/New York?excludeMatchScore=1 (default=0).

Get all ISO 3166 updates for all countries and years

Return all the latest and historic ISO 3166 updates data for all available countries and publication years, using the /api/all endpoint.

import requests

base_url = "https://iso3166-updates.vercel.app/api"
all_data = requests.get(f'{base_url}/all').json()

all_data["AD"] #updates data for Andorra
all_data["DJ"] #updates data for Djibouti
all_data["IE"] #updates data for Ireland
all_data["PW"] #updates data for Palau

curl:

$ curl -i https://iso3166-updates.vercel.app/api/all

Get all ISO 3166 updates for a country using its ISO 3166-1 alpha code (alpha-2, alpha-3, numeric)

Return all the latest and historic ISO 3166 updates data for 1 or more countries, using their ISO 3166-1 2 letter alpha-2, 3 letter alpha-3 or numeric country codes via the /api/alpha endpoint. The endpoint also accepts a comma separated list of multiple alpha country codes.

For example, France (FR,FRA,250), Germany (DE,DEU,276) and Hungary (HU,HUN,348):

import requests

base_url = "https://iso3166-updates.vercel.app/api"

#FR - France
input_alpha = "FR"
fr_updates_data = requests.get(f'{base_url}/alpha/{input_alpha}').json()
fr_updates_data["FR"]

#DEU - Germany
input_alpha = "DEU"
de_updates_data = requests.get(f'{base_url}/alpha/{input_alpha}').json()
de_updates_data["DE"]

#348 - Hungary
input_alpha = "348"
hu_updates_data = requests.get(f'{base_url}/alpha/{input_alpha}').json()
hu_updates_data["HU"]

curl:

$ curl -i https://iso3166-updates.vercel.app/api/alpha/FR
$ curl -i https://iso3166-updates.vercel.app/api/alpha/DEU
$ curl -i https://iso3166-updates.vercel.app/api/alpha/348
$ curl -i https://iso3166-updates.vercel.app/api/alpha/FR,DEU,348

This endpoint can also be used in conjunction with the /api/year and /api/date_range endpoints.

Get all ISO 3166 updates for a country using its country name

Return all the latest and historic ISO 3166 updates data for 1 or more countries, using their ISO 3166-1 country name, as it is most commonly known in English, via the /api/country_name endpoint. The endpoint also accepts a comma separated list of multiple country names.

For example, Tajikistan (TJ,TJK,762), Seychelles (SC,SYC,690) and Uganda (UG,UGA,800):

import requests

base_url = "https://iso3166-updates.vercel.app/api/"

#Tajikistan
input_name = "Tajikistan"
tajikistan_updates_data = requests.get(base_url + f'country_name/{input_country_name}').json()
tajikistan_updates_data["TJ"]

#Seychelles
input_name = "Seychelles"
seychelles_updates_data = requests.get(base_url + f'country_name/{input_country_name}').json()
seychelles_updates_data["SC"]

#Uganda
input_name = "Uganda"
seychelles_updates_data = requests.get(base_url + f'country_name/{input_country_name}').json()
uganda_updates_data["UG"]

curl:

$ curl -i https://iso3166-updates.vercel.app/api/country_name/Tajikistan
$ curl -i https://iso3166-updates.vercel.app/api/country_name/Seychelles
$ curl -i https://iso3166-updates.vercel.app/api/country_name/Uganda
$ curl -i https://iso3166-updates.vercel.app/api/country_name/Tajikistan,Seychelles,Uganda

This endpoint can also be used in conjunction with the /api/year endpoint.

Get all ISO 3166 updates from a year or list of years

Return all the ISO 3166 updates data that were published in a specific year or list of years, using the /api/year endpoint. The endpoint can also accept a comma separated list of years.

For example, 2004 and 2007:

import requests

base_url = "https://iso3166-updates.vercel.app/api/"

#2004
input_year = "2004"
_2004_updates = requests.get(f'{base_url}year/{input_year}').json()

#2007
input_year = "2007"
_2007_updates = requests.get(f'{base_url}year/{input_year}').json()

#2004,2007
input_year = "2004,2007"
_2004_2007_updates = requests.get(f'{base_url}year/{input_year}').json()

curl:

$ curl -i https://iso3166-updates.vercel.app/api/year/2004
$ curl -i https://iso3166-updates.vercel.app/api/year/2007
$ curl -i https://iso3166-updates.vercel.app/api/year/2004,2007

Get all ISO 3166 updates from a year range

Return all the ISO 3166 updates data that were published within a specific year range, using the /api/year endpoint. Sort output by publication date (Date Issued) via the sortBy query string parameter.

For example, 2009-2015 and 2001-2008:

import requests

base_url = "https://iso3166-updates.vercel.app/api/"

#2009-2015, sort by date descending
input_year = "2009-2015"
_2009_2015_updates = requests.get(f'{base_url}year/{input_year}', params={"sortBy": "dateDesc"}).json()

#2001-2008, sort by date ascending
input_year = "2001-2008"
_2001_2008_updates = requests.get(f'{base_url}year/{input_year}', params={"sortBy": "dateAsc"}).json()

curl:

$ curl -i https://iso3166-updates.vercel.app/api/year/2009-2015?sortBy=dateDesc
$ curl -i https://iso3166-updates.vercel.app/api/year/2001-2008?sortBy=dateAsc

Get all ISO 3166 updates greater than or less than a year

Return all ISO 3166 updates that were published less than or greater than an input year using the /api/year endpoint, sort by publication date.

For example, <2010 and >2012:

import requests

base_url = "https://iso3166-updates.vercel.app/api/"

#<2010
input_year = "<2010"
lt_2010 = requests.get(f'{base_url}year/{input_year}').json()

#>2012
input_year = ">2012"
gt_2012 = requests.get(f'{base_url}year/{input_year}').json()

curl:

$ curl -i https://iso3166-updates.vercel.app/api/alpha/year/<2010
$ curl -i https://iso3166-updates.vercel.app/api/alpha/year/>2012

Get all ISO 3166 updates, excluding a year or list of years

Return all ISO 3166 updates that exclude the input publication year or list of years using the /api/year endpoint.

For example, <>2020, <>2004

import requests

base_url = "https://iso3166-updates.vercel.app/api/"

#<>2020
input_year = "<>2020"
ne_2020 = requests.get(f'{base_url}year/{input_year}').json()

#<>2004
input_year = "<>2004"
ne_2004 = requests.get(f'{base_url}year/{input_year}').json()

curl:

$ curl -i https://iso3166-updates.vercel.app/api/alpha/year/<>2020
$ curl -i https://iso3166-updates.vercel.app/api/alpha/year/<>2004

Get all ISO 3166 updates for a country and year

Return all ISO 3166 updates for an input country that were published in a year, list of years, year range, greater than or less than a specified year or not equal to a year/list of years, using the endpoint /api/alpha/{input_alpha}/year/{input_year} or /api/year/{input_year}/alpha/{input_alpha}.

For example, Andorra - 2007, Argentina - 2010, 2015, 2017, Bulgaria - 2003-2008, Ecuador - <2019 and Japan - <>2018:

import requests

base_url = "https://iso3166-updates.vercel.app/api/"

#Andorra - 2007
input_alpha = "AD"
input_year = "2007"

request_url = base_url + f"alpha/{input_alpha}/year/{input_year}"
ad_2007 = requests.get(request_url).json()

#Argentina 2010, 2015, 2017
input_alpha = "AR"
input_year = "2010, 2015, 2017"

request_url = base_url + f"alpha/{input_alpha}/year/{input_year}"
ar_2010_2015_2017 = requests.get(request_url).json()

#Bulgaria - 2003-2008
input_alpha = "BG"
input_year = "2003-2008"

request_url = base_url + f"alpha/{input_alpha}/year/{input_year}"
bg_2003_2008 = requests.get(request_url).json()

#Ecuador - <2019
input_alpha = "EC"
input_year = "<2019"

request_url = base_url + f"alpha/{input_alpha}/year/{input_year}"
ec_lt_2019 = requests.get(request_url).json()

#Japan - <>2018
input_alpha = "JP"
input_year = "<>2018"

request_url = base_url + f"alpha/{input_alpha}/year/{input_year}"
jp_ne_2018 = requests.get(request_url).json()

curl:

$ curl -i https://iso3166-updates.vercel.app/api/alpha/AD/year/2007
$ curl -i https://iso3166-updates.vercel.app/api/alpha/AR/year/2010,2015,2017
$ curl -i https://iso3166-updates.vercel.app/api/alpha/BG/year/2003-2008
$ curl -i https://iso3166-updates.vercel.app/api/alpha/EC/year/<2019
$ curl -i https://iso3166-updates.vercel.app/api/alpha/JP/year/<>2018

Get all ISO 3166 updates for all countries from a specified date range, inclusive

Return all available country’s ISO 3166 updates data that were published within the specified date range, inclusive, using the /api/date_range endpoint.

For example, publication dates within the date range 2005-11-05 to 2007-08-09, and from 2018-05-05:

import requests

base_url = "https://iso3166-updates.vercel.app/api"

#2005-11-05 to 2007-08-09:
input_date_range = "2005-11-05,2007-08-09"
request_url = f'{base_url}/date_range/{input_date_range}'
date_range = requests.get(request_url).json()

#2018-05-05
input_date_range = "2018-05-05"
request_url = f'{base_url}/date_range/{input_date_range}'
date_range = requests.get(request_url).json()

curl:

$ curl -i https://iso3166-updates.vercel.app/api/date_range/'2005-11-05,2007-08-09'
$ curl -i https://iso3166-updates.vercel.app/api/date_range/2018-05-05

Search for all ISO 3166 updates that have specific keywords

Return all the ISO 3166 updates data who’s changes/description of change attributes feature the inputted search terms, using the /api/search endpoint. The query string parameter likeness sets a % of likeness that the input search term can be to the matching updates, by default a likeness of 100 (an exact match) is used. If a date is explicitly input to the search function, the Date Issued column will additionally be added to the search space. The outputs from the search are ordered by match_score, highest match first. This score can be excluded from the output by setting the excludeMatchScore to 1, meaning the outputs will be ordered alphabetically by country code.

For example, searching for all updates that have “Parishes” or “Canton” in them:

import requests

base_url = "https://iso3166-updates.vercel.app/api/"

#search for Parishes, exact match
input_search = "Parishes"
request_url = base_url + f"search/{input_search}"
search_result = requests.get(request_url).json()

#search for Canton, 80% match, exclude % match score
input_search = "Canton"
request_url = base_url + f"search/{input_search}"
search_result = requests.get(request_url, params={"likeness": "80", "excludeMatchScore": "1"}).json()

curl:

$ curl -i https://iso3166-updates.vercel.app/api/search/Parish
$ curl -i https://iso3166-updates.vercel.app/api/search/Canton?likeness=80&excludeMatchScore=1

Note

A demo of the software and API is available here.