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上，夏季指5月、6月、9月和10月的计费周期，但下午2–8点的峰时窗口按日历日期从5月1日到10月31日。跨越10月31日的计费周期会得到一种季节的价格和两种不同的小时分类。将这些合并为单一的“季节”字段会静默地错误计费每个过渡月份。

• 费率按山区标准时间提交，亚利桑那州不实行夏令时。 任何为夏令时调整的通用分时电价库在半年内都会错一个小时。

• 费率是分项组件堆栈，不是单一数字。燃料和购电调整位于堆栈内，并按自己的时间表变动，因此必须保持可分离。

• 假日会暂停某些时段，但不会暂停其他时段。 在E-28上，圣诞节暂停峰时，但超低谷时段仍然适用。

本服务根据提交的文件对所有这些进行建模，并展示其工作过程。

Related MCP server: ratebook-mcp

覆盖范围

调用 GET / 或 GET /v1/tariff/plans 获取实时答案。截至最新数据加载：

仅限居民。超出覆盖计费周期的请求返回 422，并附上覆盖的时间窗口。

它拒绝什么，以及为什么

在依赖它之前，这部分值得一读。

未建模的计划。 E-28为每出口千瓦时支付信用额度，当前数据模型无法表达。与其为任何有屋顶太阳能的客户返回错误的账单，该服务直接拒绝E-28并说明原因。修复此问题需要更改模式，见下文。

未覆盖的日期。 每个文件覆盖特定的计费周期窗口。如果请求的周期没有记录在案的申报文件，您会收到422，列出覆盖范围——绝不会给出外推的费率。

无法数据化的条款。 每个费率都带有 unmodeled_provisions 列表，在响应中以 caveats 形式呈现：30万美元的年度能效上限、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\。使用 设置 → 开发者 → 编辑配置 找到应用实际读取的文件。

• 必须启用开发者模式，本地服务器才会显示。

机器支付（x402）

HTTP端点也可通过 x402 按调用付费——代理收到402，以USDC支付，然后重试，无需账户或API密钥。目前位于 Base Sepolia（测试网）；生效网络在 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

仅当 .env 中同时设置了 CDP_API_KEY_ID 和 X402_PAY_TO 时，支付才会激活。保持未设置即可免费运行。

数据模型

每个申报一个JSON文件，而不是每个计划：data/tariffs/srp/<slug>@<from-billing-cycle>.json。费率案例或临时调整会添加文件；它从不编辑现有文件。注册表将 tariff_id 映射到版本列表，并根据请求的计费周期进行选择，因此历史周期仍可回答。

文件根据 schemas/tariff-schema.v1.1.json 进行验证。测试套件检查每个组件堆栈是否等于其打印的总和，所有十二个计费月份是否恰好映射到一个季节，日历能产生的每个季节/时段组合是否有价格，以及声称 confidence: verified 的文件是否也说明了验证者是谁以及哪些页面。

已知差距

• 2026年11月及以后未建模。 SRP发布多种费率手册变体（基础、临时FPPAM和TCA修订版），在添加数据之前，需要对照来源确认哪个适用于11月周期。

• 出口信用（E-28、E-13、E-14、E-16）需要信用收费类型——模式v1.2。

• 按比例分摊（部分计费周期，如迁入、迁出、计划变更）未表达。

• 结构化资格。 拥有2019年屋顶太阳能的客户不能使用E-26，但资格目前是文字描述，因此无法阻止调用者为其定价。

• 舍入约定是逐项舍入后求和。SRP是否先求和再舍入一次，尚未通过实际分时账单验证。

准确性与免责声明

费率转录自SRP提交的费率手册，每个文件记录了谁对照哪些页面进行了验证。组件堆栈经过机器检查，确保总和等于打印的总数。即便如此，这也是非官方的重新实现：它与SRP无关联，也未获得SRP认可，不应作为财务决策的唯一依据。请对照您自己的账单和SRP公布的费率进行验证。

申报文件会变化。请检查任何响应中的 retrieved_at，并确认您关心的周期是否在覆盖范围内。

由 Killion Apps 构建。