Skip to content

Commit

Permalink
updating api, unit tests
Browse files Browse the repository at this point in the history
  • Loading branch information
@amckenna41
amckenna41 committed Oct 23, 2023
1 parent f3239b4 commit ac72b20
Show file tree
Hide file tree
Showing 10 changed files with 329 additions and 661 deletions.
10 changes: 6 additions & 4 deletions .github/workflows/build_test.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,11 +41,13 @@ jobs:
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip3 install pytest
pip3 install pytest-cov
pip3 install bandit
pip3 install safety
pip install pytest
pip install pytest-cov
pip install bandit
pip install safety
pip install codecov
pip install iso3166-2
pip install importlib-metadata
pip install beautifulsoup4
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
Expand Down
111 changes: 17 additions & 94 deletions API.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,19 +13,17 @@ The other endpoints available in the API are:

Three paths/endpoints are available in the API - `/api/all`, `/api/alpha2` and `/api/name`.

* The `/api/all` path/endpoint returns all of the ISO 3166 country data for all countries (due to the size of the object this can take some time to load).
* The `/api/all` path/endpoint returns all of the ISO 3166 subdivision data for all countries.

* The 2 letter alpha-2 country code can be appended to the **alpha2** path/endpoint e.g <i>/api/alpha2/JP</i>. A single alpha-2 or list of them can be passed to the API e.g <i>/api/alpha2/FR,DE,HU,ID,MA</i>. For redudancy, the 3 letter alpha-3 counterpart for each country's alpha-2 code can also be appened to the path e.g <i>/api/alpha2/FRA,DEU,HUN,IDN,MAR</i>. If an invalid alpha-2 code is input then an error will be returned.

* The name parameter can be a country name as it is most commonly known in english, according to the ISO 3166-1. The name can similarly be appended to the **name** path/endpoint e.g <i>/api/name/Denmark</i>. A single country name or list of them can be passed into the API e.g <i>/name/France,Moldova,Benin</i>. A closeness function is utilised so the most approximate name from the input will be used e.g Sweden will be used if <i>/api/name/Swede</i>. If no country is found from the closeness function or an invalid name is input then an error will be returned.

* The main API endpoint (`/` or `/api`) will return the homepage and API documentation.

The `filter` query string parameter can be appended to any of the endpoints. It accepts a string of one or more attributes that the user wants to only be returned from their request e.g <i>/api/alpha2/IE?filter=capital,currencies,languages,region</i>. This example means that only the capital city, currencies, languages and region data for Ireland will be returned. If an invalid attribute name is input then it will be removed from the request.

The full list of attributes available for each country are available in the [ATTRIBUTES.md][attributes] file.

The API documentation and usage with all useful commands and examples to the API is available below. A demo of the software and API are available [here][demo].
The API documentation and usage with all useful commands and examples to the API is available on the [API.md][api_md] file. A demo of the software and API are available [here][demo].

Get All ISO 3166-2 updates for all countries
-------------------------------------------
Expand All @@ -39,7 +37,7 @@ Get All ISO 3166-2 updates for all countries
content-type: application/json
date: Tue, 20 Dec 2022 17:29:39 GMT
server: Vercel
content-length: 202273
content-length: 837958

{"AD":..., "AE":...}

