SRP Utility Tariff API

Точные тарифы на электроэнергию для жилых домов и детализированные счета для Salt River Project (метро Финикса, Аризона), рассчитанные по официальным тарифным книгам SRP, а не по оценкам. Каждый ответ содержит ссылку на документ и страницу, из которых взяты данные.

Работает: https://utility-api-jn9g.onrender.com · Документация: /docs

GET https://utility-api-jn9g.onrender.com/v1/tariff/rate?tariff_id=srp:E-26&at=2026-07-15T15:00:00

{
  "season": "summer_peak",
  "period": "on_peak",
  "rate_per_kwh": 0.2566,
  "components": [ ... ten unbundled line items ... ],
  "source": {
    "document_url": "https://www.srpnet.com/.../2025-Ratebook-with-Temporary-FPPAM.pdf",
    "page_refs": ["48-53"],
    "verified_by": "Courtney",
    "confidence": "verified"
  },
  "caveats": [ ... ]
}

Зачем это существует

Тарифы SRP для жилых домов публичны, но их действительно сложно рассчитать. Цены меняются по часам, дням недели, сезонам и наблюдаемым праздникам, в рамках дюжины планов, определения которых не совпадают:

• Сезоны определяются расчётным циклом. Пиковые часы определяются календарной датой. По E-26 лето означает расчётные циклы мая, июня, сентября и октября, но окно пиковой нагрузки с 14:00 до 20:00 действует с 1 мая по 31 октября по календарной дате. Расчётный цикл, пересекающий 31 октября, получает цены одного сезона и две разные классификации часов. Сведение этого в одно поле «сезон» молчаливо неверно выставляет счёт за каждый переходный месяц.

• Тарифы подаются в горном стандартном времени, а Аризона не переходит на летнее время. Любая универсальная библиотека time-of-use, которая сдвигает время на летнее, ошибается на час в течение половины года.

• Тарифы — это разложенные на компоненты стеки, а не единые числа. Корректировка на топливо и покупную мощность находится внутри стека и движется по своему собственному графику, поэтому её нужно оставлять отдельной.

• Праздники приостанавливают одни периоды, но не другие. На E-28 пиковый период приостанавливается на Рождество, а сверхнизкий пик всё ещё действует.

Этот сервис моделирует всё это на основе поданных документов и показывает свою работу.

Related MCP server: ratebook-mcp

Покрытие

Вызовите GET / или GET /v1/tariff/plans для актуального ответа. По состоянию на последнюю загрузку данных:

Только для жилых домов. Запросы вне покрываемого расчётного цикла возвращают 422 с указанием покрываемых окон.

Что сервис отказывается делать и почему

Это стоит прочитать, прежде чем полагаться на него.

Немоделируемые планы. E-28 выплачивает кредит за каждый экспортированный кВт·ч, который текущая модель данных не может выразить. Вместо того чтобы возвращать счёт, который будет неверен для любого клиента с солнечными панелями на крыше, сервис отказывает E-28 напрямую и сообщает об этом. Исправление этого — изменение схемы, отслеживается ниже.

Непокрытые даты. Каждый файл покрывает конкретное окно расчётного цикла. Запросите цикл, для которого нет поданного документа, и получите 422 со списком покрываемых — никогда не экстраполированный тариф.

Положения, которые нельзя выразить данными. Каждый тариф содержит список unmodeled_provisions, отображаемый как caveats в ответах: годовой лимит энергоэффективности в $300 000, право SRP переносить корректировку топлива между подачами и перекладывание государственных налогов/сборов. Это реальные условия, которые могут изменить сумму, и они указаны, а не скрыты.

Налоги. Не включены. Ставки штата, округа и муниципалитета зависят от адреса обслуживания.

MCP-сервер

Тот же калькулятор доступен как MCP-сервер, чтобы ассистенты могли вызывать его напрямую. Три инструмента: list_srp_plans, get_srp_rate, calculate_srp_bill. Бесплатно и локально — без оплаты, без сетевых вызовов.

{
  "mcpServers": {
    "srp-tariff": {
      "command": "C:\\path\\to\\utility-api\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\utility-api\\mcp_server.py"]
    }
  }
}

Заметки для Windows, выученные на горьком опыте:

• Устанавливайте зависимости с помощью интерпретатора venv явно: & ".\.venv\Scripts\python.exe" -m pip install -r requirements.txt. Обычный pip install может попасть в другой Python, и сервер упадёт с ModuleNotFoundError.

• Если Claude Desktop был установлен из Microsoft Store, он читает изолированный путь конфигурации в %LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude\, а не %APPDATA%\Claude\. Используйте Settings → Developer → Edit Config, чтобы найти файл, который приложение действительно читает.

• Режим разработчика должен быть включён, чтобы локальные серверы появлялись.

Машинные платежи (x402)

HTTP-эндпоинты также оплачиваются за вызов через x402 — агент получает 402, платит в USDC и повторяет попытку, без аккаунта или API-ключа. Сейчас на Base Sepolia (testnet); действующая сеть указывается в GET /.

/ и /v1/tariff/plans бесплатны по замыслу: вызывающий должен иметь возможность узнать, что покрывается, прежде чем решать платить.

Локальный запуск

python -m venv .venv
.venv\Scripts\activate
python -m pip install -r requirements.txt
python -m pytest tests\ -v
python -m uvicorn server:app --reload

Оплата активируется только когда CDP_API_KEY_ID и X402_PAY_TO оба заданы в .env. Оставьте их незаданными, чтобы работать без оплаты.

Модель данных

Один JSON-файл на подачу, а не на план: data/tariffs/srp/<slug>@<from-billing-cycle>.json. Изменение тарифа или временная корректировка добавляет файл; он никогда не редактирует существующий. Реестр связывает tariff_id со списком версий и выбирает по запрошенному расчётному циклу, поэтому исторические циклы остаются отвечаемыми.

Файлы проверяются по schemas/tariff-schema.v1.1.json. Тестовый набор проверяет, что каждый стек компонентов суммируется в его печатный итог, что все двенадцать расчётных месяцев сопоставляются ровно с одним сезоном, что каждая комбинация сезон/период, которую может создать календарь, имеет цену, и что файл, заявляющий confidence: verified, также указывает, кто его проверил и какие страницы.

Известные пробелы

• С ноября 2026 года и далее не смоделировано. SRP публикует несколько вариантов тарифной книги (базовый, временный-FPPAM и ревизии TCA), и какой из них действует для ноябрьского цикла, нужно подтвердить по источнику перед добавлением данных.

• Экспортные кредиты (E-28, E-13, E-14, E-16) требуют типа начисления кредита — схема v1.2.

• Пропорциональный расчёт для частичных расчётных циклов (въезд, выезд, смена плана) не выражен.

• Структурированная пригодность. Клиент с солнечными панелями на крыше 2019 года не может быть на E-26, но пригодность сейчас — это проза, поэтому ничто не мешает вызывающему оценить их там.

• Правило округления — построчно, затем суммирование. Не проверено, суммирует ли SRP сначала и округляет один раз, по реальному счёту time-of-use.

Точность и отказ от ответственности

Тарифы транскрибированы из поданных тарифных книг SRP, и каждый файл записывает, кто проверил его по каким страницам. Стеки компонентов машинно проверяются на суммирование к печатным итогам. Тем не менее, это неофициальная реимплементация: она не связана с SRP и не одобрена им, и не должна быть единственным основанием для финансового решения. Проверьте по своему счёту и опубликованным тарифам SRP.

Подачи меняются. Проверьте retrieved_at в любом ответе и подтвердите, что нужный цикл покрыт.

Создано Killion Apps.