Skip to content

Extract data (historical profile and grid topology) through the Grid Singularity Historical Data and Grid Data APIs

Historical Data API

The Historical Data API has been developed by Grid Singularity to allow users to retrieve the assets’ historical data in a given simulation, such as loads (consumption profiles) or generation profiles. This information can be used, for instance, by trading agents to adapt the assets’ trading settings to optimise the asset owner’s savings / revenue from these assets.

This API requires the following parameters:

  • Simulation_id: This is the ID of the simulation or the Grid Singularity Canary Test Network, and can be found in the url on the Grid Singularity user interface (UI) (see Fig. 1)
  • Market_uuid: This is the ID of the asset or market of the energy community for which the historical information is to be retrieved. It can also be found in the url on the Grid Singularity UI (see Fig. 1)
  • Start_time and end_time: This is the time period for which the historical information is downloaded

You can then connect to the API with the following URL, which divides the parameters with a slash (/):

https://gsyweb.gridsingularity.com/historical-data/assets/{simulation_id}/{market_uuid}/{start_time}/{end_time}

Grid Data API

Grid Singularity has developed the Grid Data API to provide information about the topology of a simulated energy community, listing the relevant attributes and connections for each energy asset.

This API requires the following parameters:

You can then connect to the API with the following URL, which divides the parameters with a slash (/):

https://gsyweb.gridsingularity.com/external-connection/configurations/{simulation_id}/registry

The response will include the following data:

  • Uuid: unique identifier of each asset
  • Name: name of each asset
  • Type: type of each asset
  • Aggregator: name of the aggregator that manages the asset, if any
  • Attributes: any relevant asset attributes

We will gradually add more data points to the response of the Grid Data API, for instance the geographic location (longitude and latitude) of each asset.

alt_text Figure 1: Screenshot of a simulation url, which includes the simulation_id and the market_uuid parameters in the Grid Singularity UI

Connect to the data APIs

Perform a request using Postman

Postman is a widely used API client that enables you to save your requests as well as share settings with others. To use Postman with this API, the first step is to create a “collection” that contains all settings needed to perform a request to the Historical Data API.

To install and set up a collection on postman, please follow these steps:

  1. Download and install app from Postman

  2. Import attached collection:

    • Download the collection file here.
    • Go to File > Import and click on Upload Files, select the collection file that you just downloaded and click on Import.

    VIDEO

    • Change user credentials in the pre-request scripts

    VIDEO

    • Adapt the url with the wanted parameters following the description mentioned above and press Send (the results should be shown in the Body tab of the response):

    VIDEO

    • (Optional) Save the response as a json file clicking on Save Response on the right side.

Perform a request using a Python script

Alternatively, you can directly use Python to make a request to the API. For this method, please follow this steps:

  1. Import the library and set the parameters of your simulation
import requests

username = "<your_user>"
password = "<your_password>"

domain = "https://gsyweb.gridsingularity.com"
simulation_id = "990abe5e-3126-4b8b-9978-66ca07824d3c"
market_uuid = "a245cff8-d90a-44d9-82e5-d37999b62e04"
start_date = "2021-09-25T00:00"
end_date = "2021-10-01T00:00"
  1. Generate your JWT token
response = requests.post(url=domain + "/api-token-auth/",
                         json={"username": username, "password": password})

token = response.json()["token"]
  1. Create a URL and send the request:
historical_data_url = f"{domain}/historical-data/assets/{configuration_id}/{asset_id}/{start_date}/{end_date}"
headers = {"Authorization": f"JWT {token}"}

response = requests.get(url=historical_data_url,
                        headers=headers)

profile = response.json()