============
Access data
============

Our Energy API allows you to access all the time series data which are available to you on the API `Docs <https://energy-api.stormgeo.com/docs/>`_ page.
If you want a tutorial to our API using swagger please see our :ref:`swagger <swagger>` page.
For Postman setup please see our :ref:`postman <postman>` page.

Get metadata
======================

Metadata on a time series is available through the API. 
This includes information such as the series ID, description, unit, resolution, 
and the start and end dates of the series.  The /api/v1/metadata endpoint provides metadata on the series and datasets available to you. 
Additionally, many endpoints reference other endpoints that show the 
allowed data values for their parameters. For example, 
the /api/v1/power-balance-forecast/short-term endpoint has a parameter for area, 
and the allowed values can be found at the /api/v1/power-balance-forecast/areas endpoint.



Retrieve data from the API
--------------------------------------

Now lets get trough some examples of how to retrieve data from the API. What we will show first doing a 
request to /api/v1/power-balance-forecast/areas to get a list of allowed area that is allowed and then doing a request to 
/api/v1/power-balance-forecast/short-term to get the forecast data.

.. http:get:: /api/v1/power-balance-forecast/short-term/areas
   :noindex:
   
    List of analyzed domains and codes.

    :Content-Type: application/json
             
           

**Example Request**

.. tabs::

    .. tab:: cURL
    
       .. sourcecode:: bash
       
            curl --location --request GET 'https://energy-api.stormgeo.com/api/v1/power-balance-forecast/areas' \
    
    .. tab:: csharp
    
       .. code-block:: csharp

            const string url = "https://energy-api.stormgeo.com/api/v1/power-balance-forecast/areas";
            var client = new HttpClient();
            var response = await client.GetAsync(url);
            var responseString = await response.Content.ReadAsStringAsync();
            Console.WriteLine($"{responseString}");

    .. tab:: javascript
    
       .. code-block:: javascript
    
            const url = 'https://energy-api.stormgeo.com/api/v1/api/v1/power-balance-forecast/areas';
            
            fetch(url, {
              method: 'GET'
            })
            .then(response => response.json())
            .then(data => console.log(data))
            .catch(error => console.error('Error:', error));
    
    .. tab:: python
    
       .. code-block:: python
    
            import requests
            
            url = "https://energy-api.stormgeo.com/api/v1/power-balance-forecast/areas"
            
            response = requests.get(url)
            print(response.json())


**Example Response**

.. dropdown::

    .. sourcecode:: json
    
        [
          {
            "code": "DE",
            "description": "Germany"
          },
          {
            "code": "AT",
            "description": "Austria"
          },
          {
            "code": "CH",
            "description": "Switzerland"
          },
          {
            "code": "FR",
            "description": "France"
          },
          {
            "code": "ES",
            "description": "Spain"
          },
          {
            "code": "PT",
            "description": "Portugal"
          },
          {
            "code": "IT",
            "description": "Italy"
          },
          {
            "code": "UK",
            "description": "United Kingdom"
          },
          {
            "code": "PL",
            "description": "Poland"
          },
          {
            "code": "CZ",
            "description": "Czech Republic"
          },
          {
            "code": "NL",
            "description": "Netherlands"
          },
          {
            "code": "BE",
            "description": "Belgium"
          },
          {
            "code": "SK",
            "description": "Slovakia"
          },
          {
            "code": "SI",
            "description": "Slovenia"
          },
          {
            "code": "RO",
            "description": "Romania"
          },
          {
            "code": "HU",
            "description": "Hungary"
          },
          {
            "code": "HR",
            "description": "Croatia"
          },
          {
            "code": "FI",
            "description": "Finland"
          },
          {
            "code": "NC",
            "description": "Nordic"
          },
          {
            "code": "DE",
            "description": "Germany"
          },
          {
            "code": "PL",
            "description": "Poland"
          },
          {
            "code": "NL",
            "description": "Netherlands"
          },
          {
            "code": "BE",
            "description": "Belgium"
          },
          {
            "code": "SE1",
            "description": "Sweden SE1"
          },
          {
            "code": "SE2",
            "description": "Sweden SE2"
          },
          {
            "code": "SE3",
            "description": "Sweden SE3"
          },
          {
            "code": "SE4",
            "description": "Sweden SE4"
          },
          {
            "code": "NO1",
            "description": "Norway NO1"
          },
          {
            "code": "NO2",
            "description": "Norway NO2"
          },
          {
            "code": "NO3",
            "description": "Norway NO3"
          },
          {
            "code": "NO4",
            "description": "Norway NO4"
          },
          {
            "code": "NO5",
            "description": "Norway NO5"
          },
          {
            "code": "EE",
            "description": "Estonia"
          },
          {
            "code": "LV",
            "description": "Latvia"
          },
          {
            "code": "LT",
            "description": "Lithuania"
          },
          {
            "code": "GB",
            "description": "Great Britain"
          },
          {
            "code": "RU",
            "description": "Russia "
          },
          {
            "code": "DK1",
            "description": "Denmark DK1"
          },
          {
            "code": "DK2",
            "description": "Denmark DK2"
          }
        ]
    


