{
 "openapi": "3.1.0",
 "info": {
  "title": "MeterWise open data",
  "version": "1",
  "description": "Static, read-only JSON files: heat pump vs. furnace and AC results for each U.S. electric utility we cover, for a typical 1,800 sq ft home. No key, CORS open, CC BY 4.0. Start with the ZIP lookup.",
  "license": {
   "name": "CC BY 4.0",
   "url": "https://creativecommons.org/licenses/by/4.0/"
  },
  "contact": {
   "email": "contact@meterwise.app"
  }
 },
 "servers": [
  {
   "url": "https://meterwise.app"
  }
 ],
 "paths": {
  "/data/v1/zip/{zip3}.json": {
   "get": {
    "summary": "Utilities serving each ZIP code in a 3-digit prefix",
    "description": "Returns {updated, zips: {\"02139\": [{utility, state, url, markdown_url, json_url, verdict}]}}. 404 if no covered utility.",
    "parameters": [
     {
      "name": "zip3",
      "in": "path",
      "required": true,
      "description": "First three digits of the ZIP code",
      "schema": {
       "type": "string"
      },
      "example": "021"
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ZipLookup"
        }
       }
      }
     }
    }
   }
  },
  "/data/v1/utilities/{state}/{slug}.json": {
   "get": {
    "summary": "Full result for one utility",
    "description": "Quick answer, verdict, inputs (tariff, weather, fuel prices) and each option's installed and running costs. Get the exact path from json_url.",
    "parameters": [
     {
      "name": "state",
      "in": "path",
      "required": true,
      "description": "Two-letter state code, lower case",
      "schema": {
       "type": "string"
      },
      "example": "ma"
     },
     {
      "name": "slug",
      "in": "path",
      "required": true,
      "description": "Utility slug",
      "schema": {
       "type": "string"
      },
      "example": "eversource"
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Utility"
        }
       }
      }
     }
    }
   }
  },
  "/data/v1/utilities.json": {
   "get": {
    "summary": "Summary of every covered utility",
    "description": "One row per utility page.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/UtilityList"
        }
       }
      }
     }
    }
   }
  },
  "/data/v1/states.json": {
   "get": {
    "summary": "Per-state summary",
    "description": "Averages, verdict counts and data notes per state.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Object"
        }
       }
      }
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "Object": {
    "type": "object"
   },
   "ZipLookup": {
    "type": "object",
    "properties": {
     "updated": {
      "type": "string"
     },
     "zips": {
      "type": "object",
      "additionalProperties": {
       "type": "array",
       "items": {
        "type": "object",
        "properties": {
         "utility": {
          "type": "string"
         },
         "state": {
          "type": "string"
         },
         "url": {
          "type": "string"
         },
         "markdown_url": {
          "type": "string"
         },
         "json_url": {
          "type": "string"
         },
         "verdict": {
          "type": "string"
         }
        }
       }
      }
     }
    }
   },
   "UtilityList": {
    "type": "object",
    "properties": {
     "updated": {
      "type": "string"
     },
     "count": {
      "type": "integer"
     },
     "utilities": {
      "type": "array",
      "items": {
       "type": "object"
      }
     }
    }
   },
   "Utility": {
    "type": "object",
    "properties": {
     "utility": {
      "type": "string"
     },
     "state": {
      "type": "string"
     },
     "url": {
      "type": "string"
     },
     "updated": {
      "type": "string"
     },
     "quick_answer": {
      "type": "string",
      "description": "One paragraph, quotable, with the date"
     },
     "verdict": {
      "type": "string",
      "enum": [
       "heat pump ahead at any quote",
       "depends on quotes",
       "like-for-like ahead at any quote"
      ]
     },
     "heat_pump": {
      "type": "object",
      "properties": {
       "annual_saving_vs_like_for_like": {
        "type": "integer",
        "description": "US dollars per year; negative = costs more to run"
       },
       "break_even_quote_gap": {
        "type": "integer",
        "description": "US dollars; how much more the heat pump quote can be and still win over 15 years"
       }
      }
     },
     "options": {
      "type": "array",
      "items": {
       "type": "object"
      }
     },
     "citation": {
      "type": "string"
     }
    }
   }
  }
 }
}