DiskovAfrika

The Afrikan Dataset API

(what happened to DiskovAfrika.co?)

Getting started

Encodings

Resources

Helper libraries

Documentation

Introduction

Welcome to the DiskovAfrika, the African Dataset API! This documentation should help you familiarise yourself with the resources available and how to consume them with HTTP requests. If you're after a native helper library then I suggest you scroll down and check out what's available. Read through the getting started section before you dive in. Most of your problems should be solved just by reading through it.

Getting started

Let's make our first API request to the African Dataset API!

Open up a terminal and use curl or httpie to make an API request for a resource. In the example below, we're trying to get all African countries

http diskovafrika.com/api/v1/country

We'll use httpie for our examples as it displays responses nicely and gives us a whole lot more useful information. If you don't want to download httpie, just use the curl command instead.

Here is the response we get:

HTTP/1.0 200 OK
Content-Type: application/json
{
    "admin_division": "8",
    "capital": "Algiers",
    "country_code": "213",
    "date_of_independence": "1962-07-05",
    "id": "db69f4b9-b73d-4d1b-b319-a5fdb9990864",
    "iso_code": "dz",
    "name": "Algeria",
    "num_admin_division": 48,
    "population": 43851044,
    "sub_region": "Northern",
    "utc_zone": "1"
},
{
    "admin_division": "8",
    "capital": "Luanda",
    "country_code": "244",
    "date_of_independence": "1975-11-11",
    "id": "2973889a-4852-4882-ac59-eb83c0b1c4b4",
    "iso_code": "ao",
    "name": "Angola",
    "num_admin_division": 18,
    "population": 32866272,
    "sub_region": "Central",
    "utc_zone": "1"
},
{
    "admin_division": "2",
    "capital": "Cotonou",
    "country_code": "229",
    "date_of_independence": "1960-08-01",
    "id": "7a6432b5-c4c4-48ed-8cd4-5c67d67e02b2",
    "iso_code": "bj",
    "name": "Benin",
    "num_admin_division": 12,
    "population": 12123200,
    "sub_region": "Western",
    "utc_zone": "1"
},
{
    "admin_division": "3",
    "capital": "Gaborone",
    "country_code": "267",
    "date_of_independence": "1966-09-30",
    "id": "bc1e3590-da30-45d3-b051-28b2291d530b",
    "iso_code": "bw",
    "name": "Botswana",
    "num_admin_division": 10,
    "population": 2351627,
    "sub_region": "Southern",
    "utc_zone": "2"
},
{
    "admin_division": "9",
    "capital": "Ouagadougou",
    "country_code": "226",
    "date_of_independence": "1960-08-05",
    "id": "a284b15b-34b9-4973-b115-0ea3bd0908de",
    "iso_code": "bf",
    "name": "Burkina Faso",
    "num_admin_division": 13,
    "population": 20903273,
    "sub_region": "Western",
    "utc_zone": "0"
},
{
    "admin_division": "8",
    "capital": "Bujumbura",
    "country_code": "257",
    "date_of_independence": "1962-07-01",
    "id": "6c95a3dd-9730-48dd-a274-561bee8d0b13",
    "iso_code": "bi",
    "name": "Burundi",
    "num_admin_division": 18,
    "population": 11890784,
    "sub_region": "Eastern",
    "utc_zone": "2"
},
{
    "admin_division": "9",
    "capital": "Yaoundé",
    "country_code": "237",
    "date_of_independence": "1960-01-01",
    "id": "875da6ad-6362-4719-a1da-556e07eb467c",
    "iso_code": "cmr",
    "name": "Cameroon",
    "num_admin_division": 10,
    "population": 26545863,
    "sub_region": "Central",
    "utc_zone": "1"
},
{
    "admin_division": "5",
    "capital": "Praia",
    "country_code": "238",
    "date_of_independence": "1975-07-05",
    "id": "20a3ad7e-97b6-4737-8366-cdbb17045a8f",
    "iso_code": "cv",
    "name": "Cape Verde",
    "num_admin_division": 22,
    "population": 555987,
    "sub_region": "Western",
    "utc_zone": "-1"
},
{
    "admin_division": "7",
    "capital": "Bangui",
    "country_code": "236",
    "date_of_independence": "1960-08-13",
    "id": "e21c9b09-5ad2-41cb-8646-ab3f7ec6d6fb",
    "iso_code": "caf",
    "name": "Central African Republic",
    "num_admin_division": 16,
    "population": 4829767,
    "sub_region": "Central",
    "utc_zone": "1"
},
]

NOTE: All African Countries are not included in the response above

Base URL

