API Tutorial 01 - Download data from the Open Energy Platform using the API¶
Learnings¶
This tutorials will enable you to:
Requirements¶
- Python
- Python packages:
requests(See the packages documentation for more help)- jupyter notebook, e.g.
notebookorjupyterlab shapely(only for geometry data conversion)
- Skills:
- use python with jupyter notebooks
- some understanding of JSON encoded data
- Internet: obviously, but also make sure your network settings allow https traffic from python
Feedback¶
You can provide feedback on this tutorial in this GitHub issue
Setup¶
In [1]:
Copied!
# install required packages with: pip install requests
# import required packages
import json
import requests as req
table = "tutorial_example_table"
table_api_url = f"https://openenergyplatform.org/api/v0/tables/{table}/"
table_web_url = f"https://openenergyplatform.org/database/{table}"
print(f"you can see the table in your browser here: {table_web_url}")
# install required packages with: pip install requests
# import required packages
import json
import requests as req
table = "tutorial_example_table"
table_api_url = f"https://openenergyplatform.org/api/v0/tables/{table}/"
table_web_url = f"https://openenergyplatform.org/database/{table}"
print(f"you can see the table in your browser here: {table_web_url}")
you can see the table in your browser here: https://openenergyplatform.org/database/tutorial_example_table
In [2]:
Copied!
res = req.get(table_api_url + "rows/")
data = res.json()
# show results in notebook
print(json.dumps(data, indent=4))
res = req.get(table_api_url + "rows/")
data = res.json()
# show results in notebook
print(json.dumps(data, indent=4))
[
{
"id": 1,
"name": "unit1",
"is_active": true,
"capacity_mw": 1.2,
"installation_datetime_utc": "2010-02-03T00:00:00",
"location": "01010000008FC2F5285C8F4A40713D0AD7A3B02040"
},
{
"id": 2,
"name": "unit2",
"is_active": false,
"capacity_mw": 2.1,
"installation_datetime_utc": "2010-01-08T00:00:00",
"location": null
},
{
"id": 3,
"name": "unit3",
"is_active": true,
"capacity_mw": 100.0,
"installation_datetime_utc": "2010-01-02T10:30:00",
"location": "0101000000EC51B81E85AB4B405C8FC2F5285C1D40"
}
]
Notes on data types¶
The api returns json serializable data, which is only bool, numerical, or string.
In the example, the value of installation_datetime_utc is a string representation
of a datetime object, the value of location a
WKB
string representation of a geometry object.
Depending on the use case, the data needs to be converted after the download
In [3]:
Copied!
from shapely import wkb
from datetime import datetime
data_converted = []
for row in data:
row_converted = row.copy()
# convert datetime string to datetime object
row_converted["installation_datetime_utc"] = datetime.strptime(
row_converted["installation_datetime_utc"], "%Y-%m-%dT%H:%M:%S"
)
# convert wkb string to shapely geoemtry object
row_converted["location"] = wkb.loads(row_converted["location"])
data_converted.append(row_converted)
from shapely import wkb
from datetime import datetime
data_converted = []
for row in data:
row_converted = row.copy()
# convert datetime string to datetime object
row_converted["installation_datetime_utc"] = datetime.strptime(
row_converted["installation_datetime_utc"], "%Y-%m-%dT%H:%M:%S"
)
# convert wkb string to shapely geoemtry object
row_converted["location"] = wkb.loads(row_converted["location"])
data_converted.append(row_converted)
Download filtered data¶
- requires execution of setup
- read more about query strings
In [4]:
Copied!
# Add (multiple) where filters to the url
filter = "where=is_active=true&where=capacity_mw>10"
res = req.get(table_api_url + f"rows/?{filter}")
data = res.json()
# show results in notebook
print(json.dumps(data, indent=4))
# Add (multiple) where filters to the url
filter = "where=is_active=true&where=capacity_mw>10"
res = req.get(table_api_url + f"rows/?{filter}")
data = res.json()
# show results in notebook
print(json.dumps(data, indent=4))
[
{
"id": 3,
"name": "unit3",
"is_active": true,
"capacity_mw": 100.0,
"installation_datetime_utc": "2010-01-02T10:30:00",
"location": "0101000000EC51B81E85AB4B405C8FC2F5285C1D40"
}
]
In [5]:
Copied!
res = req.get(table_api_url + "meta/")
metadata = res.json()
# show (partial) results in notebook
print(json.dumps(metadata, indent=4))
res = req.get(table_api_url + "meta/")
metadata = res.json()
# show (partial) results in notebook
print(json.dumps(metadata, indent=4))
{
"@id": null,
"name": null,
"title": null,
"@context": "https://raw.githubusercontent.com/OpenEnergyPlatform/oemetadata/production/oemetadata/v2/v20/context.json",
"resources": [
{
"@id": null,
"name": "tutorial_example_table",
"path": "test_table",
"type": "Table",
"title": null,
"format": null,
"review": {
"path": null,
"badge": null
},
"schema": {
"fields": [
{
"name": "id",
"type": "bigint",
"unit": null,
"isAbout": [
{
"@id": null,
"name": null,
"openModalButton": null
}
],
"nullable": false,
"description": "numerical id of this data point",
"valueReference": [
{
"@id": null,
"name": null,
"value": null,
"openModalButton": null
}
]
},
{
"name": "name",
"type": "varchar(18)",
"unit": null,
"isAbout": [
{
"@id": null,
"name": null,
"openModalButton": null
}
],
"nullable": true,
"description": "name of installation",
"valueReference": [
{
"@id": null,
"name": null,
"value": null,
"openModalButton": null
}
]
},
{
"name": "is_active",
"type": "boolean",
"unit": null,
"isAbout": [
{
"@id": null,
"name": null,
"openModalButton": null
}
],
"nullable": true,
"description": "true/false if installation is active",
"valueReference": [
{
"@id": null,
"name": null,
"value": null,
"openModalButton": null
}
]
},
{
"name": "capacity_mw",
"type": "float",
"unit": null,
"isAbout": [
{
"@id": null,
"name": null,
"openModalButton": null
}
],
"nullable": true,
"description": "installed capacity in MW",
"valueReference": [
{
"@id": null,
"name": null,
"value": null,
"openModalButton": null
}
]
},
{
"name": "installation_datetime_utc",
"type": "timestamp",
"unit": null,
"isAbout": [
{
"@id": null,
"name": null,
"openModalButton": null
}
],
"nullable": true,
"description": "date (and time) when installation was build",
"valueReference": [
{
"@id": null,
"name": null,
"value": null,
"openModalButton": null
}
]
},
{
"name": "location",
"type": "geometry",
"unit": null,
"isAbout": [
{
"@id": null,
"name": null,
"openModalButton": null
}
],
"nullable": true,
"description": "point location of installation",
"valueReference": [
{
"@id": null,
"name": null,
"value": null,
"openModalButton": null
}
]
}
],
"primaryKey": [
null
],
"foreignKeys": [
{
"fields": [
null
],
"reference": {
"fields": [
null
],
"resource": null
}
}
]
},
"topics": [
null
],
"context": {
"title": null,
"contact": null,
"grantNo": null,
"homepage": null,
"publisher": null,
"sourceCode": null,
"documentation": null,
"fundingAgency": null,
"publisherLogo": null,
"fundingAgencyLogo": null
},
"dialect": {
"delimiter": null,
"decimalSeparator": null
},
"sources": [
{
"path": null,
"title": null,
"authors": [
null
],
"description": null,
"sourceLicenses": [
{
"name": null,
"path": null,
"title": null,
"attribution": null,
"instruction": null,
"copyrightStatement": null
}
],
"publicationYear": null
}
],
"spatial": {
"extent": {
"@id": null,
"crs": null,
"name": null,
"boundingBox": [
0,
0,
0,
0
],
"resolutionUnit": null,
"resolutionValue": null
},
"location": {
"@id": null,
"address": null,
"latitude": null,
"longitude": null
}
},
"subject": [
{
"@id": null,
"name": null,
"openModalButton": null
}
],
"encoding": null,
"keywords": [
"energy",
"installations",
"geo"
],
"licenses": [
{
"name": "CC-BY-4.0",
"path": "https://creativecommons.org/licenses/by/4.0/legalcode",
"title": "Creative Commons Attribution 4.0 International",
"attribution": null,
"instruction": "You are free to share and adapt, but you must attribute. See https://creativecommons.org/licenses/by/4.0/deed.en for further information.",
"copyrightStatement": null
}
],
"temporal": {
"timeseries": [
{
"end": null,
"start": null,
"alignment": null,
"resolutionUnit": null,
"aggregationType": null,
"resolutionValue": null
}
],
"referenceDate": null
},
"languages": [
null
],
"description": null,
"contributors": [
{
"date": null,
"path": null,
"roles": [
null
],
"title": null,
"object": null,
"comment": null,
"organization": null
}
],
"embargoPeriod": {
"end": null,
"start": null,
"isActive": false
},
"publicationDate": null
}
],
"description": null,
"metaMetadata": {
"metadataLicense": {
"name": "CC0-1.0",
"path": "https://creativecommons.org/publicdomain/zero/1.0/",
"title": "Creative Commons Zero v1.0 Universal"
},
"metadataVersion": "OEMetadata-2.0.4"
}
}
About this tutorial¶
- Title: API Tutorial 01 - Download data from the Open Energy Platform using the API
- Authors: Christian Winger
- Copyright: Öko-Institut (2024)
- License: CC BY 4.0
- Attribution: Öko-Institut (2024): API Tutorial 01- Download data from the Open Energy Platform using the API.
- Link: https://openenergyplatform.github.io/academy/tutorials/01_api/01_api_download/
- Version: 1.0
- Last update 2025-11-29
- Keywords: API, OEP
- Language: en