API How To



Step 1: Make a request


To make a request use the base URL with one of the endpoint paths appended


Base URL


http://data.footprintnetwork.org/api/b1/{endpoint}


Endpoints


/countries A country is a geo political region that data is related to
/years A year is a calendar year in which the data was gathered
/types A type is a category of data or 'record type'
/data A datum is a dataset of data as specified using type, countries and years

Step 2: Get a Response


Responses are returned in xml or json depending on the Accept header sent with the request


Accept: application/json Returns data in json format
Accept: application/xml Returns data in xml format



Countries:


Geo political regions for which we have data available


Base URL


http://data.footprintnetwork.org/api/b1/{endpoint}


Endpoints


Path Description
http://data.footprintnetwork.org/api/b1/countries Returns a list of countries for which data is available.
http://data.footprintnetwork.org/api/b1/countries/count Returns a count of available countries

Data


Data fields Description
countryCode unique identifier for country
countryName Country name

Examples


Fetch Available Countries

http://data.footprintnetwork.org/api/b1/countries

Fetch the number of available countries

http://data.footprintnetwork.org/api/b1/countries/count



Years:


Calendar years for which data is available


Endpoints


Path Description
http://data.footprintnetwork.org/api/b1/years Returns a list of countries for which data is available.
http://data.footprintnetwork.org/api/b1/years/count Returns a count of available countries

Data


Data fields Description
Year Calendar Year

Examples


Fetch Available Countries

http://data.footprintnetwork.org/api/b1/years

Fetch the number of available countries

http://data.footprintnetwork.org/api/b1/years/count



Types:



Endpoints


Path Description
http://data.footprintnetwork.org/api/b1/types Returns a list of record types for which data is available.
http://data.footprintnetwork.org/api/b1/types/count Returns a count of available record types

Data


Data fields Description
code Short record type code
name record type name
note Description of record type
record Long record type code

Examples


Fetch available record types

http://data.footprintnetwork.org/api/b1/types

Fetch the number of available record types

http://data.footprintnetwork.org/api/b1/types/count



Data:



Endpoints


Path Description
http://data.footprintnetwork.org/api/b1/data Not used
http://data.footprintnetwork.org/api/b1/data/{countryCode}/{year} returns data specified by countryCode and year
http://data.footprintnetwork.org/api/b1/data/{countryCode}/{year}/{record} returns data specified by countryCode, year and record

Parameters


Parameters Example Description
countryCode 2 Unique id of country taken from countries list or 'all' for all countries Note: All counties and all years is not available
year 1999 Calendar year taken from years list or 'all' for all years Note: All counties and all years is not available
record pop Record type taken from types list or 'all'

Data


Data fields Description
countryName Name of country
countryCode Unique identifier of country
isoa2 ISO 3166-1 Alpha 2 Country Code
year Calendar year
record Data type
value numeric value of data point

Land Type Data


Some Records may also contain Land Type data


Data fields Description
builtupLand Built-up land in gha
carbon Carbon Footprint in gha
cropLand Cropland in gha
fishingGround Fishing Grounds in gha
forestland Forest land in gha
grazingLand Grazing land in gha

Link to definitions page


Examples


Fetch data for Afghanistan for the year 1999

http://data.footprintnetwork.org/api/b1/data/2/1999

Fetch data for all counties in for the year 2000

http://data.footprintnetwork.org/api/b1/data/all/2000


Fetch data for all years for Afghanistan

http://data.footprintnetwork.org/api/b1/data/2/all

Fetch only Biocapacity per person and Population for Afghanistan in the year 1998

http://data.footprintnetwork.org/api/b1/data/2/1998/BCpc,pop