SRP Utility Tariff API

Tarifas residenciales de electricidad exactas y facturas detalladas para SRP (Salt River Project) (área metropolitana de Phoenix, Arizona), calculadas a partir de las tarifas oficiales de SRP en lugar de estimaciones. Cada respuesta cita el documento y la página de la que proviene.

En vivo: https://utility-api-jn9g.onrender.com · Documentación: /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": [ ... ]
}

Por qué existe

Las tarifas residenciales de SRP son públicas, pero en la práctica difíciles de calcular. Los precios varían por hora, día de la semana, temporada y día festivo observado, en una docena de planes cuyas definiciones no coinciden:

• Las temporadas se definen por ciclo de facturación. Las horas punta se definen por fecha de calendario. En E-26, el verano significa los ciclos de facturación de mayo, junio, septiembre y octubre, pero la ventana punta de 2–8 p.m. va del 1 de mayo al 31 de octubre según la fecha de calendario. Un ciclo de facturación que cruza el 31 de octubre recibe los precios de una temporada y dos clasificaciones horarias diferentes. Colapsar todo en un único campo de "temporada" factura erróneamente cada mes de transición.

• Las tarifas se presentan en hora estándar de las Montañas Rocosas y Arizona no observa el horario de verano. Cualquier biblioteca genérica de tarifas por tiempo de uso que ajuste por horario de verano se equivoca en una hora durante medio año.

• Las tarifas son paquetes de componentes desglosados, no números únicos. El ajuste de combustible y energía comprada está dentro del paquete y se mueve según su propio calendario, por lo que debe mantenerse separable.

• Los días festivos suspenden algunos períodos pero no otros. En E-28, el horario pico se suspende en Navidad mientras que el super-valle sigue aplicándose.

Este servicio modela todo eso a partir de las presentaciones oficiales y muestra su trabajo.

Related MCP server: ratebook-mcp

Cobertura

Llame a GET / o GET /v1/tariff/plans para obtener la respuesta actualizada. A partir de la última carga de datos:

Solo residencial. Las solicitudes fuera de un ciclo de facturación cubierto devuelven un 422 con los períodos que sí están cubiertos.

Qué rechaza, y por qué

Esta es la parte que conviene leer antes de confiar en el servicio.

Planes no modelados. E-28 paga un crédito por kWh exportado que el modelo de datos actual no puede expresar. En lugar de devolver una factura incorrecta para cualquier cliente con paneles solares en tejado, el servicio rechaza E-28 por completo y lo indica explícitamente. Solucionar esto es un cambio de esquema, recogido más abajo.

Fechas no cubiertas. Cada archivo cubre un ciclo de facturación específico. Si se solicita un ciclo que ningún documento oficial regula, se devuelve un 422 que indica lo que sí está cubierto — nunca una tarifa extrapolada.

Disposiciones que no pueden ser datos. Cada tarifa incluye una lista unmodeled_provisions que se expone como caveats en las respuestas: el límite anual de 300 000 USD de eficiencia energética, la facultad de SRP de ajustar el factor de combustible entre presentaciones, y el traspaso de impuestos y tasas gubernamentales. Son condiciones reales que pueden afectar el importe, y se declaran en lugar de ocultarse.

Impuestos. No incluidos. Las tasas estatales, del condado y municipales dependen de la dirección del servicio.

Servidor MCP

La misma API está disponible como servidor MCP, para que los asistentes puedan consultarla directamente. Tres herramientas: list_srp_plans, get_srp_rate, calculate_srp_bill. Sin pago, sin llamada de red.

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

Notas de Windows aprendidas a la fuerza:

• Instala las dependencias con el intérprete explícito: & ".\.venv\Scripts\python.exe" -m pip install -r requirements.txt. Si usas otro intérprete, puedes obtener ModuleNotFoundError.

• Claude Desktop puede leer una ruta de configuración distinta. Usa Settings → Developer → Edit Config para encontrar el archivo que la aplicación realmente lee.

Pago por uso (x402)

Los endpoints HTTP también se pueden pagar por llamada mediante x402: un agente recibe un 402, paga en USDC y reintenta, sin cuenta ni clave API. Actualmente en Base Sepolia (testnet); la red vigente se informa en GET /.

/ y /v1/tariff/plans son gratuitos por diseño: quien llama debe poder saber qué está cubierto antes de decidir pagar.

Ejecución local

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

El pago solo se activa si CDP_API_KEY_ID y X402_PAY_TO están definidos en .env. Déjalos sin definir para ejecutar sin pago.

Modelo de datos

Un archivo JSON por presentación (filing), no por plan: data/tariffs/srp/<slug>@<ciclo-de-facturación-inicial>.json. Un caso tarifario o un ajuste temporal añade un archivo; nunca modifica uno existente. El registro indexa tariff_id por lista de versiones y selecciona según el ciclo de facturación solicitado, de modo que los ciclos anteriores siguen siendo consultables.

Los archivos se validan contra schemas/tariff-schema.v1.2.json. La suite de pruebas comprueba que cada paquete de componentes suma su total impreso, que los doce meses caen exactamente en una temporada, que cada combinación temporada/período que el calendario puede producir tiene precio, y que un archivo que declara confidence: verified también nombra quién lo verificó y en qué páginas.

Limitaciones conocidas

• A partir de noviembre de 2026 no está modelado. SRP publica varias versiones del libro de tarifas (FPPA, revisiones de TCA) y cuál rige para el ciclo de noviembre debe confirmarse contra la fuente antes de agregar datos.

• Créditos de exportación (E-28, E-13, E-14) necesitan un tipo de cargo por crédito — esquema v1.2.

• Prorrateo para ciclos de facturación parciales (mudanza de entrada, mudanza de salida) no está expresado.

• Elegibilidad estructurada. Un cliente con energía solar en tejado de 2019 no puede estar en E-26, pero la elegibilidad es actualmente texto descriptivo, así que nada impide que quien llama le cotice en ese plan.

Precisión y descargo de responsabilidad

Las tarifas se transcriben de las presentaciones oficiales de SRP y cada archivo registra quién las verificó y contra qué páginas. Los paquetes de componentes se verifican automáticamente para que sumen los totales impresos. Aun así, esto es una reimplementación no oficial: no está afiliada ni respaldada por SRP, y no debe ser la única base para una decisión financiera. Verifica contra tu propia factura y las tarifas publicadas por SRP.

Las presentaciones cambian. Comprueba retrieved_at en cualquier respuesta y confirma que el ciclo que te interesa está cubierto.

Creado por Killion Apps.