{
  "openapi": "3.1.0",
  "info": {
    "title": "WattFigure API",
    "version": "1.0.0",
    "description": "Household electricity running costs, U.S. state electricity prices, and EV home-charging costs. Prices from EIA Electric Power Monthly (August 2026); vehicle consumption from EPA fueleconomy.gov. Both are U.S. government works in the public domain. Figures are estimates from published averages and stated assumptions, not bills.",
    "contact": {
      "email": "hello@wattfigure.com"
    }
  },
  "servers": [
    {
      "url": "https://api.wattfigure.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Pro tier. Omit entirely for the free tier."
      }
    }
  },
  "paths": {
    "/v1/health": {
      "get": {
        "summary": "Service and dataset status",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/rates": {
      "get": {
        "summary": "Average residential electricity price for all 51 jurisdictions",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Rows to return (free tier caps at 25)",
            "schema": {
              "type": "integer"
            },
            "example": 25
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Rows to skip",
            "schema": {
              "type": "integer"
            },
            "example": 0
          }
        ],
        "responses": {
          "200": {
            "description": "Rate list"
          }
        }
      }
    },
    "/v1/rates/{state}": {
      "get": {
        "summary": "One state's rate, rank and year-over-year change",
        "parameters": [
          {
            "name": "state",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "State slug, e.g. alabama, alaska, arizona",
            "example": "alabama"
          }
        ],
        "responses": {
          "200": {
            "description": "State rate"
          },
          "404": {
            "description": "Unknown state"
          }
        }
      }
    },
    "/v1/appliances": {
      "get": {
        "summary": "Appliance catalog with usage assumptions",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Filter by category slug",
            "schema": {
              "type": "string"
            },
            "example": "kitchen"
          }
        ],
        "responses": {
          "200": {
            "description": "Appliance list"
          }
        }
      }
    },
    "/v1/appliances/{slug}": {
      "get": {
        "summary": "One appliance",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "space-heater"
          }
        ],
        "responses": {
          "200": {
            "description": "Appliance"
          },
          "404": {
            "description": "Unknown appliance"
          }
        }
      }
    },
    "/v1/vehicles": {
      "get": {
        "summary": "EV catalog (EPA consumption and range)",
        "parameters": [
          {
            "name": "make",
            "in": "query",
            "required": false,
            "description": "Filter by manufacturer",
            "schema": {
              "type": "string"
            },
            "example": "Tesla"
          }
        ],
        "responses": {
          "200": {
            "description": "Vehicle list"
          }
        }
      }
    },
    "/v1/vehicles/{slug}": {
      "get": {
        "summary": "One vehicle",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "acura-zdx-awd"
          }
        ],
        "responses": {
          "200": {
            "description": "Vehicle"
          },
          "404": {
            "description": "Unknown vehicle"
          }
        }
      }
    },
    "/v1/cost": {
      "get": {
        "summary": "Appliance running cost at a state's rate",
        "description": "Pass an appliance slug to use its stored assumptions, or pass watts directly. Query parameters override stored assumptions where both are given.",
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "required": true,
            "description": "State slug",
            "schema": {
              "type": "string"
            },
            "example": "california"
          },
          {
            "name": "appliance",
            "in": "query",
            "required": false,
            "description": "Appliance slug",
            "schema": {
              "type": "string"
            },
            "example": "space-heater"
          },
          {
            "name": "watts",
            "in": "query",
            "required": false,
            "description": "Draw in watts",
            "schema": {
              "type": "number"
            },
            "example": 1500
          },
          {
            "name": "hours_per_day",
            "in": "query",
            "required": false,
            "description": "Hours run per day",
            "schema": {
              "type": "number"
            },
            "example": 4
          },
          {
            "name": "days_per_year",
            "in": "query",
            "required": false,
            "description": "Days used per year",
            "schema": {
              "type": "number"
            },
            "example": 120
          }
        ],
        "responses": {
          "200": {
            "description": "Cost breakdown"
          },
          "400": {
            "description": "Missing state, or neither appliance nor watts"
          }
        }
      }
    },
    "/v1/charge": {
      "get": {
        "summary": "EV home charging cost at a state's rate",
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "required": true,
            "description": "State slug",
            "schema": {
              "type": "string"
            },
            "example": "texas"
          },
          {
            "name": "vehicle",
            "in": "query",
            "required": false,
            "description": "Vehicle slug",
            "schema": {
              "type": "string"
            },
            "example": "acura-zdx-awd"
          },
          {
            "name": "kwh_per_100mi",
            "in": "query",
            "required": false,
            "description": "Consumption at the wall",
            "schema": {
              "type": "number"
            },
            "example": 30
          },
          {
            "name": "miles_per_year",
            "in": "query",
            "required": false,
            "description": "Annual mileage",
            "schema": {
              "type": "number"
            },
            "example": 12000
          }
        ],
        "responses": {
          "200": {
            "description": "Charging cost breakdown"
          },
          "400": {
            "description": "Missing state, or neither vehicle nor consumption"
          }
        }
      }
    },
    "/v1/bulk/{dataset}": {
      "get": {
        "summary": "Whole dataset (pro tier)",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "dataset",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "rates",
                "appliances",
                "vehicles"
              ]
            },
            "example": "rates"
          }
        ],
        "responses": {
          "200": {
            "description": "Dataset"
          },
          "402": {
            "description": "Key required"
          }
        }
      }
    }
  }
}