{
  "markdown": "[![PyPI - Version](https://img.shields.io/pypi/v/eptr2)](https://pypi.org/project/eptr2/)\n[![PyPI - Downloads](https://img.shields.io/pypi/dm/eptr2)](https://pypi.org/project/eptr2/)\n[![PyPI - Python Version](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Ftideseed%2Feptr2%2Fmain%2Fpyproject.toml)](https://pypi.org/project/eptr2/)\n[![PyPI - License](https://img.shields.io/pypi/l/eptr2)](https://github.com/Tideseed/eptr2/blob/main/LICENSE)\n[![Documentation](https://img.shields.io/badge/docs-tideseed.github.io%2Feptr2-blue)](https://tideseed.github.io/eptr2/)\n[![AI agents](https://img.shields.io/badge/AI%20agents-MCP%20%7C%20CLI%20%7C%20Skills-8A2BE2)](https://tideseed.github.io/eptr2/ai-integration/mcp-server/)\n\n# eptr2\n\n`eptr2` (**EP**IAS **Tr**ansparency **2**.0) is a Python client for the [EPIAS Transparency Platform v2.0](https://seffaflik.epias.com.tr/home) API, covering **232 services** of the Turkish electricity and natural gas markets — prices (PTF/SMF), consumption, generation, production plans, market operations and imbalance costs.\n\nIt is an unofficial package by [Robokami](https://robokami.com) / [Tideseed](https://tideseed.com), Apache License 2.0.\n\n📖 **Full documentation: <https://tideseed.github.io/eptr2/>** · 🇹🇷 **[Türkçe bölüm aşağıda](#türkçe)**\n\n---\n\n## Getting Started\n\n**1. Get credentials.** [Register with the EPIAS Transparency Platform](https://kayit.epias.com.tr/epias-transparency-platform-registration-form). Your username is the registration e-mail. The platform has an English version too.\n\n**2. Install.**\n\n```bash\npip install \"eptr2[allextras]\"\n```\n\n`[allextras]` adds pandas (DataFrame output) and MCP server support. For a thin client with almost no dependencies, `pip install eptr2` also works. Everything works with `uv pip install` as well.\n\n**3. Store your credentials** in a `.env` file next to your script:\n\n```\nEPTR_USERNAME=your.email@example.com\nEPTR_PASSWORD=yourpassword\n```\n\n**4. Make your first call.**\n\n```python\nfrom eptr2 import EPTR2\n\neptr = EPTR2(use_dotenv=True, recycle_tgt=True)\n\n# Market Clearing Price (MCP / PTF) for a single day\ndf = eptr.call(\"mcp\", start_date=\"2026-07-01\", end_date=\"2026-07-01\")\nprint(df)\n```\n\n`recycle_tgt=True` caches the authentication ticket, so repeated runs do not log in again.\n\nYou can also pass credentials directly — handy for notebooks:\n\n```python\neptr = EPTR2(username=\"your.email@example.com\", password=\"yourpassword\")\n```\n\n**5. Or skip Python entirely** and use the command line:\n\n```bash\neptr2 call mcp --start-date 2026-07-01 --end-date 2026-07-01 --format csv\n```\n\n## Usage\n\n### One call pattern for all 232 services\n\nEvery service is reached with the same `call` method and an endpoint key:\n\n```python\neptr.call(\"mcp\",         start_date=\"2026-07-01\", end_date=\"2026-07-01\")  # PTF\neptr.call(\"smp\",         start_date=\"2026-07-01\", end_date=\"2026-07-01\")  # SMF\neptr.call(\"rt-cons\",     start_date=\"2026-07-01\", end_date=\"2026-07-01\")  # Real-time consumption\neptr.call(\"rt-gen\",      start_date=\"2026-07-01\", end_date=\"2026-07-01\")  # Generation by source\neptr.call(\"mcp-smp-imb\", start_date=\"2026-07-01\", end_date=\"2026-07-01\")  # Imbalance prices\n```\n\nTurkish aliases work too: `ptf` → `mcp`, `smf` → `smp`.\n\n### Finding the right service\n\nYou do **not** need credentials to explore the API:\n\n```bash\neptr2 list                     # all 232 keys grouped by category\neptr2 search dengesizlik       # keyword search, Turkish or English\neptr2 describe mcp             # parameters, method, path, description\n```\n\n```python\nfrom eptr2.agentic import search_calls, describe_call\n\ndescribe_call(\"uevm\")          # required/optional parameters and meaning\n```\n\n### Typed convenience wrappers\n\nIf you prefer autocomplete and type hints over string keys:\n\n```python\nfrom eptr2.calls import get_mcp, get_smp, get_rt_gen\n\ndf = get_mcp(start_date=\"2026-07-01\", end_date=\"2026-07-01\", eptr=eptr)\n```\n\n### Composite functions\n\nReady-made combinations of several calls, cleaned and merged:\n\n```python\nfrom eptr2.composite import (\n    get_hourly_price_and_cost_data,        # MCP + SMP + WAP + imbalance/KUPST costs\n    get_hourly_consumption_and_forecast_data,\n    get_dabi_idm_data,                     # day-ahead + bilateral + intraday volumes\n    get_bpm_range,                         # balancing market (YAL/YAT) with SMP\n    get_kgup_bulk_range,                   # bulk production PLANS (by UEVCB id)\n    get_rt_gen_bulk_range,                 # bulk REALIZED generation (by powerplant id)\n)\n\ndf = get_hourly_price_and_cost_data(\n    start_date=\"2026-07-01\", end_date=\"2026-07-31\", eptr=eptr\n)\n```\n\nNote the argument order: dates first, the client as the `eptr` keyword.\n\n### Imbalance and KÜPST cost calculations\n\nPure functions — no API call, no credentials. The regulation period (pre-2026 / 2026) and the price floor/ceiling are derived from the contract code:\n\n```python\nfrom eptr2.util.costs import calculate_unit_price_and_costs_by_contract\n\ncalculate_unit_price_and_costs_by_contract(\n    contract=\"PH26070101\",          # PHYYMMDDhh\n    mcp=4000, smp=4000,\n    system_direction=\"Enerji Açığı\", # required when MCP == SMP\n)\n```\n\n⚠️ When MCP equals SMP the system direction cannot be inferred from prices, and assuming a balanced system **understates the negative imbalance price**. Pass `system_direction` (or `sd_sign`) explicitly; the `systemStatus` field of `mcp-smp-imb` gives it.\n\n### Options for unattended / production use\n\n```python\neptr = EPTR2(\n    use_dotenv=True,\n    recycle_tgt=True,\n    strict_params=True,     # raise on unknown parameters instead of warning\n    connect_timeout=10.0,   # seconds (per operation, not a total deadline)\n    read_timeout=60.0,\n)\n```\n\n`strict_params` matters more than it looks: an unknown parameter is dropped from the request, so a misspelled filter (`ppID` instead of `pp_id`) silently turns a filtered query into an unfiltered one. By default eptr2 warns and names the correct parameter; `strict_params=True` makes it an error.\n\n---\n\n## Using eptr2 with AI Agents\n\n`eptr2` ships provider-agnostic tooling — nothing is tied to one model vendor. There are three ways to use it, depending on what your agent is.\n\n### 1. Chat assistants — connect the MCP server\n\nGives any [Model Context Protocol](https://modelcontextprotocol.io) client (VS Code agent mode, Claude Desktop/Code, Cursor, …) **18 tools**: prices, consumption, generation, market operations, credential-free discovery, and pure imbalance/KÜPST calculators.\n\n```bash\npip install \"eptr2[allextras]\"\neptr2 mcp-config --client vscode     # or claude-desktop, claude-code, cursor, generic\n```\n\nPaste the printed snippet into your client's MCP configuration, fill in your credentials, and ask questions in plain language:\n\n> \"What was the market clearing price in Turkey yesterday, and how did it compare with SMP?\"\n\n### 2. Coding agents — let them write eptr2 code for you\n\nPoint the agent at **[AGENTS.md](AGENTS.md)**, the canonical agent guide (VS Code and Claude Code read it automatically inside this repo). Away from the repo, the agent can learn the whole API on its own, without credentials:\n\n```bash\neptr2 schema --stdout        # machine-readable description of all 232 endpoints\neptr2 describe rt-gen        # exact parameters for one endpoint\neptr2 search üretim          # find endpoints by keyword\n```\n\nInstall the 7 bundled skills (prices, consumption, generation, imbalance costs, market operations, API discovery, typed wrappers) into any SKILL.md-compatible runtime:\n\n```bash\neptr2 install-skills                 # into ./.agents/skills\neptr2 install-skills --dest user     # into ~/.agents/skills\neptr2 install-skills --client claude  # into ./.claude/skills\neptr2 install-skills --client claude --dest user  # into ~/.claude/skills\n```\n\nThe skills and MCP server are also packaged together as a portable [Agent Plugin](https://agent-plugins.org): `eptr2 plugin-path`.\n\n### 3. Shell-driven agents — use the CLI\n\nData goes to stdout (JSON or CSV), diagnostics to stderr, nonzero exit codes on failure, so output pipes cleanly:\n\n```bash\neptr2 call mcp --start-date 2026-07-01 --end-date 2026-07-01 --format json | jq '.[0]'\n```\n\n📚 Details: [MCP server](https://tideseed.github.io/eptr2/ai-integration/mcp-server/) · [MCP client setup](https://tideseed.github.io/eptr2/ai-integration/mcp-clients/) · [agent skills](https://tideseed.github.io/eptr2/ai-integration/agent-skills/) · [Agent Plugin](https://tideseed.github.io/eptr2/ai-integration/agent-plugin/) · [CLI](https://tideseed.github.io/eptr2/ai-integration/cli/)\n\n---\n\n## Going Further\n\n| Topic | Documentation |\n|-------|---------------|\n| All 232 API calls, categories and parameters | [Available API Calls](https://tideseed.github.io/eptr2/user-guide/api-calls/) |\n| Typed `get_*` wrapper functions (`eptr2.calls`) | [Convenience Wrappers](https://tideseed.github.io/eptr2/user-guide/convenience-wrappers/) |\n| Aliases, bulk calls, DataFrames | [Basic Usage](https://tideseed.github.io/eptr2/user-guide/basic-usage/) · [DataFrames](https://tideseed.github.io/eptr2/user-guide/dataframes/) |\n| Composite functions | [Composite Functions](https://tideseed.github.io/eptr2/user-guide/composite-functions/) |\n| Imbalance / KÜPST cost calculations | [Utilities API](https://tideseed.github.io/eptr2/api/util/) |\n| Turkish market abbreviations (PTF, SMF, KGÜP, …) | [Abbreviations](https://tideseed.github.io/eptr2/reference/abbreviations/) |\n| Release history | [Changelog](https://tideseed.github.io/eptr2/reference/changelog/) |\n\n### Development versions\n\n```bash\npip install --pre \"eptr2[allextras]\"                                          # latest pre-release\npip install \"eptr2[allextras] @ git+https://github.com/Tideseed/eptr2.git\"    # straight from GitHub\n```\n\nPin a released version with `eptr2==1.3.8` if you need to stay off dev builds.\n\n---\n\n## Türkçe\n\n`eptr2` (**EP**İAŞ **Tr**ansparency **2**.0), [EPİAŞ Şeffaflık Platformu 2.0](https://seffaflik.epias.com.tr/home) API'si üzerine geliştirilmiş bir Python paketidir. Türkiye elektrik ve doğal gaz piyasalarına ait **232 veri servisine** tek bir yapıyla erişim sağlar: PTF/SMF fiyatları, tüketim, üretim, üretim planları (KGÜP/KUDÜP), piyasa işlemleri (GÖP, GİP, DGP, İA) ve dengesizlik maliyetleri.\n\n[Robokami](https://robokami.com) / [Tideseed](https://tideseed.com) tarafından geliştirilen resmi olmayan bir pakettir. Apache License 2.0 ile lisanslanmıştır; ticari kullanım dahil geniş ölçüde serbesttir.\n\n### Kurulum ve ilk adımlar\n\n**1. Kayıt.** [EPİAŞ Şeffaflık Platformu'na kayıt olun](https://kayit.epias.com.tr/epias-transparency-platform-registration-form). Kullanıcı adınız kayıt e-postanızdır.\n\n**2. Kurulum.**\n\n```bash\npip install \"eptr2[allextras]\"\n```\n\n`[allextras]` seçeneği pandas (DataFrame çıktısı) ve MCP sunucu desteğini de kurar. Sadece temel istemci için `pip install eptr2` yeterlidir.\n\n**3. Kimlik bilgileri.** Betiğinizin yanına bir `.env` dosyası oluşturun:\n\n```\nEPTR_USERNAME=eposta@ornek.com\nEPTR_PASSWORD=sifreniz\n```\n\n**4. İlk çağrı.**\n\n```python\nfrom eptr2 import EPTR2\n\neptr = EPTR2(use_dotenv=True, recycle_tgt=True)\n\n# Piyasa Takas Fiyatı (PTF)\ndf = eptr.call(\"ptf\", start_date=\"2026-07-01\", end_date=\"2026-07-01\")\nprint(df)\n```\n\n`recycle_tgt=True` giriş biletini (TGT) saklar; her çalıştırmada yeniden giriş yapılmaz.\n\n### Kullanım\n\nTüm servisler aynı desenle çağrılır. Türkçe kısaltmalar takma ad olarak kullanılabilir (`ptf` → `mcp`, `smf` → `smp`):\n\n```python\neptr.call(\"ptf\",         start_date=\"2026-07-01\", end_date=\"2026-07-01\")  # Piyasa Takas Fiyatı\neptr.call(\"smf\",         start_date=\"2026-07-01\", end_date=\"2026-07-01\")  # Sistem Marjinal Fiyatı\neptr.call(\"rt-cons\",     start_date=\"2026-07-01\", end_date=\"2026-07-01\")  # Gerçek zamanlı tüketim\neptr.call(\"rt-gen\",      start_date=\"2026-07-01\", end_date=\"2026-07-01\")  # Kaynak bazlı üretim\neptr.call(\"mcp-smp-imb\", start_date=\"2026-07-01\", end_date=\"2026-07-01\")  # Dengesizlik fiyatları\n```\n\nHangi servisin ne olduğunu **kimlik bilgisi gerekmeden** keşfedebilirsiniz:\n\n```bash\neptr2 list                 # 232 servisin tamamı, kategorilere göre\neptr2 search dengesizlik   # Türkçe veya İngilizce anahtar kelime araması\neptr2 describe uevm        # parametreler, yöntem, açıklama\n```\n\nBirden fazla çağrıyı birleştiren hazır fonksiyonlar (composite) da mevcuttur:\n\n```python\nfrom eptr2.composite import get_hourly_price_and_cost_data\n\n# PTF, SMF, AOF ve dengesizlik/KÜPST maliyetleri tek tabloda\ndf = get_hourly_price_and_cost_data(\n    start_date=\"2026-07-01\", end_date=\"2026-07-31\", eptr=eptr\n)\n```\n\n### Dengesizlik ve KÜPST maliyetleri\n\nAPI çağrısı gerektirmeyen saf hesaplama fonksiyonlarıdır. Mevzuat dönemi (2026 öncesi / 2026) ve taban-tavan fiyatlar sözleşme kodundan otomatik belirlenir:\n\n```python\nfrom eptr2.util.costs import calculate_unit_price_and_costs_by_contract\n\ncalculate_unit_price_and_costs_by_contract(\n    contract=\"PH26070101\",           # PHYYAAGGss formatında saatlik sözleşme\n    mcp=4000, smp=4000,\n    system_direction=\"Enerji Açığı\",  # PTF == SMF ise zorunlu\n)\n```\n\n⚠️ **Önemli:** PTF ile SMF eşit olduğunda sistem yönü fiyatlardan anlaşılamaz. Bu durumda sistemin dengede olduğu varsayılırsa **negatif dengesizlik fiyatı olduğundan düşük hesaplanır**. `system_direction` değerini (`Enerji Açığı` / `Enerji Fazlası` / `Dengede`) mutlaka belirtin; bu bilgi `mcp-smp-imb` çağrısındaki `systemStatus` alanından alınabilir.\n\n### Yapay zeka ajanlarıyla kullanım\n\n`eptr2`, herhangi bir yapay zeka sağlayıcısına bağlı olmayan araçlar sunar:\n\n- **MCP sunucusu** — VS Code, Claude, Cursor gibi istemcilere 18 araç kazandırır. Yapılandırma çıktısı için: `eptr2 mcp-config --client vscode`\n- **Ajan becerileri (skills)** — fiyat analizi, tüketim, üretim, dengesizlik maliyetleri, piyasa işlemleri ve API keşfi için 7 hazır beceri: `eptr2 install-skills`\n- **[AGENTS.md](AGENTS.md)** — kod yazan ajanlar için başvuru rehberi\n- **Makine tarafından okunabilir şema** — 232 servisin tamamı parametreleriyle: `eptr2 schema --stdout`\n\nBöylece bir yapay zeka asistanına doğrudan \"geçen ayın PTF ortalamasını hesapla\" ya da \"rüzgar santralim için dengesizlik maliyetini çıkar\" diyebilir, ajanın sizin için doğru çağrıları yazmasını sağlayabilirsiniz.\n\n### Dokümantasyon\n\nAyrıntılı ve güncel dokümantasyon: **<https://tideseed.github.io/eptr2/>**\n",
  "bytes": 14383,
  "sha": "2df626981f173ed777467cc234c02382fa5130080613c26071c1adc50bdc668f",
  "repo_slug": "tideseed/eptr2",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_tideseed_eptr2_claude_skills_eptr2_price_d8dcd0df/readme"
}