API How To

Step 1: Get and API Key

You can get your personal api key here: API Key

Note: if you have previously requested an api key using the same email address, requesting a new key will disable the old key.

Step 2: Add your API key to the Auth Header

Add your api key to the password field of a basic authentication request. The user name of the basic auth request can be any string.

Using curl, it will look something like this:

curl -u any-user-name:<api key>  http://data.footprintnetwork.org/api/v1/types

A full curl query might look like this:

curl -X GET -H "Accept: application/json" -u any-user-name:<api key>  http://data.footprintnetwork.org/api/v1/types

Using php it will look something like this:

<?php

$login = 'any-login';
$password = '<api key>';
$request =  'http://data.footprintnetwork.org/api/v1/types';

// Initialize the session
$session = curl_init($request);

// Set curl options
curl_setopt($session, CURLOPT_HEADER, true);
curl_setopt($session, CURLOPT_RETURNTRANSFER, true);
curl_setopt($session, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($session, CURLOPT_USERPWD, "$login:$password");

// Add this if you want json
curl_setopt($session, CURLOPT_HTTPHEADER,array('Accept: application/json') );

// Make the request
$response = curl_exec($session);

// Close the curl session
curl_close($session);

echo($response);

?>

Step 3: 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/v1/{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 4: 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 data is available

Base URL

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

Endpoints

Path Description
http://data.footprintnetwork.org/api/v1/countries Returns a list of countries for which data is available.
http://data.footprintnetwork.org/api/v1/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/v1/countries

Fetch the number of available countries http://data.footprintnetwork.org/api/v1/countries/count

Years

Calendar years for which data is available

Endpoints

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

Data

Data fields Description
Year Calendar Year

Examples

Fetch Available Countries http://data.footprintnetwork.org/api/v1/years

Fetch the number of available countries http://data.footprintnetwork.org/api/v1/years/count

Types

Record types for which data is available

Endpoints

Path Description
http://data.footprintnetwork.org/api/v1/types Returns a list of record types for which data is available.
http://data.footprintnetwork.org/api/v1/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/v1/types

Fetch the number of available record types http://data.footprintnetwork.org/api/v1/types/count

Data

Data access using country, year and type parameters

Endpoints

Path Description
http://data.footprintnetwork.org/api/v1/data Not used
http://data.footprintnetwork.org/api/v1/data/{countryCode}/{year} returns data specified by countryCode and year
http://data.footprintnetwork.org/api/v1/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/v1/data/2/1999

Fetch data for all counties in for the year 2000 http://data.footprintnetwork.org/api/v1/data/all/2000

Fetch data for all years for Afghanistan http://data.footprintnetwork.org/api/v1/data/2/all

Fetch only Biocapacity per person and Population for Afghanistan in the year 1998 http://data.footprintnetwork.org/api/v1/data/2/1998/BCpc,pop

API Key Request Form

Please fill out Form below to receive an API Key