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.

 

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:

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

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.

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.