Retrieve data from the API (continued)
------------------------------------------------------------

for the next example we will do a request to /api/v1/power-balance-forecast/short-term to get the forecast data.

.. http:get:: /api/v1/power-balance-forecast/short-term
   :noindex:
   
    Get short-term model result(s).

     **Note**: You should replace *<your-access-token>* with the bearer token from  :ref:`login request <authentication>`.
    
    :query: 
        .. sourcecode:: json

            {
                "area": "string",
                "balanceCategory": "string",
                "issueTime": "string <date-time>",
                "startDate": "string <date-time>",
                "endDate": "string <date-time>",
                "resolution": "string <enum>",
                "currency": "string <enum>"
            }
    :Content-Type: application/json
    :headers: 
        .. sourcecode:: json

            {"Authorization": "Bearer <your-access-token>"}

   .. dropdown:: query parameters
      :animate: fade-in

      +-------------------+----------------------+-------------------------------------------+
      | **Parameter**     | **Type**             | **Example**                               |
      +-------------------+----------------------+-------------------------------------------+
      | Area              | string               | "DE", "AT", "CH", "NO1"                   |
      +-------------------+----------------------+-------------------------------------------+
      | BalanceCategory   | string               | "hrprice", "hrproduction", "hrcons"       |
      +-------------------+----------------------+-------------------------------------------+
      | IssueTime         | string <date-time>   | "yyyy-MM-ddTHH:mm:ssZ"                    |
      +-------------------+----------------------+-------------------------------------------+
      | StartDate         | string <date-time>   | "yyyy-MM-ddTHH:mm:ssZ"                    |
      +-------------------+----------------------+-------------------------------------------+
      | EndDate           | string <date-time>   | "yyyy-MM-ddTHH:mm:ssZ"                    |
      +-------------------+----------------------+-------------------------------------------+

**Example Request**

.. tabs::

    .. tab:: cURL
    
       .. sourcecode:: bash
       
            curl --location --request GET 'https://energy-api.stormgeo.com/api/v1/power-balance-forecast/short-term?area=<area>&balanceCategory=<balanceCategory>&issueTime=<issueTime>&startDate=<startDate>&endDate=<endDate>&resolution=<resolution>&currency=<currency>' \
            --header 'Authorization: Bearer <your-access-token>'

    .. tab:: csharp

         .. code-block:: csharp
    
                const string url = "https://energy-api.stormgeo.com/api/v1/power-balance-forecast/short-term?area=<area>&balanceCategory=<balanceCategory>&issueTime=<issueTime>&startDate=<startDate>&endDate=<endDate>&resolution=<resolution>&currency=<currency>";
                var client = new HttpClient();
                client.DefaultRequestHeaders.Add("Authorization", "Bearer <your-access-token>");
                var response = await client.GetAsync(url);
                var responseString = await response.Content.ReadAsStringAsync();
                Console.WriteLine($"{responseString}");

    .. tab:: javascript

         .. code-block:: javascript
     
                const url = 'https://energy-api.stormgeo.com/api/v1/power-balance-forecast/short-term?area=<area>&balanceCategory=<balanceCategory>&issueTime=<issueTime>&startDate=<startDate>&endDate=<endDate>&resolution=<resolution>&currency=<currency>';
                const token = '<your-access-token>';
                
                fetch(url, {
                  method: 'GET',
                  headers: {
                 'Authorization': `Bearer ${token}`
                  }
                })
                .then(response => response.json())
                .then(data => console.log(data))
                .catch(error => console.error('Error:', error));
    
    .. tab:: python
    
       .. code-block:: python

            import requests
            
            url = "https://energy-api.stormgeo.com/api/v1/power-balance-forecast/short-term"
            params = {
                'area': '<area>',
                'balanceCategory': '<balanceCategory>',
                'issueTime': '<issueTime>',
                'startDate': '<startDate>',
                'endDate': '<endDate>',
                'resolution': '<resolution>',
                'currency': '<currency>'
            }
            headers = {
                'Authorization': 'Bearer <your-access-token>'
            }
            
            response = requests.get(url, headers=headers, params=params)
            print(response.json())

