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.

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	CO₂ emissions.(in ton)
		notation	String	Notation key (if needed).
		activity_amount_mj	Int or String	Activity data amount (in MJ). If CO₂ is neither zero nor empty, then value is CO₂, 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	CO₂ emissions.
		notation	String	Notation key (if needed).
		activity_amount_mj	Int or String	Total activity data amount (in MJ). If CO₂ is neither zero nor empty, then value is CO₂, 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.

API

Build a Data Portal API URL

API Instructions

City ID Lookup Tool