{
 "openapi": "3.1.0",
 "info": {
  "title": "Porchlight Weather API",
  "version": "1.0.0",
  "summary": "Keyless JSON forecasts for US places and ZIPs, from the National Weather Service.",
  "description": "Resolve a US place name or 5-digit ZIP offline (Census 2024 Gazetteer), then read the NWS forecast for it: current conditions, 14 half-day periods, 24 hourly periods, active alerts, and a one-line plain-English note. No authentication. CORS open. Responses cached 5 to 10 minutes."
 },
 "servers": [
  {
   "url": "https://porchlight-weather.pages.dev"
  }
 ],
 "paths": {
  "/api/places": {
   "get": {
    "operationId": "searchPlaces",
    "summary": "Find US places or a ZIP by text",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string",
       "maxLength": 80
      },
      "description": "Place name, 'name, ST', 'name State', a slug like sacramento-ca, or a 5-digit ZIP."
     },
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 10,
       "default": 5
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Matches, best first",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PlacesResponse"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "503": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/api/forecast": {
   "get": {
    "operationId": "getForecast",
    "summary": "Forecast for a place, ZIP or coordinate",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "schema": {
       "type": "string",
       "maxLength": 80
      },
      "description": "Same forms as /api/places. The best match is used."
     },
     {
      "name": "lat",
      "in": "query",
      "schema": {
       "type": "number",
       "minimum": -90,
       "maximum": 90
      }
     },
     {
      "name": "lon",
      "in": "query",
      "schema": {
       "type": "number",
       "minimum": -180,
       "maximum": 180
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Forecast",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ForecastResponse"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "404": {
      "$ref": "#/components/responses/Error"
     },
     "502": {
      "$ref": "#/components/responses/Error"
     },
     "503": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  }
 },
 "components": {
  "responses": {
   "Error": {
    "description": "Plain error",
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/Error"
      }
     }
    }
   }
  },
  "schemas": {
   "Error": {
    "type": "object",
    "required": [
     "error",
     "message"
    ],
    "properties": {
     "error": {
      "type": "string",
      "enum": [
       "missing_query",
       "query_too_long",
       "unknown_place",
       "bad_coordinates",
       "no_grid",
       "upstream",
       "gazetteer_unavailable"
      ]
     },
     "message": {
      "type": "string"
     }
    }
   },
   "Place": {
    "type": "object",
    "required": [
     "name",
     "state",
     "kind",
     "lat",
     "lon",
     "slug"
    ],
    "properties": {
     "name": {
      "type": "string"
     },
     "state": {
      "type": "string"
     },
     "kind": {
      "type": "string",
      "description": "city, town, village, borough, CDP, zcta, point, ..."
     },
     "lat": {
      "type": "number"
     },
     "lon": {
      "type": "number"
     },
     "id": {
      "type": [
       "string",
       "null"
      ],
      "description": "Census GEOID or ZIP"
     },
     "slug": {
      "type": [
       "string",
       "null"
      ],
      "description": "Stable query form, e.g. sacramento-ca"
     },
     "near": {
      "type": [
       "string",
       "null"
      ],
      "description": "For a ZIP: nearest gazetteer place"
     },
     "matched": {
      "type": "string",
      "description": "Present when a fuzzy match was used"
     }
    }
   },
   "Period": {
    "type": "object",
    "properties": {
     "name": {
      "type": "string"
     },
     "startTime": {
      "type": "string",
      "format": "date-time"
     },
     "endTime": {
      "type": "string",
      "format": "date-time"
     },
     "isDaytime": {
      "type": "boolean"
     },
     "temperature": {
      "type": "number"
     },
     "temperatureUnit": {
      "type": "string"
     },
     "shortForecast": {
      "type": "string"
     },
     "detailedForecast": {
      "type": "string"
     },
     "pop": {
      "type": [
       "integer",
       "null"
      ],
      "description": "Probability of precipitation, percent"
     },
     "windSpeed": {
      "type": "string"
     },
     "windDirection": {
      "type": "string"
     }
    }
   },
   "Alert": {
    "type": "object",
    "properties": {
     "event": {
      "type": "string"
     },
     "headline": {
      "type": "string"
     },
     "severity": {
      "type": "string"
     },
     "urgency": {
      "type": "string"
     },
     "onset": {
      "type": "string"
     },
     "ends": {
      "type": "string"
     },
     "sender": {
      "type": "string"
     },
     "description": {
      "type": "string"
     }
    }
   },
   "PlacesResponse": {
    "type": "object",
    "properties": {
     "query": {
      "type": "string"
     },
     "match": {
      "type": "string",
      "enum": [
       "exact",
       "prefix",
       "fuzzy",
       "zip",
       "none"
      ]
     },
     "results": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Place"
      }
     },
     "source": {
      "type": "string"
     }
    }
   },
   "ForecastResponse": {
    "type": "object",
    "properties": {
     "place": {
      "$ref": "#/components/schemas/Place"
     },
     "point": {
      "type": "object",
      "properties": {
       "office": {
        "type": "string"
       },
       "gridX": {
        "type": "integer"
       },
       "gridY": {
        "type": "integer"
       },
       "timezone": {
        "type": "string"
       }
      }
     },
     "now": {
      "$ref": "#/components/schemas/Period"
     },
     "porch_line": {
      "type": "string"
     },
     "periods": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Period"
      }
     },
     "hourly": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Period"
      }
     },
     "alerts": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Alert"
      }
     },
     "updated": {
      "type": [
       "string",
       "null"
      ]
     },
     "notes": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "source": {
      "type": "object",
      "properties": {
       "name": {
        "type": "string"
       },
       "points": {
        "type": "string"
       },
       "forecast": {
        "type": "string"
       },
       "hourly": {
        "type": "string"
       },
       "alerts": {
        "type": "string"
       }
      }
     },
     "fetched_at": {
      "type": "string",
      "format": "date-time"
     },
     "cache": {
      "type": "string",
      "enum": [
       "hit",
       "miss",
       "stale"
      ],
      "description": "hit: every upstream read came from the edge cache; miss: at least one went to api.weather.gov; stale: upstream failed and the last cached forecast (up to 48 h) was served."
     },
     "stale_since": {
      "type": "string",
      "format": "date-time",
      "description": "Present only when the forecast service was down and this is the last cached forecast; the UTC time it was fetched. notes[0] says the same in words."
     }
    }
   }
  }
 }
}