The Base URL is the root URL for all of the API, if you ever make a request to DiskovAfrika and you get back a 404 NOT FOUND response then check the Base URL first.

The Base URL for DiskovAfrika is:

https://diskovafrika.com/api/v1

The documentation below assumes you are prepending the Base URL to the endpoints in order to make requests.

Rate limiting

DiskovAfrika has rate limiting to prevent malicious abuse (as if anyone would abuse DiskovAfrika data!) and to make sure our service can handle a potentially large amount of traffic. Rate limiting is done via IP address and is currently limited to 10,000 API request per day. This is enough to request all the data on the website at least ten times over. There should be no reason for hitting the rate limit.

Authentication

DiskovAfrika is a completely open API. No authentication is required to query and get data. This also means that we've limited what you can do to just GET-ing the data. If you find a mistake in the data, then TWEET THE AUTHOR or EMAIL US.

JSON Schema

All resources support JSON Schema. Making a request to /api/<resource>/schema will give you the details of that resource. This will allow you to programmatically inspect the attributes of that resource and their types.

Searching

All resources support a search parameter that filters the set of resources returned. This allows you to make queries like:

https://diskovafrika.com/api/v1/country?search=angola

All searches will use case-insensitive partial matches on the set of search fields. To see the set of search fields for each resource, check out the individual resource documentation. For more information on advanced search terms see here.

Encodings

DiskovAfrika provides one encoding for you to render the data with:

JSON

JSON is the standard data format provided by DiskovAfrika by default.

Resources

Root

The Root resource provides information on all available resources within the API.

Example request:

http https://diskovafrika.com/api/v1

Example response:

HTTP/1.0 200 OK
Content-Type: application/json
{
    "country": "https://diskovafrika.com/api/v1/country/",
    "user": "https://diskovafrika.com/api/v1/user/user_id",
    "dishes": "https://diskovafrika.com/api/v1/country/name/dishes",
    "division": "https://diskovafrika.com/api/v1/country/name/division"
}

Attributes:

  • country string -- The URL root for Country resources
  • user string -- The URL root for User resources
  • dishes string -- The URL root for Dishes resources
  • division string -- The URL root for Division resources

Countries

The Countries Resource shows all 54 African Countries.

Endpoints

  • /country/ -- get all the country resources
  • /country/:name/ -- get a specific country resource
  • /country/:name/division/ -- get the country divisions resource

Example request:

http https://diskovafrika.com/api/v1/country/angola/

Example response:

HTTP/1.0 200 OK
Content-Type: application/json
{
    "admin_division": "8",
    "capital": "Luanda",
    "country_code": "244",
    "date_of_independence": "1975-11-11",
    "id": "2973889a-4852-4882-ac59-eb83c0b1c4b4",
    "iso_code": "ao",
    "name": "Angola",
    "num_admin_division": 18,
    "population": 32866272,
    "sub_region": "Central",
    "utc_zone": "1"
}

Attributes:

  • admin_division string -- The id of admin_divisions in the country
  • capital string -- The capital of the country.
  • country_code string -- The country's postal code
  • date_of_independence string -- The country's independence date.
  • id string -- The country's special id
  • iso_code string -- The iso code of the country.
  • name string -- The name of the Country.
  • num_admin_division string -- The number of divisions in the country.
  • population string -- The Country's population.
  • sub_region string -- Country's region in the African Map.
  • utc_zone string -- Country's TimeZone

Search Fields:

  • name

User

The User information.

Endpoints

  • /user/ -- show the particular user info.

Example request:

http https://diskovafrika.com/api/v1/user/

Example response:

HTTP/1.0 200 OK
Content-Type: application/json
{
    "name": "John Doe"
    "email": "johndoe@yahoo.com"
    "API_KEY": "2973889a-4852-4882-ac59-eb83c0b1c4e5"
}

Attributes:

  • name string -- The name of the User.
  • email integer -- The email of the User.
  • API_KEY string -- The special key to access our services.

Search Fields:

  • user

Dishes

African Dishes List

Endpoints

  • /dishes/ -- get all the dishes resources
  • /country/name/dishes/ -- get a specific country dish resource

Example request:

http https://diskovafrika.com/api/v1/dishes/

Example response:

No Example on this for now!!

Attributes:

Search Fields:

Division

All Administrative Division Resources.

Endpoints

  • /division/ -- get all the division resources
  • /country/division/ -- get a specific division resource

Example request:

http https://diskovafrika.com/api/v1/division/

Example response:

No Example for this now!!

Attributes:

Search Fields:

Helper libraries

There are a bunch of helper libraries available for consuming the DISKOVAFRIKA API in a native programming language.

Python

Created by Trefania, Donald and Emmanuel Maintained by Donald © 2023