# Entsog-py
Python client for the ENTSO-G API (european network of transmission system operators for gas)
Documentation of the API found on https://transparency.entsog.eu/api/archiveDirectories/8/api-manual/TP_REG715_Documentation_TP_API%20-%20v2.1.pdf
Documentation of the data (user manual) found on https://www.entsog.eu/sites/default/files/2021-07/ENTSOG%20-%20TP%20User%20Manual_v_4.5.pdf
Heavily inspired upon (and forked from) https://github.com/EnergieID/entsoe-py
## Installation
```
python3 -m pip install entsog-py
```
## Usage
The package comes with 2 clients:
- [`EntsogRawClient`](#EntsogRawClient): Returns data in its raw format, usually JSON
- [`EntsogPandasClient`](#EntsogPandasClient): Returns data parsed as a Pandas DataFrame
It's preferable to use the Pandas Client as this will handle most API limitations itself. However, if you want to obtain the pure raw data; you can use the raw client.
## Example Use Case
On wwww.gasparency.com you can find example use cases of the data. Almost everything there is achieved with the help of this package!
### <a name="EntsogRawClient"></a>EntsogRawClient
```python
from entsog import EntsogRawClient
import pandas as pd
client = EntsogRawClient()
start = pd.Timestamp('20171201', tz='Europe/Brussels')
end = pd.Timestamp('20180101', tz='Europe/Brussels')
country_code = 'NL' # Netherlands
client.query_connection_points()
client.query_operators()
client.query_balancing_zones()
client.query_operator_point_directions(country_code)
client.query_interconnections()
client.query_aggregate_interconnections()
client.query_urgent_market_messages()
client.query_tariffs(start = start, end = end, country_code = country_code)
client.query_tariffs_sim(start = start, end = end, country_code = country_code)
operational_options = {
interruption_capacity : "Actual interruption of interruptible capacity",
allocation : "Allocation",
firm_available : "Firm Available",
firm_booked : "Firm Booked",
firm_interruption_planned : "Firm Interruption Planned - Interrupted",
firm_interruption_unplanned :"Firm Interruption Unplanned - Interrupted",
firm_technical : "Firm Technical",
gcv : "GCV",
interruptible_available : "Interruptible Available",
interruptible_booked : "Interruptible Booked",
interruptible_interruption_actual : "Interruptible Interruption Actual – Interrupted",
interruptible_interruption_planned : "Interruptible Interruption Planned - Interrupted",
interruptible_total : "Interruptible Total",
nomination : "Nomination",
physical_flow : "Physical Flow",
firm_interruption_capacity_planned : "Planned interruption of firm capacity",
renomination : "Renomination",
firm_interruption_capacity_unplanned : "Unplanned interruption of firm capacity",
wobbe_index : "Wobbe Index",
oversubscription_available : "Available through Oversubscription",
surrender_available : "Available through Surrender",
uioli_available_lt : "Available through UIOLI long-term",
uioli_available_st : "Available through UIOLI short-term"}
client.query_operational_data(start = start, end = end, country_code = country_code, indicator = ['renomination', 'physical_flow'])
```
### <a name="EntsogPandasClient"></a>EntsogPandasClient
The Pandas Client works similar to the Raw Client, with extras:
- API limitations of big requests are automatically dealt with and put into multiple calls.
- Tariffs (and simulated tariffs) can be melted into nice storable format. Instead of having row with EUR, local currency, shared currency for each seperate product, it will create a row for each.
- Operational data can be either requested as in the raw format (which requires some loading time) or in an aggregate function `query_operational_data_all` which will aggressively request all points in Europe and a lot faster.
- It's easier to navigate points, for instance if you want to check gazprom points. See below.
```python
from entsog import EntsogPandasClient
import pandas as pd
client = EntsogPandasClient()
start = pd.Timestamp('20171228', tz='Europe/Brussels')
end = pd.Timestamp('20180101', tz='Europe/Brussels')
country_code = 'NL' # Netherlands
client.query_connection_points()
client.query_operators(country_code)
client.query_balancing_zones()
client.query_operator_point_directions()
client.query_interconnections()
client.query_aggregate_interconnections()
client.query_urgent_market_messages()
client.query_tariffs(start = start, end = end, country_code = country_code, melt = True, verbose = True)
client.query_tariffs_sim(start = start, end = end, country_code = country_code, verbose = True)
client.query_aggregated_data(start = start, end = end, country_code = country_code)
# TODO: Add interruptions...
# client.query_interruptions(start = start, end = end)
client.query_CMP_auction_premiums(start = start, end = end)
client.query_CMP_unavailable_firm_capacity(start = start, end = end)
client.query_CMP_unsuccesful_requests(start = start, end = end)
operational_options = {
'interruption_capacity' : "Actual interruption of interruptible capacity",
'allocation' : "Allocation",
'firm_available' : "Firm Available",
'firm_booked' : "Firm Booked",
'firm_interruption_planned' : "Firm Interruption Planned - Interrupted",
'firm_interruption_unplanned' :"Firm Interruption Unplanned - Interrupted",
'firm_technical' : "Firm Technical",
'gcv' : "GCV",
'interruptible_available' : "Interruptible Available",
'interruptible_booked' : "Interruptible Booked",
'interruptible_interruption_actual' : "Interruptible Interruption Actual – Interrupted",
'interruptible_interruption_planned' : "Interruptible Interruption Planned - Interrupted",
'interruptible_total' : "Interruptible Total",
'nomination' : "Nomination",
'physical_flow' : "Physical Flow",
'firm_interruption_capacity_planned' : "Planned interruption of firm capacity",
'renomination' : "Renomination",
'firm_interruption_capacity_unplanned' : "Unplanned interruption of firm capacity",
'wobbe_index' : "Wobbe Index",
'oversubscription_available' : "Available through Oversubscription",
'surrender_available' : "Available through Surrender",
'uioli_available_lt' : "Available through UIOLI long-term",
'uioli_available_st' : "Available through UIOLI short-term"
}
client.query_operational_data(start = start, end = end, country_code = country_code, indicators = ['renomination', 'physical_flow'])
# You should use this when you want to query operational data for the entirety of continental europe.
client.query_operational_data_all(start = start, end = end, indicators = ['renomination', 'physical_flow'])
# Example for if you would like to see Gazprom points.
points = client.query_operator_point_directions()
mask = points['connected_operators'].str.contains('Gazprom')
masked_points = points[mask]
print(masked_points)
keys = []
for idx, item in masked_points.iterrows():
keys.append(f"{item['operator_key']}{item['point_key']}{item['direction_key']}")
data = client.query_operational_point_data(start = start, end = end, indicators = ['physical_flow'], point_directions = keys, verbose = False)
print(data.head())
```
Raw data
{
"_id": null,
"home_page": "https://github.com/nhcb/entsog-py",
"name": "entsog-py",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "entsog api gas energy",
"author": "Nicky Sonnemans",
"author_email": "nicky.sonnemans@gmail.nl",
"download_url": "https://files.pythonhosted.org/packages/40/5e/bb8cabf799677cd63f9195472e1ca741b21a8554be8af6f481a73ab4b230/entsog-py-1.0.3.tar.gz",
"platform": null,
"description": "# Entsog-py\nPython client for the ENTSO-G API (european network of transmission system operators for gas)\n\nDocumentation of the API found on https://transparency.entsog.eu/api/archiveDirectories/8/api-manual/TP_REG715_Documentation_TP_API%20-%20v2.1.pdf\n\nDocumentation of the data (user manual) found on https://www.entsog.eu/sites/default/files/2021-07/ENTSOG%20-%20TP%20User%20Manual_v_4.5.pdf\n\nHeavily inspired upon (and forked from) https://github.com/EnergieID/entsoe-py \n\n## Installation\n```\npython3 -m pip install entsog-py\n```\n\n## Usage\nThe package comes with 2 clients:\n- [`EntsogRawClient`](#EntsogRawClient): Returns data in its raw format, usually JSON\n- [`EntsogPandasClient`](#EntsogPandasClient): Returns data parsed as a Pandas DataFrame\n\nIt's preferable to use the Pandas Client as this will handle most API limitations itself. However, if you want to obtain the pure raw data; you can use the raw client.\n\n## Example Use Case\nOn wwww.gasparency.com you can find example use cases of the data. Almost everything there is achieved with the help of this package!\n\n### <a name=\"EntsogRawClient\"></a>EntsogRawClient\n```python\nfrom entsog import EntsogRawClient\nimport pandas as pd\n\nclient = EntsogRawClient()\n\nstart = pd.Timestamp('20171201', tz='Europe/Brussels')\nend = pd.Timestamp('20180101', tz='Europe/Brussels')\ncountry_code = 'NL' # Netherlands\n\nclient.query_connection_points()\nclient.query_operators()\nclient.query_balancing_zones()\nclient.query_operator_point_directions(country_code)\nclient.query_interconnections()\nclient.query_aggregate_interconnections()\nclient.query_urgent_market_messages()\nclient.query_tariffs(start = start, end = end, country_code = country_code)\nclient.query_tariffs_sim(start = start, end = end, country_code = country_code)\n\n operational_options = { \n interruption_capacity : \"Actual interruption of interruptible capacity\",\n allocation : \"Allocation\",\n firm_available : \"Firm Available\",\n firm_booked : \"Firm Booked\",\n firm_interruption_planned : \"Firm Interruption Planned - Interrupted\",\n firm_interruption_unplanned :\"Firm Interruption Unplanned - Interrupted\",\n firm_technical : \"Firm Technical\",\n gcv : \"GCV\",\n interruptible_available : \"Interruptible Available\",\n interruptible_booked : \"Interruptible Booked\",\n interruptible_interruption_actual : \"Interruptible Interruption Actual \u2013 Interrupted\",\n interruptible_interruption_planned : \"Interruptible Interruption Planned - Interrupted\",\n interruptible_total : \"Interruptible Total\",\n nomination : \"Nomination\",\n physical_flow : \"Physical Flow\",\n firm_interruption_capacity_planned : \"Planned interruption of firm capacity\",\n renomination : \"Renomination\",\n firm_interruption_capacity_unplanned : \"Unplanned interruption of firm capacity\",\n wobbe_index : \"Wobbe Index\",\n oversubscription_available : \"Available through Oversubscription\",\n surrender_available : \"Available through Surrender\",\n uioli_available_lt : \"Available through UIOLI long-term\",\n uioli_available_st : \"Available through UIOLI short-term\"}\n\nclient.query_operational_data(start = start, end = end, country_code = country_code, indicator = ['renomination', 'physical_flow'])\n\n\n\n\n\n```\n\n### <a name=\"EntsogPandasClient\"></a>EntsogPandasClient\nThe Pandas Client works similar to the Raw Client, with extras:\n- API limitations of big requests are automatically dealt with and put into multiple calls.\n- Tariffs (and simulated tariffs) can be melted into nice storable format. Instead of having row with EUR, local currency, shared currency for each seperate product, it will create a row for each.\n- Operational data can be either requested as in the raw format (which requires some loading time) or in an aggregate function `query_operational_data_all` which will aggressively request all points in Europe and a lot faster.\n- It's easier to navigate points, for instance if you want to check gazprom points. See below.\n\n```python\nfrom entsog import EntsogPandasClient\nimport pandas as pd\n\nclient = EntsogPandasClient()\n\nstart = pd.Timestamp('20171228', tz='Europe/Brussels')\nend = pd.Timestamp('20180101', tz='Europe/Brussels')\ncountry_code = 'NL' # Netherlands\n\nclient.query_connection_points()\nclient.query_operators(country_code)\nclient.query_balancing_zones()\nclient.query_operator_point_directions()\nclient.query_interconnections()\nclient.query_aggregate_interconnections()\nclient.query_urgent_market_messages()\n\n\nclient.query_tariffs(start = start, end = end, country_code = country_code, melt = True, verbose = True)\nclient.query_tariffs_sim(start = start, end = end, country_code = country_code, verbose = True)\n\nclient.query_aggregated_data(start = start, end = end, country_code = country_code)\n# TODO: Add interruptions...\n# client.query_interruptions(start = start, end = end)\nclient.query_CMP_auction_premiums(start = start, end = end)\nclient.query_CMP_unavailable_firm_capacity(start = start, end = end)\n\nclient.query_CMP_unsuccesful_requests(start = start, end = end)\n\noperational_options = { \n 'interruption_capacity' : \"Actual interruption of interruptible capacity\",\n 'allocation' : \"Allocation\",\n 'firm_available' : \"Firm Available\",\n 'firm_booked' : \"Firm Booked\",\n 'firm_interruption_planned' : \"Firm Interruption Planned - Interrupted\",\n 'firm_interruption_unplanned' :\"Firm Interruption Unplanned - Interrupted\",\n 'firm_technical' : \"Firm Technical\",\n 'gcv' : \"GCV\",\n 'interruptible_available' : \"Interruptible Available\",\n 'interruptible_booked' : \"Interruptible Booked\",\n 'interruptible_interruption_actual' : \"Interruptible Interruption Actual \u2013 Interrupted\",\n 'interruptible_interruption_planned' : \"Interruptible Interruption Planned - Interrupted\",\n 'interruptible_total' : \"Interruptible Total\",\n 'nomination' : \"Nomination\",\n 'physical_flow' : \"Physical Flow\",\n 'firm_interruption_capacity_planned' : \"Planned interruption of firm capacity\",\n 'renomination' : \"Renomination\",\n 'firm_interruption_capacity_unplanned' : \"Unplanned interruption of firm capacity\",\n 'wobbe_index' : \"Wobbe Index\",\n 'oversubscription_available' : \"Available through Oversubscription\",\n 'surrender_available' : \"Available through Surrender\",\n 'uioli_available_lt' : \"Available through UIOLI long-term\",\n 'uioli_available_st' : \"Available through UIOLI short-term\"\n}\n\nclient.query_operational_data(start = start, end = end, country_code = country_code, indicators = ['renomination', 'physical_flow'])\n# You should use this when you want to query operational data for the entirety of continental europe.\nclient.query_operational_data_all(start = start, end = end, indicators = ['renomination', 'physical_flow'])\n# Example for if you would like to see Gazprom points.\npoints = client.query_operator_point_directions()\nmask = points['connected_operators'].str.contains('Gazprom')\nmasked_points = points[mask]\nprint(masked_points)\n\nkeys = []\nfor idx, item in masked_points.iterrows():\n keys.append(f\"{item['operator_key']}{item['point_key']}{item['direction_key']}\")\n\ndata = client.query_operational_point_data(start = start, end = end, indicators = ['physical_flow'], point_directions = keys, verbose = False)\n\nprint(data.head())\n\n\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A python API wrapper for transparency.entsog.eu",
"version": "1.0.3",
"split_keywords": [
"entsog",
"api",
"gas",
"energy"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f74b2a56c67ea90e4100848b86d4bea401da640c0af5552ac3fe340ac176d705",
"md5": "6c67196700518736cef5ed8a434ff388",
"sha256": "7f69a60ec532e3060832d1bea781b66f7d1ec6146fd9e2b0887997eaf47c713f"
},
"downloads": -1,
"filename": "entsog_py-1.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6c67196700518736cef5ed8a434ff388",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 24618,
"upload_time": "2023-02-03T15:50:04",
"upload_time_iso_8601": "2023-02-03T15:50:04.904137Z",
"url": "https://files.pythonhosted.org/packages/f7/4b/2a56c67ea90e4100848b86d4bea401da640c0af5552ac3fe340ac176d705/entsog_py-1.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "405ebb8cabf799677cd63f9195472e1ca741b21a8554be8af6f481a73ab4b230",
"md5": "815e2040d357d542a50910782f5762af",
"sha256": "40e4caa06d3c270ebe5d89d0e38d2505a48e9b916384e41f72893d75fbf5723f"
},
"downloads": -1,
"filename": "entsog-py-1.0.3.tar.gz",
"has_sig": false,
"md5_digest": "815e2040d357d542a50910782f5762af",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 25641,
"upload_time": "2023-02-03T15:50:06",
"upload_time_iso_8601": "2023-02-03T15:50:06.706449Z",
"url": "https://files.pythonhosted.org/packages/40/5e/bb8cabf799677cd63f9195472e1ca741b21a8554be8af6f481a73ab4b230/entsog-py-1.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-03 15:50:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "nhcb",
"github_project": "entsog-py",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "entsog-py"
}
JSON
