API Tutorial 03 - Publish data to the Open Energy Platform using the API.¶

Learnings¶

This tutorials will enable you to:

• Publish an existing table on the OEP
• Optionally apply an embargo period
• Undo the table publishing

Requirements¶

• have your OEP API token at hand. You find this in settings tab in your profile page. (If you don't have a token see Things you only need to do once.)
• Your tabular data is available on the open energy platform and got oemetadata including an open license (according to the SPDX data license list) in the licenses field.
  • we use the tutorial_example_table_publish from model_draft on the OEP, make sure it exists beforehand. If it is missing try to recreate it using this script TODO.
• Python
• Python packages:
  • requests (See the packages documentation for more help)
  • jupyter notebook, e.g. notebook or jupyterlab
• 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¶

This part of the code sets up all you need to execute the further code below. It imports the required packages into python, sets up the test table and asks you for the OEP API token so that you can identify with the OEP, which is mandatory if you want to upload to the OEP. The setup is a necessary step.

In [5]:

# install required packages with: pip install requests
# import required packages
import json
from getpass import getpass
from os import environ

import requests as req

topic = "model_draft"
table = f"tutorial_example_table"

publish_in_topic = "demand"
token = environ.get("OEP_API_TOKEN") or getpass("Enter your OEP API token:")

# for read/write, we need to add authorization header
auth_headers = {"Authorization": "Token %s" % token}
table_publish_api_url = f"https://openenergyplatform.org/api/v0/schema/{topic}/tables/{table}/move_publish/{publish_in_topic}/"
table_undo_publish_api_url = f"https://openenergyplatform.org/api/v0/schema/{publish_in_topic}/tables/{table}/move_publish/{topic}/"

print(table_publish_api_url)
print(table_undo_publish_api_url)

# install required packages with: pip install requests # import required packages import json from getpass import getpass from os import environ import requests as req topic = "model_draft" table = f"tutorial_example_table" publish_in_topic = "demand" token = environ.get("OEP_API_TOKEN") or getpass("Enter your OEP API token:") # for read/write, we need to add authorization header auth_headers = {"Authorization": "Token %s" % token} table_publish_api_url = f"https://openenergyplatform.org/api/v0/schema/{topic}/tables/{table}/move_publish/{publish_in_topic}/" table_undo_publish_api_url = f"https://openenergyplatform.org/api/v0/schema/{publish_in_topic}/tables/{table}/move_publish/{topic}/" print(table_publish_api_url) print(table_undo_publish_api_url)

https://openenergyplatform.org/api/v0/schema/model_draft/tables/tutorial_example_table/move_publish/demand/
https://openenergyplatform.org/api/v0/schema/demand/tables/tutorial_example_table/move_publish/model_draft/

Optional: Setup an embargo period¶

This part of the code will add an embargo period of either 6 months or 1 year on the published tabular dataset. Since it is also possible to apply an embargo on data that is not yet published, during table creation, this section code also shows how to remove an embargo period that is already active.

Note: It is not possible to set a custom embargo period like embargo": {"start": "2024-08-27", "end": "2024-02-27"} We might consider implementing such a possibility later on.

In [4]:

embargo = {
    "embargo": {"duration": "6_months"},
    # "embargo": None,
}

embargo = { "embargo": {"duration": "6_months"}, # "embargo": None, }

Publish a table¶

This part of the code deletes the table (including the metadata) that you have uploaded to the OEP.

To be able to execute this part you will need to have executed the setup and you will need to have created a table.

In [3]:

# Deleting tables needs authentication headers
res = req.post(table_publish_api_url, json={"query": embargo}, headers=auth_headers)

# raise Exception if request fails
if not res.ok:
    raise Exception(res.text)

# Deleting tables needs authentication headers res = req.post(table_publish_api_url, json={"query": embargo}, headers=auth_headers) # raise Exception if request fails if not res.ok: raise Exception(res.text)

---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[3], line 2
      1 # Deleting tables needs authentication headers
----> 2 res = req.post(table_undo_publish_api_url, headers=auth_headers)
      4 # raise Exception if request fails
      5 if not res.ok:

NameError: name 'table_undo_publish_api_url' is not defined

Revoke a published table¶

This part of the code deletes the table (including the metadata) that you have uploaded to the OEP.

To be able to execute this part you will need to have executed the setup and you will need to have created a table.

In [ ]:

# Deleting tables needs authentication headers
res = req.post(table_undo_publish_api_url, headers=auth_headers)

# raise Exception if request fails
if not res.ok:
    raise Exception(res.text)

# Deleting tables needs authentication headers res = req.post(table_undo_publish_api_url, headers=auth_headers) # raise Exception if request fails if not res.ok: raise Exception(res.text)

About this tutorial¶

• Author: Jonas Huber
• Copyright: Reiner-Lemoine-Institut (2024)
• License: CC BY 4.0
• Attribution: Reiner-Lemoine-Institut (2024): API Tutorial 03 - Publish data to the Open Energy Platform using the API.
• Last update 2024-11-18