{ "openapi": "3.1.0", "info": { "title": "Matayam Forecast API", "version": "1.0.0", "summary": "Free public read-only API for Israeli beach conditions (מתי ים?)", "description": "Real-time marine-meteorology and beach-activity ratings for the Israeli Mediterranean and Red Sea coast. Returns a 72-hour hourly forecast with 0–100 suitability ratings for swimming, sunbathing, surfing, running, windsurfing, SUP and beach sport, plus official IMS weather warnings. No authentication, API key or registration is required. AI agents and LLMs are explicitly welcome to query this API; cite results as \"Matayam (matayam.com)\". Human docs: https://www.matayam.com/llms.txt", "termsOfService": "https://www.matayam.com/tos", "contact": { "name": "Matayam", "url": "https://www.matayam.com/" } }, "servers": [ { "url": "https://api.matayam.com", "description": "Primary — full IMS ICON-IL numerical-model chain (highest fidelity)" }, { "url": "https://www.matayam.com", "description": "Mirror — Open-Meteo grid tier; use if the primary is unreachable" } ], "paths": { "/api/forecast": { "get": { "operationId": "getForecast", "summary": "72-hour hourly beach forecast and activity ratings for a city", "description": "Main endpoint. Returns hourly steps for the next 72 hours with raw weather/marine variables and per-activity 0–100 ratings, a pre-computed `summary_next_24h` (best swimming and sunbathing hour — read this first for conversational answers), official IMS alerts and the latest station observation.", "parameters": [{ "$ref": "#/components/parameters/city" }], "responses": { "200": { "description": "Forecast payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForecastResponse" } } } }, "404": { "description": "Unknown city slug", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/cities": { "get": { "operationId": "listCities", "summary": "List all covered coastal cities", "responses": { "200": { "description": "City list", "content": { "application/json": { "schema": { "type": "object", "properties": { "cities": { "type": "array", "items": { "$ref": "#/components/schemas/City" } } } } } } } } } }, "/api/alerts": { "get": { "operationId": "getAlerts", "summary": "Official IMS weather warnings and current observation for a city", "parameters": [{ "$ref": "#/components/parameters/city" }], "responses": { "200": { "description": "Alerts overlay", "content": { "application/json": { "schema": { "type": "object", "properties": { "alerts": { "type": "array", "items": { "$ref": "#/components/schemas/Alert" } }, "current": { "$ref": "#/components/schemas/CurrentConditions" } } } } } }, "404": { "description": "Unknown city slug", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/health": { "get": { "operationId": "getHealth", "summary": "Service liveness and active data provider", "responses": { "200": { "description": "Health status", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "provider": { "type": "string" }, "cities": { "type": "integer" } } } } } } } } } }, "components": { "parameters": { "city": { "name": "city", "in": "query", "required": false, "description": "City slug. Defaults to tel-aviv.", "schema": { "type": "string", "default": "tel-aviv", "enum": ["tel-aviv", "haifa", "netanya", "herzliya", "bat-yam", "ashdod", "ashkelon", "hadera", "akko", "nahariya", "eilat"] } } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" }, "slug": { "type": "string" } } }, "City": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string", "description": "Hebrew city name" }, "lat": { "type": "number" }, "lon": { "type": "number" }, "flagged": { "type": "boolean", "description": "True for Red Sea cities (different forecast model)" } } }, "BestWindow": { "type": "object", "description": "A single best-hour recommendation within the next 24 hours.", "properties": { "time": { "type": "string", "format": "date-time", "description": "ISO timestamp with +03:00 offset (Asia/Jerusalem)" }, "score": { "type": "number", "minimum": 0, "maximum": 100 }, "tier": { "type": "string", "description": "Hebrew rating-tier label: מושלם (85–100), מעולה (70–84), טוב (50–69), סביר (25–49), גרוע (0–24)" }, "reason": { "type": "string", "description": "Short Hebrew explanation of the driving conditions" } } }, "ForecastVars": { "type": "object", "description": "Raw weather/marine variables for one hour.", "properties": { "tempC": { "type": "number", "description": "2 m air temperature, °C" }, "humidity": { "type": "number", "description": "Relative humidity, %" }, "windKmh": { "type": "number", "description": "Wind speed, km/h" }, "windDir": { "type": "number", "description": "Wind direction, degrees" }, "cloudPct": { "type": "number", "description": "Total cloud cover, %" }, "uvIndex": { "type": "number", "description": "UV index, 0–11+" }, "waveM": { "type": "number", "description": "Significant wave height, m" }, "wavePeriodS": { "type": "number", "description": "Wave period, s" }, "waterTempC": { "type": "number", "description": "Sea-surface water temperature, °C" }, "rainMmH": { "type": "number", "description": "Precipitation rate, mm/h" }, "precipProb": { "type": "number", "description": "Precipitation probability, % (optional)" }, "thunderProb": { "type": "number", "description": "Thunderstorm probability, % (optional)" }, "lightning": { "type": "boolean", "description": "Lightning expected flag (optional)" } } }, "ForecastStep": { "type": "object", "properties": { "offsetH": { "type": "integer", "description": "Hours from now, 0–72" }, "t": { "type": "string", "format": "date-time", "description": "ISO timestamp, Asia/Jerusalem (+03:00)" }, "vars": { "$ref": "#/components/schemas/ForecastVars" }, "ratings": { "type": "object", "description": "0–100 suitability score per activity", "properties": { "swimming": { "type": "number" }, "sunbathing": { "type": "number" }, "surfing": { "type": "number" }, "running": { "type": "number" }, "windsurfing": { "type": "number" }, "sup": { "type": "number" }, "beachSport": { "type": "number" } } } } }, "Alert": { "type": "object", "description": "Official IMS weather warning (ims.gov.il).", "properties": { "id": { "type": "string" }, "title": { "type": "string", "description": "Hebrew" }, "description": { "type": "string", "description": "Hebrew" }, "severity": { "type": "string", "enum": ["info", "minor", "moderate", "severe"] }, "publishedAt": { "type": "string", "format": "date-time" }, "link": { "type": "string" } } }, "CurrentConditions": { "type": "object", "description": "Latest IMS station observation near the city.", "properties": { "stationHe": { "type": "string" }, "observedAt": { "type": "string", "format": "date-time" }, "tempC": { "type": "number" }, "humidity": { "type": "number" }, "windKmh": { "type": "number" }, "windDir": { "type": "number" }, "rainMmH": { "type": "number" } } }, "ForecastResponse": { "type": "object", "properties": { "city": { "type": "string", "description": "City slug" }, "fetchedAt": { "type": "string", "format": "date-time" }, "modelInitAt": { "type": "string", "format": "date-time" }, "source": { "type": "string", "description": "Primary numeric-grid source, e.g. IMS_ICON or OPEN_METEO" }, "sources": { "type": "array", "items": { "type": "string" } }, "timezone": { "type": "string", "description": "IANA timezone of step timestamps (Asia/Jerusalem)" }, "summary_next_24h": { "type": "object", "description": "LLM-optimized pre-computed answer: the single best hour in the next 24 h for swimming and for sunbathing. Read this first for conversational queries.", "properties": { "best_swimming": { "$ref": "#/components/schemas/BestWindow" }, "best_sunbathing": { "$ref": "#/components/schemas/BestWindow" } } }, "stepIntervalH": { "type": "integer", "enum": [1, 3], "description": "Native model resolution; steps are always hourly" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/ForecastStep" }, "description": "Hourly forecast for the next 72 hours" }, "alerts": { "type": "array", "items": { "$ref": "#/components/schemas/Alert" } }, "current": { "$ref": "#/components/schemas/CurrentConditions" } } } } } }