{"id":35180580,"url":"https://github.com/tideseed/eptr2","last_synced_at":"2026-05-24T09:03:04.589Z","repository":{"id":208979877,"uuid":"719082827","full_name":"Tideseed/eptr2","owner":"Tideseed","description":"EPIAS Transparency Platform API / EPİAŞ Şeffaflık Platformu API ","archived":false,"fork":false,"pushed_at":"2026-04-03T06:46:38.000Z","size":2206,"stargazers_count":20,"open_issues_count":0,"forks_count":3,"subscribers_count":6,"default_branch":"main","last_synced_at":"2026-04-03T08:49:33.931Z","etag":null,"topics":["api","electricity","epias","markets"],"latest_commit_sha":null,"homepage":"https://robokami.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Tideseed.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2023-11-15T12:18:24.000Z","updated_at":"2026-04-03T06:46:42.000Z","dependencies_parsed_at":"2026-04-03T00:02:42.692Z","dependency_job_id":null,"html_url":"https://github.com/Tideseed/eptr2","commit_stats":null,"previous_names":["tideseed/eptr2"],"tags_count":52,"template":false,"template_full_name":null,"purl":"pkg:github/Tideseed/eptr2","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tideseed%2Feptr2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tideseed%2Feptr2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tideseed%2Feptr2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tideseed%2Feptr2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Tideseed","download_url":"https://codeload.github.com/Tideseed/eptr2/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tideseed%2Feptr2/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31461534,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T21:22:52.476Z","status":"online","status_checked_at":"2026-04-06T02:00:07.287Z","response_time":112,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","electricity","epias","markets"],"created_at":"2025-12-29T01:17:30.560Z","updated_at":"2026-04-06T06:01:38.589Z","avatar_url":"https://github.com/Tideseed.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![PyPI - Version](https://img.shields.io/pypi/v/eptr2) ![PyPI - Downloads](https://img.shields.io/pypi/dm/eptr2) ![PyPI - Python Version](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Ftideseed%2Feptr2%2Fmain%2Fpyproject.toml\n) ![PyPI - License](https://img.shields.io/pypi/l/eptr2)\n\n**!! IMPORTANT: Starting from 1.3.3 there will be some breaking changes due to regulatory changes by EPDK. Overhaul is planned to finish with the next mid release 1.4.0**\n\n**!! CRITICAL: Due to authentication method changes you are strongly recommended to update the eptr2 version to 1.2.4+**\n\n**Note: From 1.3.0 and onwards, eptr2 starts to evolve to be an AI oriented tool. You can use it as an MCP server, directly use them in your LLMs and AI agents to write your code for you.**\n\n# Quickstart\n\nThis document is a quickstart guide for `eptr2` package. It is a Python client for [EPIAS Transparency Platform v2.0](https://seffaflik.epias.com.tr/home) API. It is an unofficial package with Apache License 2.0.\n\n+ For live demo, please visit \u003chttps://eptr2demo.streamlit.app/\u003e\n+ For local demo, you can run `eptr2demo` at terminal after installing the library.\n\n\n# MCP Server Quick Reference\n\n+ You can use Claude Desktop configuration to connect to the MCP server in VS Code as well. See Claude Desktop configuration details [here](https://modelcontextprotocol.io/docs/develop/connect-local-servers).\n+ Make sure in VS Code settings `chat.mcp.discovery.enabled` is enabled and `chat.mcp.access` is set to the correct value. See details in [VS Code documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers).\n\n\n## Installation\n\nRECOMMENDED: Install `eptr2` with \"allextras\" option to get additional features. Extras currently include `pandas` and `streamlit` libraries. You can install the package with the following command.\n\n```bash\npip install \"eptr2[allextras]\"\n```\n\n**Note:** The `[allextras]` option includes MCP server support for AI agent integration, along with pandas and streamlit.\n\nOtherwise you can easily install it from PyPI with the following commmand.\n\n```bash\npip install eptr2\n```\n\nYou can also use `uv` tool to install the package with extras or plain.\n\n```bash\nuv pip install \"eptr2[allextras]\"\n```\n\n```bash\nuv pip install eptr2\n```\n\n## Usage\n\nYou can simply use `EPTR2` class to call services with convenience methods. You need to [register](https://kayit.epias.com.tr/epias-transparency-platform-registration-form) with the [EPIAS Transparency Platform](https://seffaflik.epias.com.tr/) to get your username (i.e. registration email) and password. The platform also accommodates an English version.\n\nBelow is an example of getting Market Clearing Price (MCP) / Piyasa Takas Fiyatı (PTF). All services use the same pattern.\n\n```python\nfrom eptr2 import EPTR2\n\neptr = EPTR2(\n    username=\"YOUR_USERNAME\", password=\"YOUR_PASSWORD\"\n)\n\nres = eptr.call(\"mcp\", start_date=\"2024-07-29\", end_date=\"2024-07-29\")\n```\n\nThere are more than 213 calls available. You can search for available calls with `eptr.get_available_calls()` function. This is almost an exhaustive list of available calls in the platform currently. \n\n\n### Alternative: Using .env file for credentials and TGT recycling\n\nStarting from version `1.2.3`, you can use \".env\" file to store credentials and recycle TGT (Ticket Granting Ticket) automatically. Recycling TGT allows you to create wrapper functions without the need to carry `EPTR2` object directly or having to create TGTs for each call (which may be throttled). TGT information is stored in the target path (default is current directory) under the file name `.eptr2-tgt` and reused until it expires.\n\n```python\nfrom eptr2 import EPTR2\n\neptr = EPTR2(\n    use_dotenv=True,  ## Default: True\n    recycle_tgt=True, ## Default: False\n    dotenv_path=\".env\" ## Default: \"\".env\"\n    tgt_path=\".\" ## Default: \".\", included as a kwarg\n    )\n\ndf = eptr.call(\"mcp\", start_date=\"2025-08-01\",end_date=\"2025-08-31\")\n```\n\n`.env` file is simply a text file with the following content. You need to create it in the same directory where you run your script.\n\n```\nEPTR_USERNAME=youremail@something.com\nEPTR_PASSWORD=yourpassword\n```\n\n### Deprecated: Credentials JSON\n\n*This method is being deprecated and will be removed soon.*\n\nFrom eptr2 version 1.1.0, you can use a new login method that automatically handles TGT (Ticket Granting Ticket) management. This way, TGT is automatically renewed when it expires, and credentials are loaded from a file or environment variables. You need a credentials file (e.g. `creds/eptr_credentials.json`) with the following structure:\n\n```json\n{\n    \"username\": \"YOUR_USERNAME\",\n    \"password\": \"YOUR_PASSWORD\"\n}\n```\n\nOr, you can generate the credentials file with the following code (ps. you can change the `cred_path` to your desired path, default is `creds/eptr_credentials.json`):\n\n```python\nfrom eptr2 import generate_eptr2_credentials_file\n\ngenerate_eptr2_credentials_file(\n    username=\"YOUR_USERNAME\",\n    password=\"YOUR_PASSWORD\"\n)\n```\n\nYou can use the following code to create an `EPTR2` object with the new login method (ps. you can change the `cred_path` to your desired path, default is `creds/eptr_credentials.json`):\n\n```python\nfrom eptr2 import eptr_w_tgt_wrapper\n\neptr = eptr_w_tgt_wrapper()\n```\n\n\n### Live Tutorial\n\nStarting from version 1.0.0, `eptr2` package includes a live tutorial feature as a Streamlit app (p.s. You need to have Streamlit installed). You can run the following code to start the tutorial. Its functionality is almost the same as [eptr2demo app](https://eptr2demo.streamlit.app/).\n\n```python\nfrom eptr2.tutorials import run_demo_app\n\nrun_demo_app(username=\"YOUR_USERNAME\",password=\"YOUR_PASSWORD\")\n```\n\n### Calculator Tutorial\n\nWith version 1.0.2 you can get a calculator tutorial to get imbalance and KÜPST cost estimates for any date and hour with custom actual and forecast values.\n\n```python\nfrom eptr2.tutorials import run_calc_app\n\nrun_calc_app(username=\"YOUR_USERNAME\",password=\"YOUR_PASSWORD\")\n```\n\n\n_More tutorials are expected to be added in the future._\n\n## AI Agent Integration (MCP Server)\n\nStarting from version 1.2.4, `eptr2` includes a Model Context Protocol (MCP) server for AI agent integration. This allows AI assistants like Claude to directly query Turkish electricity market data.\n\n### Quick Start\n\nInstall with all extras (includes MCP support):\n\n```bash\npip install \"eptr2[allextras]\"\n```\n\nRun the MCP server:\n\n```bash\neptr2-mcp-server\n```\n\nOr programmatically:\n\n```python\nfrom eptr2.mcp import run_mcp_server\nimport asyncio\n\nasyncio.run(run_mcp_server(use_dotenv=True, recycle_tgt=True))\n```\n\n### Configuration\n\nCreate a `.env` file with your credentials:\n\n```env\nEPTR_USERNAME=your.email@example.com\nEPTR_PASSWORD=yourpassword\n```\n\nFor Claude Desktop integration, add to your config file:\n\n```json\n{\n  \"mcpServers\": {\n    \"eptr2\": {\n      \"command\": \"eptr2-mcp-server\",\n      \"env\": {\n        \"EPTR_USERNAME\": \"your.email@example.com\",\n        \"EPTR_PASSWORD\": \"yourpassword\"\n      }\n    }\n  }\n}\n```\n\n### Available MCP Tools\n\nThe server exposes 10 tools for querying electricity market data:\n- Market Clearing Price (MCP/PTF)\n- System Marginal Price (SMP/SMF)\n- Real-time Consumption and Generation\n- Demand Forecasts\n- Imbalance Prices\n- Generic API calls (213+ endpoints)\n- Composite data functions\n\nFor complete Claude Desktop setup, see [CLAUDE_SETUP.md](CLAUDE_SETUP.md).\n\nFor AI agent reference documentation, see [AGENTS.md](AGENTS.md) and [src/eptr2/mcp/README.md](src/eptr2/mcp/README.md).\n\n# About EPIAS Transparency Platform v2.0 Python client by Robokami Data\n\n🇬🇧 `eptr2` (**EP**IAS **Tr**ansparency **2**.0) package is a thin wrapper around [EPIAS Transparency Platform v2.0](https://seffaflik.epias.com.tr/home) API brought to you by [Robokami](https://robokami.com). It is an unofficial package with Apache License 2.0 (free and permissable use for commercial applications, [see details](https://www.tldrlegal.com/license/apache-license-2-0-apache-2-0)). `eptr2` accesses currently more than 213 services with convenience methods.\n\n\n🇹🇷 `eptr2` (**EP**İAŞ **Tr**ansparency **2**.0) paketi [Robokami](https://robokami.com) tarafından [EPİAŞ Şeffaflık Platformu 2.0](https://seffaflik.epias.com.tr/home) API'si üzerine geliştirilmiş bir Python paketidir. Apache License 2.0 ile lisanslanmıştır ([ücretsiz ve büyük ölçüde serbest kullanım](https://www.tldrlegal.com/license/apache-license-2-0-apache-2-0)). `eptr2` 213'ten fazla veri servisine erişim sağlar.\n\n\n## Advanced Topics\n\n### Aliases\n\nThere are default aliases for the calls. For instance, \"ptf\" is an alias for \"mcp\". You can use aliases to call services. \n\n```python\nres = eptr.call(\"ptf\", start_date=\"2024-07-29\", end_date=\"2024-07-29\")\n```\n\nYou can also create aliases for your calls. Just prepare an alias dictionary and add it to the `EPTR2` object. \n\n```python\ncustom_aliases = {\"market-clearing-price\": \"mcp\", \"system-marginal-price\": \"smp\"}\n\neptr = EPTR2(username=\"YOUR_USERNAME\",password=\"YOUR_PASSWORD\", custom_aliases=custom_aliases)\n```\n\nAs a warning aliases may overwrite the default keys and default aliases. For instance if your alias is \"mcp\" pointing to \"smp\", now default \"mcp\" call is overwritten with \"mcp\" alias pointing to \"smp\".\n\nLibrary will also have default aliases. You can check aliases with `eptr.get_aliases()` function. If you want to include custom aliases, you can get them with `include_custom_aliases` parameter. `eptr.get_available_calls()` function may also include aliases.\n\n```python\neptr.get_aliases(include_custom_aliases = True)\n\neptr.get_available_calls(include_aliases = True)\n```\n\n### Composite Functions\n\n_New feature from version 1.0.0_\n\nComposite functions are combinations of multiple calls under a single table for a purpose. That purpose might be to gather reporting data or training data for forecast models. You can create your own composite functions with `eptr2` package or use already available ones. \n\nAn side note: We process and manipulate data in composite functions so it is not just the merged data frames of base eptr2 calls.\n\n#### Hourly Consumption and Forecast Data\n\nOur first composite function is `get_hourly_consumption_and_forecast_data`. It returns a data frame with a combination of Load Plan, UECM and Real Time Consumption.\n\n```python\nfrom eptr2 import EPTR2\nfrom eptr2.composite import get_hourly_consumption_and_forecast_data\n\neptr = EPTR2(username=\"YOUR_USERNAME\",password=\"YOUR_PASSWORD\")\ndf = get_hourly_consumption_and_forecast_data(eptr, start_date=\"2024-07-29\", end_date=\"2024-07-29\")\nprint(df)\n```\n\n#### Price and Cost\n\nOur second set of composite functions is about prices and costs. \n\n+ `get_hourly_price_and_cost_data`: It returns a data frame with a combination of MCP, SMP, WAP (optional) and associated imbalance and KUPST (optional) costs.\n+ `get_imbalance_data`: It returns a data frame with a combination of Imbalance Prices, Imbalance Volumes and Imbalance Costs (optional).\n\n```python\nfrom eptr2 import EPTR2\nfrom eptr2.composite import get_hourly_price_and_cost_data, get_imbalance_data\n\neptr = EPTR2(username=\"YOUR_USERNAME\",password=\"YOUR_PASSWORD\")\ndf_cost = get_hourly_price_and_cost_data(eptr, start_date=\"2024-07-29\", end_date=\"2024-07-29\")\nprint(df_cost)\ndf_imbalance = get_imbalance_data(eptr, start_date=\"2024-07-29\", end_date=\"2024-07-29\")\nprint(df_imbalance)\n```\n\n#### Production\n\nWith v1.0.2, you can get production and production plan data as well with composite functions. If you know the necessary ids, you can get the specific production values (omit the parameters to get totals).\n\nThere are three composite functions. One for getting actual production data (real time, UEVM), one for getting plan data (KGUP v1, KGUP, KUDUP), and one to get both and merge into a single table. Each column except date/time/hour get their own suffix from the data source (e.g. \"wind_uevm\").\n\n```python\nfrom eptr2 import EPTR2\nfrom eptr2.composite import wrapper_hourly_production_plan_and_realized, get_hourly_production_data, get_hourly_production_plan_data\n\neptr = EPTR2(username=\"YOUR_USERNAME\",password=\"YOUR_PASSWORD\")\n\nactual_df = get_hourly_production_data(\n    eptr=eptr,\n    start_date=\"2024-11-01\",\n    end_date=\"2024-11-01\",\n    rt_pp_id=641,  ## ATATÜRK HES\n    uevm_pp_id=142,  ## ATATÜRK HES\n    verbose=True,\n)\n\n\nplan_df = get_hourly_production_plan_data(\n    eptr=eptr,\n    start_date=\"2024-11-01\",\n    end_date=\"2024-11-01\",\n    org_id=195, ## EÜAŞ\n    uevcb_id=3525325, ## ATATÜRK HES\n    verbose=True,\n)\n\nwrap_df = wrapper_hourly_production_plan_and_realized(\n        eptr=eptr, start_date=\"2024-11-01\", end_date=\"2024-11-01\", verbose=True\n    )\n```\n\n#### Intraday Market (IDM) Logs\n\nYou can get the Intraday Market (IDM) logs with the following composite function. It returns a data frame with a combination of IDM logs and their details.\n\n```python\nfrom eptr2 import EPTR2\nfrom eptr2.composite import idm_log_longer, idm_log_period\n\neptr = EPTR2(credentials_file_path=\"creds/eptr_credentials.json\")\n\nidm_log_longer(eptr=eptr, start_date=\"2023-01-01\", end_date=\"2023-01-31\", verbose=True)\nidm_log_period(eptr=eptr, period=\"2023-01-01\", verbose=True)\n```\n\n#### Day Ahead and Bilateral Trade Data\n\n```python\nfrom eptr2 import EPTR2\nfrom eptr2.composite import get_day_ahead_and_bilateral_matches, get_day_ahead_detail_info\n\neptr = EPTR2(credentials_file_path=\"creds/eptr_credentials.json\")\n\ndf = get_day_ahead_and_bilateral_matches(eptr=eptr,start_date=\"2023-01-01\", end_date=\"2023-01-31\", verbose=True, include_contract_symbol=True)\n\ndf2 = get_day_ahead_detail_info(\n    eptr=eptr, start_date=\"2023-01-01\", end_date=\"2023-01-31\", verbose=True\n)\n```\n\n#### Balancing Power Market Data\n\n```python\nfrom eptr2 import EPTR2\nfrom eptr2.composite import get_bpm_period, get_bpm_range\n\neptr = EPTR2(credentials_file_path=\"creds/eptr_credentials.json\")\nstart_date = \"2025-05-01\"\nend_date = \"2025-05-31\"\ndf1 = get_bpm_range(\n    eptr=eptr, start_date=start_date, end_date=end_date, verbose=True\n)\n\nperiod = \"2025-05-01\"  # Example period\ndf2 = get_bpm_period(\n    period=period, eptr=eptr, max_lives=2, verbose=True, strict=True\n)\n```\n\n#### Plant Costs\n\n```python\nfrom eptr2 import EPTR2\nfrom eptr2.composite import gather_and_calculate_plant_costs\n\neptr = EPTR2(credentials_file_path=\"creds/eptr_credentials.json\")\n\ndf = gather_and_calculate_plant_costs(\n    eptr=eptr,\n    start_date=\"2023-01-01\",\n    end_date=\"2023-01-31\",\n    pp_id=120,  ## BOZCAADA RES\n    org_id=195,  ## EÜAŞ\n    uevcb_id=3204384,  ## BOZCAADA RES\n    plant_type=\"wind\",\n    verbose=True,\n    forecast_source = \"kgup\",\n    actual_source = \"uevm\"\n)\n```\n\n### Bulk Function Calls\n\nThere are three bulk function calls for daily operations: daily production plan (DPP/KGÜP), real time generation and uevcb ids. \n\n```python\n### DPP / KGÜP bulk\ndpp_df = eptr.call(\"dpp-bulk\", date=\"2025-08-31\", uevcb_ids=[3208611, 723724, 335505, 106710, 4094])\n### Real Time Generation bulk\nrt_gen_df = eptr.call(\"rt-gen-bulk\", date=\"2025-08-31\", pp_ids=[11162, 17889, 605, 5005121, 20764])\n### UEVCB list bulk\nuevcb_df = eptr.call(\"uevcb-list-bulk\", date=\"2025-08-31\", org_ids=[166, 12297, 648, 19880, 162])\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftideseed%2Feptr2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftideseed%2Feptr2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftideseed%2Feptr2/lists"}