**Example Response**  
    
    .. dropdown::  
        
        .. sourcecode:: json
          
          {
              "analyzedTime": "2024-09-16T00:00:00Z",
              "data": [
                {
                  "area": "DE",
                  "seriesName": "hrprice",
                  "resolution": "Hourly",
                  "unit": "EUR/MWh",
                  "updateTime": "2024-09-16T08:58:37Z",
                  "validTime": "2024-09-17T00:00:00Z",
                  "value": 87.6671
                },
                {
                  "area": "DE",
                  "seriesName": "hrprice",
                  "resolution": "Hourly",
                  "unit": "EUR/MWh",
                  "updateTime": "2024-09-16T08:58:37Z",
                  "validTime": "2024-09-17T01:00:00Z",
                  "value": 85.275
                },
                {
                  "area": "DE",
                  "seriesName": "hrprice",
                  "resolution": "Hourly",
                  "unit": "EUR/MWh",
                  "updateTime": "2024-09-16T08:58:37Z",
                  "validTime": "2024-09-17T02:00:00Z",
                  "value": 83.6127
                },
                {
                  "area": "DE",
                  "seriesName": "hrprice",
                  "resolution": "Hourly",
                  "unit": "EUR/MWh",
                  "updateTime": "2024-09-16T08:58:37Z",
                  "validTime": "2024-09-17T03:00:00Z",
                  "value": 86.7345
                },
                {
                  "area": "DE",
                  "seriesName": "hrprice",
                  "resolution": "Hourly",
                  "unit": "EUR/MWh",
                  "updateTime": "2024-09-16T08:58:37Z",
                  "validTime": "2024-09-17T04:00:00Z",
                  "value": 89.242
                },
                {
                  "area": "DE",
                  "seriesName": "hrprice",
                  "resolution": "Hourly",
                  "unit": "EUR/MWh",
                  "updateTime": "2024-09-16T08:58:37Z",
                  "validTime": "2024-09-17T05:00:00Z",
                  "value": 88.2724
                },
                {
                  "area": "DE",
                  "seriesName": "hrprice",
                  "resolution": "Hourly",
                  "unit": "EUR/MWh",
                  "updateTime": "2024-09-16T08:58:37Z",
                  "validTime": "2024-09-17T06:00:00Z",
                  "value": 92.6834
                },
                {
                  "area": "DE",
                  "seriesName": "hrprice",
                  "resolution": "Hourly",
                  "unit": "EUR/MWh",
                  "updateTime": "2024-09-16T08:58:37Z",
                  "validTime": "2024-09-17T07:00:00Z",
                  "value": 94.8989
                },
                {
                  "area": "DE",
                  "seriesName": "hrprice",
                  "resolution": "Hourly",
                  "unit": "EUR/MWh",
                  "updateTime": "2024-09-16T08:58:37Z",
                  "validTime": "2024-09-17T08:00:00Z",
                  "value": 92.6364
                },
                {
                  "area": "DE",
                  "seriesName": "hrprice",
                  "resolution": "Hourly",
                  "unit": "EUR/MWh",
                  "updateTime": "2024-09-16T08:58:37Z",
                  "validTime": "2024-09-17T09:00:00Z",
                  "value": 90
                },
                {
                  "area": "DE",
                  "seriesName": "hrprice",
                  "resolution": "Hourly",
                  "unit": "EUR/MWh",
                  "updateTime": "2024-09-16T08:58:37Z",
                  "validTime": "2024-09-17T10:00:00Z",
                  "value": 86.0258
                },
                {
                  "area": "DE",
                  "seriesName": "hrprice",
                  "resolution": "Hourly",
                  "unit": "EUR/MWh",
                  "updateTime": "2024-09-16T08:58:37Z",
                  "validTime": "2024-09-17T11:00:00Z",
                  "value": 80.3679
                },
                {
                  "area": "DE",
                  "seriesName": "hrprice",
                  "resolution": "Hourly",
                  "unit": "EUR/MWh",
                  "updateTime": "2024-09-16T08:58:37Z",
                  "validTime": "2024-09-17T12:00:00Z",
                  "value": 73.4933
                },
                {
                  "area": "DE",
                  "seriesName": "hrprice",
                  "resolution": "Hourly",
                  "unit": "EUR/MWh",
                  "updateTime": "2024-09-16T08:58:37Z",
                  "validTime": "2024-09-17T13:00:00Z",
                  "value": 72.1527
                },
                {
                  "area": "DE",
                  "seriesName": "hrprice",
                  "resolution": "Hourly",
                  "unit": "EUR/MWh",
                  "updateTime": "2024-09-16T08:58:37Z",
                  "validTime": "2024-09-17T14:00:00Z",
                  "value": 72.8494
                },
                {
                  "area": "DE",
                  "seriesName": "hrprice",
                  "resolution": "Hourly",
                  "unit": "EUR/MWh",
                  "updateTime": "2024-09-16T08:58:37Z",
                  "validTime": "2024-09-17T15:00:00Z",
                  "value": 74.3457
                },
                {
                  "area": "DE",
                  "seriesName": "hrprice",
                  "resolution": "Hourly",
                  "unit": "EUR/MWh",
                  "updateTime": "2024-09-16T08:58:37Z",
                  "validTime": "2024-09-17T16:00:00Z",
                  "value": 81.7523
                },
                {
                  "area": "DE",
                  "seriesName": "hrprice",
                  "resolution": "Hourly",
                  "unit": "EUR/MWh",
                  "updateTime": "2024-09-16T08:58:37Z",
                  "validTime": "2024-09-17T17:00:00Z",
                  "value": 94.2654
                },
                {
                  "area": "DE",
                  "seriesName": "hrprice",
                  "resolution": "Hourly",
                  "unit": "EUR/MWh",
                  "updateTime": "2024-09-16T08:58:37Z",
                  "validTime": "2024-09-17T18:00:00Z",
                  "value": 106.703
                },
                {
                  "area": "DE",
                  "seriesName": "hrprice",
                  "resolution": "Hourly",
                  "unit": "EUR/MWh",
                  "updateTime": "2024-09-16T08:58:37Z",
                  "validTime": "2024-09-17T19:00:00Z",
                  "value": 102.903
                },
                {
                  "area": "DE",
                  "seriesName": "hrprice",
                  "resolution": "Hourly",
                  "unit": "EUR/MWh",
                  "updateTime": "2024-09-16T08:58:37Z",
                  "validTime": "2024-09-17T20:00:00Z",
                  "value": 91.8813
                },
                {
                  "area": "DE",
                  "seriesName": "hrprice",
                  "resolution": "Hourly",
                  "unit": "EUR/MWh",
                  "updateTime": "2024-09-16T08:58:37Z",
                  "validTime": "2024-09-17T21:00:00Z",
                  "value": 90.783
                },
                {
                  "area": "DE",
                  "seriesName": "hrprice",
                  "resolution": "Hourly",
                  "unit": "EUR/MWh",
                  "updateTime": "2024-09-16T08:58:37Z",
                  "validTime": "2024-09-17T22:00:00Z",
                  "value": 89.2492
                },
                {
                  "area": "DE",
                  "seriesName": "hrprice",
                  "resolution": "Hourly",
                  "unit": "EUR/MWh",
                  "updateTime": "2024-09-16T08:58:37Z",
                  "validTime": "2024-09-17T23:00:00Z",
                  "value": 85.8938
                },
                {
                  "area": "DE",
                  "seriesName": "hrprice",
                  "resolution": "Hourly",
                  "unit": "EUR/MWh",
                  "updateTime": "2024-09-16T08:58:37Z",
                  "validTime": "2024-09-18T00:00:00Z",
                  "value": 85.2579
                }
              ]
            }