SRP Utility Tariff API

Salt River Project(피닉스 광역권, 애리조나)의 정확한 주거용 전기 요금과 항목별 청구서를 계산하는 API로, 추정치가 아니라 SRP가 제출한 요금표(ratebook)를 기준으로 산출합니다. 모든 응답에는 근거가 된 문서와 페이지가 명시됩니다.

라이브: 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시 온피크(on-peak) 시간대는 달력 날짜 기준 5월 1일부터 10월 31일까지입니다. 10월 31일에 걸친 청구 주기는 한 계절의 요금과 서로 다른 두 시간대 구분을 갖게 됩니다. 이를 단순히 "season" 필드로 합쳐 버리면 모든 경계 월(shoulder month)에서 조용히 잘못된 청구가 만들어집니다.

• 요금표는 산악 표준시(Mountain Standard Time)를 기준으로 제출되며, 애리조나에는 일광 절약 시간제(DST)가 없습니다. 일광 절약 시간을 반영하는 범용 시간대별(TOU) 라이브러리는 1년 중 절반은 한 시간이 어긋납니다.

• 요금은 단일 숫자가 아니라 여러 구성 요소가 쌓인 형태(component stack)입니다. 연료 및 전력 구입 조정분(fuel and purchased power adjustment)요소는 이 스택 안에 포함되며 자체 일정에 따라 움직이므로 분리된 상태로 유지되어야 합니다.

• 공휴일은 일부 시간대만 중단시킵니다. E-28에서는 크리스마스에 온피크(on-peak)가 중단되는 반면, 슈퍼 오프피크(super-off-peak)는 그대로 적용됩니다.

이 서비스는 해당 사항을 모두 신고서(filing)에서 파악해 계산 과정을 그대로 보여줍니다.

Related MCP server: ratebook-mcp

Coverage

최신 정보는 GET / 또는 GET /v1/tariff/plans를 호출하면 됩니다. 최신 데이터 기준:

주거용만 적용됩니다. 커버되는 청구 주기 이외의 요청에는 커버되는 기간과 함께 422가 반환됩니다.

뭐 더 필요... 거부하는 것과 그 이유

이 부분은 이 서비스에 의존하기 전에 읽어 둘 가치가 있습니다.

모델링되지 않은 요금제. E-28은 수출된 kWh당 크레딧을 지급하는데, 현재 데이터 모델로 표시할 수 없습니다. 태양광 패널이 있는 어떤 고객에게 잘못된 청구서를 보내는 대신, 이 서비스는 E-28을 아예 거부하고 그 이유를 명시합니다. 이 문제는 스키마 변경이 필요하며 아래에 추적되어 있습니다.

적용되지 않는 기간. 각 파일이 커버하는 청구 주기 창은 정해져 있습니다. 기록상 어떠한 신고서에서도 관장하지 않는 주기를 요청하면, 커버되는 주기와 함께 422 응답을 받게 됩니다. 추정 요금을 반환하는 일은 없습니다.

데이터로 표현할 수 없는 조항. 모든 요금표에는 unmodeled_provisions 목록이 있으며, 응답에서는 caveats로 표시됩니다. 예: 연간 $300,000의 에너지 효율 상한, SRP가 신고서 사이에서 연료 조정을 옮길 수 있는 재량권, 그리고 정부세금과 수수료의 전가(pass-through). 이는 실제 금액을 바꿀 수 있는 실질적인 조건이며, 숨기지 않고 명시합니다.

세금. 포함되지 않습니다. 주 세금, 카운티 세금, 지방세(특별) 요율은 서비스 주소에 따라 달라집니다.

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이 다른 CD/다른 Python을 건드리면 서버가 ModuleNotFoundError를 내며 실패할 수 있습니다.

• Claude Desktop이 Microsoft Store에서 설치된 경우, %APPDATA%\Claude\ 대신 %LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude\ 아래의 샌드박스 config를 읽습니다. 앱이 실제로 읽는 파일을 찾으려면 Settings → Developer → Edit Config를 사용하세요.

• 로컬 서버가 표시되려면 개발자 모드가 켜져 있어야 합니다.

Machine Payments (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

결제는 .env에 CDP_API_KEY_ID와 X402_PAY_TO가 둘 다 설정된 경우에만 활성화됩니다. 두 값을 비워 두면 무상으로 실행됩니다.

데이터 모델

JSON 파일은 planar화 아니라 filing당 하나입니다: data/tariffs/srp/<slug>@<from-billing-cycle>.json. 인상 조정이 있을 때 파일이 추가만 될 뿐, 기존 파일을 수정하지 않습니다. 레지스트리는 tariff_id를 버전 목록에 연결(key)하고 요청된 청구 주기를 기준으로 선택하므로, 과거 주기에도 답할 수 있습니다.

파일은 schemas/tariff-schema.v1.1.json에 대해 검증됩니다. 테스트 스위트가 확인하는 것은: 각 구성 요소 스택이 표시된 총계로 정확히 합산되는지, 열두 청구월이 모두 정확히 하나의 계절에 매핑되는지, 달력이 만들어 낼 수 있는 모든 계절/시간대 조합에 요금이 존재하는지, 그리고 confidence: verified로 주장하는 파일에 검증한 사람과 쪽수가 명시되어 있는지 등입니다.

알려진 한계

• 2026년 11월 이후는 모델링되지 않습니다. SRP는 기본형, 임시 FPPAM, TCA 개정 등의 여러 요금표 변형을 발행하며, 11월 주적으로는 어떤 것을 적용할지는 데이터를 추가하기 전에 원 출처로 확인해야 합니다.

• 출력 크레딧 (E-28, E-13, E-14, E-16)은 별도의 credit charge 유형이 필요하며, 이는 스키마 v1.2에 해당됩니다.

• 부분 청구 주기(전입, 전출, 요금제 변경)에 대한 일할 계산(proration)은 표현되지 않습니다.

• 구조화된 가입 조건 자격... 2019년에 지붕 태양광을 설치한 고객은 E-26에 가입할 수 없지만, 자격 조건이 현재 설명문(prose)으로만 되어 있어 이런 고객이 해당 요금으로 of the price를 조회하는 것을 막을 수 없습니다.

• **반올림 규칙은 항목별로 반올림 후 합계를 낸다`는 방식입니다. SRP가 합산 후 한 번에 반올림을 하는지 여부는 실제 시간대별 사용량 청구서로 검증되지 않았습니다.

정확성 및 고지

요금 요율은 SRP가 제출한 요금표에서 옮긴 것이며, 각 파일에는 검증한 사람과 근거한 쪽수가 기록되어 있습니다. 구성 스택은 합계가 기재 총계와 일치하는지 기계 검증을 거칩니다. 그럼에도 불구하고 이 서비스는 비공식 재구현입니다: SRP와 계열 관계나 보증이 없으며, 재무적 결정의 유일한 근거가 되어선 안 됩니다. 청구서와 SRP가 공인하는 요율로 직접 확인하십시오.

신고서에 나오는 내용은 바뀔 수 있으므로, 어떤 응답에서든 retrieved_at을 확인하고 이용하려는 기간이 적용 대상인지 되돌아보세요.

Killion 앱 제작.