Expand All @@ -66,7 +64,7 @@ function getData() {
var data = JSON.parse(this.response)
```

Get all country and ISO 3166-2 data for a specific country, using its 2 letter alpha-2 code e.g FR, DE, HN
Get all ISO 3166-2 subdivision data for a specific country, using its 2 letter alpha-2 code e.g FR, DE, HN
----------------------------------------------------------------------------------------------------------

### Request
Expand All @@ -79,9 +77,9 @@ Get all country and ISO 3166-2 data for a specific country, using its 2 letter a
content-type: application/json
date: Tue, 20 Dec 2022 17:30:27 GMT
server: Vercel
content-length: 4513
content-length: 26298

{"FR":[{"altSpellings":"", "area": "", "borders": ""...}]}
{"FR":{"FR-01":{...}}}

### Request
`GET /api/alpha2/DE`
Expand All @@ -93,9 +91,9 @@ Get all country and ISO 3166-2 data for a specific country, using its 2 letter a
content-type: application/json
date: Tue, 20 Dec 2022 17:31:19 GMT
server: Vercel
content-length: 10
content-length: 3053

{"DE":[{"altSpellings":"", "area": "", "borders": ""...}]}
{"DE":{"DE-BB":{...}}}

### Request
`GET /api/alpha2/HN`
Expand All @@ -107,9 +105,9 @@ Get all country and ISO 3166-2 data for a specific country, using its 2 letter a
content-type: application/json
date: Tue, 20 Dec 2022 17:31:53 GMT
server: Vercel
content-length: 479
content-length: 2708

{"HN":[{"altSpellings":"", "area": "", "borders": ""...}]}
{"HN":{"HN-AT":{...}}}

### Python
```python
Expand Down Expand Up @@ -138,7 +136,7 @@ function getData() {
var data = JSON.parse(this.response)
```

Get all country and ISO 3166-2 data for a specific country, using country name, e.g. Tajikistan, Seychelles, Uganda
Get all ISO 3166-2 subdivision data for a specific country, using country name, e.g. Tajikistan, Seychelles, Uganda
-------------------------------------------------------------------------------------------------------------------

### Request
Expand All @@ -151,9 +149,9 @@ Get all country and ISO 3166-2 data for a specific country, using country name,
content-type: application/json
date: Tue, 20 Dec 2022 17:40:19 GMT
server: Vercel
content-length: 10
content-length: 701

{"TJ":[{"altSpellings":"", "area": "", "borders": ""...}]}
{"TJ":{"TJ-DU":{...}}}

### Request
`GET /api/name/Seychelles`
Expand All @@ -165,9 +163,9 @@ Get all country and ISO 3166-2 data for a specific country, using country name,
content-type: application/json
date: Tue, 20 Dec 2022 17:41:53 GMT
server: Vercel
content-length: 479
content-length: 5085

{"SC":[{"altSpellings":"", "area": "", "borders": ""...}]}
{"SC":{"SC-01":{...}}}

### Request
`GET /api/name/Uganda`
Expand All @@ -179,9 +177,9 @@ Get all country and ISO 3166-2 data for a specific country, using country name,
content-type: application/json
date: Tue, 21 Dec 2022 19:43:19 GMT
server: Vercel
content-length: 10
content-length: 14965

{"UG":[{"altSpellings":"", "area": "", "borders": ""...}]}
{"UG":{"UG-101":{...}}}

### Python
```python
Expand Down Expand Up @@ -210,81 +208,6 @@ function getData() {
var data = JSON.parse(this.response)
```

Get area, population and timezones attributes for a specific country, using its 2 letter alpha-2 code e.g LA, PA, RO
--------------------------------------------------------------------------------------------------------------------

### Request
`GET /api/alpha2/LA?filter=area,population,timezones`

curl -i https://iso3166-2-api.vercel.app/api/alpha2/LA?filter=area,population,timezones

### Response
HTTP/2 200
content-type: application/json
date: Sat, 23 Sep 2023 12:56:44 GMT
server: Vercel
content-length: 70

{"LA":{"area":236800,"population":7275556,"timezones":["UTC+07:00"]}}

### Request
`GET /api/alpha2/PA?filter=area,population,timezones`

curl -i https://iso3166-2-api.vercel.app/api/alpha2/PA?filter=area,population,timezones

### Response
HTTP/2 200
content-type: application/json
date: Sat, 23 Sep 2023 12:57:34 GMT
server: Vercel
content-length: 70

{"PA":{"area":75417,"population":4314768,"timezones":["UTC-05:00"]}}

### Request
`GET /api/alpha2/RO`

curl -i https://iso3166-2-api.vercel.app/api/alpha2/RO?filter=area,population,timezones

### Response
HTTP/2 200
content-type: application/json
date: Sat, 23 Sep 2023 12:58:54 GMT
server: Vercel
content-length: 71

{"RO":{"area":238391,"population":19286123,"timezones":["UTC+02:00"]}}

### Python
```python
import requests

base_url = "https://iso3166-2-api.vercel.app/api/"
input_alpha2 = "LA" #PA, RO

request_url = base_url + f"alpha2/{input_alpha2}"

all_request = requests.get(request_url, params={"filter": "area,population,timezones"})
all_request.json()
```

### Javascript
```javascript
let input_alpha2 = "LA"; //PA, RO

function getData() {
const response =
await fetch(`https://iso3166-updates.com/api/alpha2/${input_alpha2}` +
new URLSearchParams({
filter: "area,population,timezones"
}));
const data = await response.json()
}

// Begin accessing JSON data here
var data = JSON.parse(this.response)
```

[Back to top](#TOP)

[attributes]: https://github.com/amckenna41/iso3166-2-api/ATTRIBUTES.md
Expand Down
58 changes: 6 additions & 52 deletions ATTRIBUTES.md
View file
Original file line number Diff line number Diff line change
@@ -1,54 +1,8 @@
| Field | Info |
|------------------------|------|
| altSpellings / altNames | Alternate spellings and names of country name |
| area | Geographical size (km^2) |
| borders | Border countries |
| capital | Capital city/cities |
| capitalInfo > latlng | Capital city latitude and longitude |
| car > side | Car driving side |
| car > signs | Car distinguised (oval) signs |
| cca2 / alpha2Code | ISO 3166-1 alpha-2 two-letter country code |
| cca3 / alpha3Code | ISO 3166-1 alpha-3 three-letter country code |
| ccn3 / numericCode | ISO 3166-1 numeric code (UN M49) |
| cioc | Code of the International Olympic Committee |
| coatOfArms > png | [MainFacts.com](https://mainfacts.com/coat-of-arms-countries-world) link to png of country's coat of arms |
| coatOfArms > svg | [MainFacts.com](https://mainfacts.com/coat-of-arms-countries-world) link to svg of country's coat of arms |
| continents | List of continents the country is on |
| currencies > name | List of country's currency names |
| currencies > symbol | List of country's currency's international symbol |
| demonym | Name for the inhabitants of the country |
| demonyms > m/f | Genderized inhabitants of the country in English and native languages |
| fifa | FIFA code |
| flag | Unicode flag emoji (https://flagpedia.net/emoji)|
| flags > alt | Image alt text description for flag |
| flags > png | [Flagpedia](https://flagpedia.net/) link to png of country flag |
| flags > svg | [Flagpedia](https://flagpedia.net/) link to svg of country flag |
| gini | Worldbank [Gini](https://data.worldbank.org/indicator/SI.POV.GINI) index |
| idd > root | International dialing/calling code root |
| idd > suffix | International dialing/calling code suffix |
| independent | ISO 3166-1 independence status (the country is considered a sovereign state) |
| landlocked | Landlocked country (true/false) |
| languages | List of official languages |
| latlng | Latitude and longitude |
| maps > googleMaps | Link to country on Google Maps |
| maps > openStreetMaps | Link to country on Open Street Maps |
| name > common | Common country name in English |
| name > nativeName | Native country name |
| name > nativeName > official/common | Official and common country name in native language |
| name > official | Official country name |
| population | Country population |
| postalCodes > format/regex | Country postal code format |
| region | UN [demographic regions](https://unstats.un.org/unsd/methodology/m49/) |
| startOfWeek | Day of the start of week (Sunday/Monday) |
| status | ISO 3166-1 assignment status |
| subdivisions | List of a country's [ISO3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) subdivision names and codes |
| subdivisions > flag_url | URL to subdivision's flag on [iso3166-flag-icons](https://github.com/amckenna41/iso3166-flag-icons) repo, if applicable |
| subdivisions > latlng | Coordinates for subdivision, using the Google Maps API |
| subdivisions > name | Name of subdivision |
| subdivisions > parent_code | Parent code of subdivision |
| subdivisions > type | Parent code of subdivision |
| subregion | UN [demographic subregions](https://unstats.un.org/unsd/methodology/m49/) |
| timezones | Timezones |
| tld / topLevelDomain | Internet top level domain |
| translations > official/common | List of official and common country name in translated languages |
| unMember | UN Member status |

| flag_url | URL to subdivision's flag on [iso3166-flag-icons](https://github.com/amckenna41/iso3166-flag-icons) repo, if applicable |
| latlng | Coordinates for subdivision, using the Google Maps API |
| name | Name of subdivision |
| parent_code | Parent code of subdivision |
| type | Subdivision type |
Loading

1 comment on commit ac72b20

@vercel
Copy link

@vercel vercel bot commented on ac72b20 Oct 23, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Successfully deployed to the following URLs:

iso3166-2-api – ./

iso3166-2-api-git-main-amckenna41.vercel.app
iso3166-2-api.vercel.app
iso3166-2-api-amckenna41.vercel.app

Please sign in to comment.