API

The Data Portal for Cities API offers free and open access to city greenhouse gas inventory emission data sets for use on websites, applications, and spreadsheets.

The API follows common standards and format (JSON) and allows developers and climate action professionals to export data from the Data Portal for Cities on a point-by-point basis or by extracting entire city datasets following the GCoM CRF (Global Covenant of Mayors Common Reporting Framework).

The API offers access to all data points available across all cities and available years through a unique string in the form of an internet address (URL). When applying the URL in applications and documents, developers and users may pull data for use in their own context and make sure all data points are updated when new data sets become available on the Data Portal for Cities or when existing data are updated.

Every city on the Data Portal has a unique ID of 7-8 digits. To allow developers and other users to pull data for the intended city, the API allows to look up IDs used in the Data Portal for use in the construction of specific strings. 

Developer instructions
The Data Portal for Cities API is a JSON compliant and straight forward to integrate on websites, applications, and spreadsheets. Please refer to the section API Instructions for details. In implementing data from the Data Portal for Cities, unique city IDs are needed to construct working URL strings. For that purpose, you may make use of the city lookup tool, or you may request a list of IDs for cities in a specific country or region. Please direct requests to: info@dataportalforcities.org and allow two weekdays for delivery.

 

Build a Data Portal API URL

API Instructions

The Data Portal for Cities API page allows users to retrieve emission data ether point by point or as full data sets for a given city using a single URL. When accessing API URLs directly it is advisable to make use of a JSON formatter in your browser to get an orderly output. There are several free options available, e.g., the JSON formatter extension to Chrome.

The Data Portal API URL construction
A valid API URL string is constructed as follows:

https://dataportalforcities.org/api/emissions?city_id=[city_idvalue]&year=[year]&sector=[sector]&scope=[scope]

Address base
The first (green) part of the string is mandatory and serves as the URL address of the API.

City_id
The city_id (blue) part of the string is mandatory and refers to the ID of the city in question. Every city on Data Portal for Cities is assigned a 6–8-digit city ID to make sure cities across the globe are identified correctly and equally named cities not confused. To lookup a specific city ID, simply use the City Lookup Tool. For more information, see the section City Lookup Tool Instructions.

Year
The year parameter (orange) simply refers to the year of the compiled data. The data parameter can be omitted, in which case data from the most recent year will be returned as default.

Sector
Valid string inputs cover all sectors and sub sectors that are part of the CRF inventory format. Sectors and subsectors must be applied exact:

  Stationary energy Transport Waste
  Residential buildings On-road Solid waste disposal
  Commercial buildings & facilities Rail Biological treatment
  Institutional buildings & facilities Waterborne navigation Incineration and open burning
  Industrial buildings & facilities Aviation Wastewater
  Agriculture Off-road  
  Fugitive emissions    

 

  IPPU AFOLU Generation of grid-supplied energy Total emissions
  Industrial process Livestock Electricity-only generation  
  Produce use Land use CHP Generation  
    Other AFOLU Heat/cold generation  
      Local renewable generation  

 

 

 

 

 

Scope
Scope (red) refers to ether direct or indirect emissions – or the total of both. Valid values are simply:

direct
indirect
total

Usage Examples
The Data Portal for Cities API opens various ways of retrieving data. Here just a few examples:
 

Example: Retrieve all emission data of a specific city

https://dataportalforcities.org/api/emissions?cityid=2618424&scope=total

 

Example: Retrieve the total emission of a sector

https://dataportalforcities.org/api/emissions?scope=total&cityid=2618424&sector=Residential buildings

 

Example: Retrieve direct emission of a specific sub sector

https://dataportalforcities.org/api/emissions?cityid=2618424&year=2015&sector=Institutional%20buildings%20%26%20facilities&scope=direct

 

Output parameters
The Data Portal for Cities API returns detailed data depending on the request. Here is the full overview of output:

Name

Type

Description

cityid

Int

ID of the current city.

city_name

String

Name of the current city.

adm1id

Int

ADM1 of the current city.

adm1_name

String

ADM1 name of the current city.

countryid

Int

Country id of the current city.

country_name

String

Country name of the current city.

regionid

Int

Region id of the current city.

region_name

String

Region name of the current city.

year

Int

Year of the data being returned.

data

Array

Array with emissions by sector.

population

int

City population.

 

sector

String

Sector name.

 

sector_code

String

Code of the sector.

 

emissions

Array

Array with emissions by subsector.

 

 

co2e_total_ton

Int or String

CO2 emissions.(in ton)

 

 

notation

String

Notation key (if needed).

 

 

activity_amount_mj

Int or String

Activity data amount (in MJ). If CO2 is neither zero nor empty, then value is CO2, otherwise value is notation.

 

 

subsector

String

Subsector name.

 

 

subsector_code

String

Subsector code.

 

total

Array

Array with sector summatory emissions.

 

 

co2e_total_ton

Int or String

CO2 emissions.

 

 

notation

String

Notation key (if needed).

 

 

activity_amount_mj

Int or String

Total activity data amount (in MJ). If CO2 is neither zero nor empty, then value is CO2, otherwise value is notation.

 

 

 


 

 

 

 

 

 

 

 


 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Error codes
All response codes are returned in the status code of the https response header.

200: Request was processed.

400: Bad request. One of the requested parameters is not valid.

404: One of the requested elements was not found.

City ID Lookup Tool

The City ID Lookup Tool allows free and simple access to lookup the Data Portal for Cities ID of any city represented on the portal. The tool can easily be implemented as a distributed service and is found at: 

https://dataportalforcities.org/city/picker

Using the tool
City ID Lookup Tool is designed for simplicity and easy implementation. It is recommended to implement the tool using the HTML <iframe> tag. In content management systems look for Insert external object or similar. The tool is scalable and easily fits mobile and full-scale browsers alike.

City ID for entire countries or regions
When planning to make use of data from The Data Portal for Cities for an entire country or region, a list of IDs can come in handy. Please direct request to: info@dataportalforcities.org.