GBADs Data Portal Documentation

Introduction

Welcome to the GBADs Data Portal and API. Through this portal you can retrieve any data contained in the GBADs public databases. This public data portal does not require a login or API tokens. The Portal currently contains data from OIE, FAOSTAT, and the Central Statistical Agency of Ethiopia. Other data will be added in the future. This introductory page contains information on how to use the Portal and has a Quick API Guide with common API calls that you can use and adapt.

Using the API

You can use the API in three (3) different ways:

1. As an HTML command where the result will be an html page or a CSV file:
   • https://gbadske.org/api/dataportal/
   • https://gbadske.org/api/GBADsTables/public?format=html
   • https://gbadske.org/api/GBADsLivestockPopulation/faostat?year=2017&country=Canada&species=*&format=file
   
   
2. As a cURL command line tool where the result will be text:
   • On Unix-based systems (Mac OSX, Linux):
     • curl "https://gbadske.org/api/GBADsTables/public?format=text"
     • curl "https://gbadske.org/api/GBADsLivestockPopulation/faostat?year=2017&country=Canada&species=*&format=file"
       where the reponse is:

       country,year,species,population
       "Canada","2017","Beehives","701033"
       "Canada","2017","Cattle","11535000"
       "Canada","2017","Chickens","170120000"
       "Canada","2017","Ducks","1499000"
       "Canada","2017","Geese and guinea fowls","323000"
       "Canada","2017","Goats","30050"
       "Canada","2017","Horses","397870"
       "Canada","2017","Mules","4000"
       "Canada","2017","Pigs","13935000"
       "Canada","2017","Sheep","813900"
       "Canada","2017","Turkeys","5687000"
       "Canada","2017","Cattle and Buffaloes","11535000"
       "Canada","2017","Poultry Birds","177629000"
       "Canada","2017","Sheep and Goats","843950"
       

   • On Windows systems using Powershell where the result will be text:
     • curl.exe https://gbadske.org/api/GBADsTable/public?table_name=livestock_production_faostat&format=text
   
   
3. In an R or Python program:
   • R examples are in GitHub repo (reference to be added)
   • Python example (apiExample.py in GitHub repo - link to be added)

Quick API Guide

These commands are designed to make specific population queries of OIE and FAOSTAT population data and return "country, year, species, population"

• Get OIE population data on Cattle for all years for a specific country, e.g. Germany and return it as a CSV file
  https://gbadske.org/api/GBADsLivestockPopulation/oie?species=Cattle&year=*&country=Germany&format=file
  
  
• Get FAOSTAT population data on Sheep for 2010 for a specific country, e.g. Australia and display as html
  https://gbadske.org/api/GBADsLivestockPopulation/faostat?species=Sheep&year=2010&country=Australia&format=html
  
  
• Get OIE population data on all Poultry categories populations for all years for a specific country, e.g. Switzerland and return it as a CSV file
  https://gbadske.org/api/GBADsLivestockPopulation/oie?species=Poultry&year=*&country=Switzerland&format=file
  
  

API Commands Reference

https://gbadske.org/api/dataportal/

• This will provide documentation about the GBADs Data Portal including how to use the API to the GBADs Public Database.
• It will also give the status of the Data Portal.

https://gbadske.org/api/GBADsTables/public?format=html   |   text

• This command returns the names of all of the tables that exist in the GBADs Public Database. The informationis returned either as a HTML page or as text and this is indicated by the parameter format. If format does not appear then the default is html.
• Example commands:
  • https://gbadske.org/api/GBADsTables/public?format=html
  • https://gbadske.org/api/GBADsTables/public?format=text

https://gbadske.org/api/GBADsTable/public?table_name=table_name&format=html   |   text

• This command returns the column/field names in the given table (). It will be returned as html or as text.
• The type of return is designated by format but this is an optional parameter. If format is not present then the response will be html.
• The required parameter is table name.
• Example commands:
  • https://gbadske.org/api/GBADsTable/public?table_name=eth_csa_goats_health&format=html or https://gbadske.org/api/GBADsTable/public?table_name=eth_csa_goats_health
  • https://gbadske.org/api/GBADsTable/public?table_name=eth_csa_goats_health&format=text

https://gbadske.org/api/GBADsLivestockPopulation/data_source{faostat   |   oie}

• This commands retrieves data from one of the livestock population tables in the public database.
• Currently (as of 2021-10-26) there are two livestock tables: faostat and oie.
• The required parameters are:
  • data_source which is currently either faostat or oie
  • format which is either html or file
• Optional parameters are:
  • year which can be a single year or an * which signifies all years and is the default if year does not appear as a parameter
  • country which can be a country name or an * which signifies all countries and is the default if country does not appear as a parameter
  • iso3 which is the country ISO code (3 characters) or an * which signifies all countries and is the default if iso3 does not appear as a parameter
  • Special notes: Only one of country or iso3 can appear since they refer to the same concept. Also, currently the country/iso3 choice is only implemented for FAOSTAT and not OIE
  • species which can be a species name or an * which signifies all species and is the default if species does not appear as a parameter
• Example commands:
  • https://gbadske.org/api/GBADsLivestockPopulation/faostat?year=2017&country=Canada&species=*&format=html
    • Returns population numbers for all species in Canada in the year 2017 from FAOSTAT (as html)
  • https://gbadske.org/api/GBADsLivestockPopulation/oie?year=2017&country=Canada&species=*&format=html
    • Returns population numbers for all species in Canada in the year 2017 from OIE (as html)
  • https://gbadske.org/api/GBADsLivestockPopulation/oie?year=*&country=Canada&species=Cattle&format=html
    • Returns population numbers for Cattle in Canada in all years from OIE (as html)
  • https://gbadske.org/api/GBADsLivestockPopulation/faostat?iso3=AUS&species=Cattle&format=html
    • Returns population number for Cattle in Australia for all years from FAOSTAT (as html)

https://gbadske.org/api/GBADsPublicQuery/{table_name}

• This command is still a work in progress - to be updated very soon!
• This command performs a general query on a table in the GBADs Public Database.
• The required parameters are
  • table name
  • fields
  • query
  • format
• Example commands:
  • https://gbadske.org/api/GBADsPublicQuery/livestock_production_faostat?fields=country,year,species,population&query=year=2017%20AND%20species=%27Goats%27&format=html
  • https://gbadske.org/api/GBADsPublicQuery/livestock_production_faostat?fields=country,year,species,population&query=year=2017%20AND%20species=%27Goats%27&format=file