{
  "openapi": "3.1.0",
  "info": {
    "title": "Tláloc — rain forecast API (Mexico City & London)",
    "version": "1.1.0",
    "description": "Free, key-less, CORS-enabled JSON API for live rain and temperature across ~27 landmarks in Mexico City (CDMX, Spanish copy) and ~24 in London (English copy). Data from Open-Meteo (WMO weather codes), refreshed every 30 minutes and edge-cached. Read-only — agents and tools are welcome to consume it.",
    "contact": { "name": "Tláloc", "url": "https://tlaloc.cloud/" },
    "license": { "name": "Weather data © Open-Meteo (CC-BY 4.0)", "url": "https://open-meteo.com/" }
  },
  "servers": [{ "url": "https://tlaloc.cloud", "description": "Production" }],
  "externalDocs": { "description": "Agent docs", "url": "https://tlaloc.cloud/llms.txt" },
  "paths": {
    "/landmarks": {
      "get": {
        "operationId": "getLandmarks",
        "summary": "Current rain outlook for every landmark (lightweight)",
        "description": "Each landmark with its current condition, temperature, next-rain time and a short Spanish outlook. Omits the hourly array — use /landmarks-detail for that.",
        "responses": {
          "200": {
            "description": "Forecast for all landmarks.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LandmarkResponse" } } }
          }
        }
      }
    },
    "/landmarks-detail": {
      "get": {
        "operationId": "getLandmarksDetail",
        "summary": "Current outlook plus a 24-hour hourly forecast for every landmark (CDMX)",
        "description": "Everything in /landmarks, plus a `reports[]` array of the next ~24 hourly forecasts per landmark.",
        "responses": {
          "200": {
            "description": "Detailed forecast for all CDMX landmarks.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LandmarkResponseDetail" } } }
          }
        }
      }
    },
    "/london/landmarks": {
      "get": {
        "operationId": "getLondonLandmarks",
        "summary": "Current rain outlook for every London landmark (lightweight)",
        "description": "Same shape as /landmarks, for London (English `description`, BST/GMT times).",
        "responses": {
          "200": {
            "description": "Forecast for all London landmarks.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LandmarkResponse" } } }
          }
        }
      }
    },
    "/london/landmarks-detail": {
      "get": {
        "operationId": "getLondonLandmarksDetail",
        "summary": "Current outlook plus a 24-hour hourly forecast for every London landmark",
        "description": "Same shape as /landmarks-detail, for London.",
        "responses": {
          "200": {
            "description": "Detailed forecast for all London landmarks.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LandmarkResponseDetail" } } }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "WeatherReport": {
        "type": "object",
        "description": "One forecast hour.",
        "required": ["time", "temperature", "code", "description", "precipitationProbability", "precipitation", "time_epoch"],
        "properties": {
          "time": { "type": "string", "description": "ISO-8601 local time (CDMX, no offset).", "example": "2026-06-06T15:00" },
          "temperature": { "type": "number", "description": "Air temperature, °C.", "example": 22.4 },
          "code": { "type": "integer", "description": "WMO weather-interpretation code (Open-Meteo).", "example": 63 },
          "description": { "type": "string", "description": "Human-readable condition for `code`.", "example": "Rain" },
          "precipitationProbability": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Chance of precipitation, %.", "example": 80 },
          "precipitation": { "type": "number", "description": "Precipitation amount, mm.", "example": 1.2 },
          "time_epoch": { "type": "integer", "description": "Unix epoch seconds for `time`.", "example": 1781899200 }
        }
      },
      "Landmark": {
        "type": "object",
        "required": ["name", "latitude", "longitude", "description", "next_rain", "raining"],
        "properties": {
          "name": { "type": "string", "example": "Bellas Artes" },
          "latitude": { "type": "string", "example": "19.43550" },
          "longitude": { "type": "string", "example": "-99.14126" },
          "description": { "type": "string", "description": "Localized one-liner outlook (Spanish for CDMX, English for London).", "example": "Lluvia probable en ~3 h" },
          "next_rain": { "type": ["integer", "null"], "description": "Unix seconds of the next rainy hour, or null.", "example": 1781899200 },
          "raining": { "type": "boolean", "description": "Whether it is raining at the current hour (language-independent).", "example": false },
          "current": { "type": "string", "description": "Current-hour condition (English).", "example": "Light Rain" },
          "currentTemp": { "type": "number", "description": "Current-hour temperature, °C.", "example": 22.4 }
        }
      },
      "LandmarkDetail": {
        "allOf": [
          { "$ref": "#/components/schemas/Landmark" },
          {
            "type": "object",
            "required": ["reports"],
            "properties": {
              "reports": { "type": "array", "items": { "$ref": "#/components/schemas/WeatherReport" }, "description": "Next ~24 hourly forecasts." }
            }
          }
        ]
      },
      "LandmarkResponse": {
        "type": "object",
        "required": ["landmarks"],
        "properties": {
          "landmarks": { "type": "array", "items": { "$ref": "#/components/schemas/Landmark" } },
          "updatedAt": { "type": "integer", "description": "Unix seconds when the data was fetched.", "example": 1781899200 }
        }
      },
      "LandmarkResponseDetail": {
        "type": "object",
        "required": ["landmarks"],
        "properties": {
          "landmarks": { "type": "array", "items": { "$ref": "#/components/schemas/LandmarkDetail" } },
          "updatedAt": { "type": "integer", "description": "Unix seconds when the data was fetched.", "example": 1781899200 }
        }
      }
    }
  }
}