{
 "openapi": "3.1.0",
 "info": {
  "title": "IPMA weather warnings: data.promptugal.news",
  "version": "v0.1.47",
  "description": "The weather warnings for every warning area of Portugal (the 18 mainland districts, Madeira and the Azores): yellow, orange and red in full, green counted.\n\nPublisher: IPMA, Instituto Português do Mar e da Atmosfera. Reuse terms: IPMA: free to copy and use for personal or public use if the use has no profit-making or offensive purpose; always name IPMA as the source. Not a warning service: follow IPMA and ANEPC.\n\nCode: Apache-2.0. Text: CC BY 4.0. The data keeps the terms of its own source (see each source card); nothing here relaxes them.",
  "license": {
   "name": "Apache-2.0 for code; each source keeps its own data terms",
   "identifier": "Apache-2.0"
  },
  "contact": {
   "name": "PrompTugal.news data",
   "url": "https://github.com/PrompTugal/PrompTugal__News__Data"
  }
 },
 "servers": [
  {
   "url": "https://data.promptugal.news",
   "description": "Production"
  }
 ],
 "externalDocs": {
  "description": "How to use the API",
  "url": "https://data.promptugal.news/api/"
 },
 "paths": {
  "/api/v1/ipma-warnings/latest.json": {
   "get": {
    "operationId": "get_ipma_warnings_latest",
    "tags": [
     "ipma-warnings"
    ],
    "summary": "IPMA weather warnings: the latest read",
    "description": "IPMA's weather warnings, every area: the active ones (yellow, orange, red) in full, and a count of the rest. Times as IPMA gives them (Portugal local time). Not a warning service: follow IPMA and ANEPC.",
    "responses": {
     "200": {
      "description": "The file",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "source": {
           "type": "string"
          },
          "title": {
           "type": "string"
          },
          "read_at": {
           "type": "string"
          },
          "provenance": {
           "type": "object",
           "properties": {
            "source": {
             "type": "string"
            },
            "page": {
             "type": "string"
            },
            "read_at": {
             "type": "string"
            },
            "by": {
             "type": "string"
            },
            "terms": {
             "type": "string"
            }
           },
           "required": [
            "source",
            "page",
            "read_at",
            "by",
            "terms"
           ]
          },
          "about": {
           "type": "string"
          },
          "counts": {
           "type": "object",
           "properties": {
            "active": {
             "type": "integer"
            },
            "by_level": {
             "type": "object",
             "properties": {
              "orange": {
               "type": "integer"
              },
              "yellow": {
               "type": "integer"
              }
             },
             "required": [
              "orange",
              "yellow"
             ]
            },
            "green": {
             "type": "integer"
            },
            "areas": {
             "type": "integer"
            }
           },
           "required": [
            "active",
            "by_level",
            "green",
            "areas"
           ]
          },
          "active": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "area": {
              "type": "string"
             },
             "area_name": {
              "type": "string"
             },
             "type": {
              "type": "string"
             },
             "type_pt": {
              "type": "string"
             },
             "level": {
              "type": "string"
             },
             "start": {
              "type": "string"
             },
             "end": {
              "type": "string"
             },
             "text": {
              "type": "string"
             }
            },
            "required": [
             "area",
             "area_name",
             "type",
             "type_pt",
             "level",
             "start",
             "end",
             "text"
            ]
           }
          }
         },
         "required": [
          "source",
          "title",
          "read_at",
          "provenance",
          "about",
          "counts",
          "active"
         ],
         "x-inferred": true
        },
        "examples": {
         "example": {
          "summary": "A real file, cut to a readable size",
          "value": {
           "source": "ipma-warnings",
           "title": "IPMA weather warnings",
           "read_at": "2026-11-18T19:17:47Z",
           "provenance": {
            "source": "https://api.ipma.pt/open-data/forecast/warnings/warnings_www.json",
            "page": "https://www.ipma.pt/en/otempo/prev-sam/",
            "read_at": "2026-11-18T19:17:47Z",
            "by": "sources/ipma-warnings/collect.mjs (code, no model; run by data@PrompTugal.dinis)",
            "terms": "IPMA: free to copy and use for personal or public use if the use has no profit-making or offensive purpose; always name IPMA as the source."
           },
           "about": "IPMA's weather warnings, every area: the active ones (yellow, orange, red) in full, and a count of the rest. Times as IPMA gives them (Portugal local time). Not a warning service: follow IPMA and ANEPC.",
           "counts": {
            "active": 27,
            "by_level": {
             "orange": 7,
             "yellow": 20
            },
            "green": 200,
            "areas": 25
           },
           "active": [
            {
             "area": "AVR",
             "area_name": "Aveiro",
             "type": "rough sea",
             "type_pt": "Agitação Marítima",
             "level": "orange",
             "start": "2026-11-18T17:19:00",
             "end": "2026-11-20T00:00:00",
             "text": "Ondas de noroeste com 5 a 6 metros, com altura máxima até 10 metros."
            },
            {
             "area": "AVR",
             "area_name": "Aveiro",
             "type": "rough sea",
             "type_pt": "Agitação Marítima",
             "level": "yellow",
             "start": "2026-11-20T00:00:00",
             "end": "2026-11-20T12:00:00",
             "text": "Ondas de noroeste com 4 a 5 metros."
            },
            {
             "area": "BJA",
             "area_name": "Beja",
             "type": "rough sea",
             "type_pt": "Agitação Marítima",
             "level": "yellow",
             "start": "2026-11-18T17:19:00",
             "end": "2026-11-20T09:00:00",
             "text": "Ondas de noroeste com 4 a 5 metros."
            }
           ]
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "No such file"
     }
    }
   }
  },
  "/api/v1/ipma-warnings/reads.json": {
   "get": {
    "operationId": "get_ipma_warnings_reads",
    "tags": [
     "ipma-warnings"
    ],
    "summary": "IPMA weather warnings: every read, newest first",
    "description": "Every run of sources/ipma-warnings/collect.mjs, newest first: each request's address, HTTP status, size, the first 16 hex of its sha256, and whether the bytes changed since the run before. The bytes and the full sha256 go to the source's vault (see card.json: latest/reads-full.json), never to git.",
    "responses": {
     "200": {
      "description": "The file",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "about": {
           "type": "string"
          },
          "source": {
           "type": "string"
          },
          "runs": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "at": {
              "type": "string"
             },
             "finished": {
              "type": "string"
             },
             "ok": {
              "type": "integer"
             },
             "failed": {
              "type": "integer"
             },
             "reads": {
              "type": "array",
              "items": {
               "type": "object",
               "properties": {
                "name": {
                 "type": "string"
                },
                "url": {
                 "type": "string",
                 "format": "uri"
                },
                "at": {
                 "type": "string"
                },
                "status": {
                 "type": [
                  "integer",
                  "string"
                 ]
                },
                "bytes": {
                 "type": "integer"
                },
                "sha256_prefix": {
                 "type": [
                  "string",
                  "null"
                 ]
                },
                "changed": {
                 "type": [
                  "boolean",
                  "string",
                  "null"
                 ]
                },
                "error": {
                 "type": "string"
                }
               },
               "required": [
                "name",
                "url",
                "at",
                "status",
                "bytes",
                "sha256_prefix",
                "changed"
               ]
              }
             }
            },
            "required": [
             "at",
             "finished",
             "ok",
             "failed",
             "reads"
            ]
           }
          }
         },
         "required": [
          "about",
          "source",
          "runs"
         ],
         "x-inferred": true
        },
        "examples": {
         "example": {
          "summary": "A real file, cut to a readable size",
          "value": {
           "about": "Every run of sources/ipma-warnings/collect.mjs, newest first: each request's address, HTTP status, size, the first 16 hex of its sha256, and whether the bytes changed since the run before. The bytes and the full sha256 go to the source's vault (see card.json: latest/reads-full.json), never to git.",
           "source": "ipma-warnings",
           "runs": [
            {
             "at": "2026-11-18T19:17:47Z",
             "finished": "2026-11-18T19:17:49Z",
             "ok": 1,
             "failed": 0,
             "reads": [
              {
               "name": "warnings",
               "url": "https://api.ipma.pt/open-data/forecast/warnings/warnings_www.json",
               "at": "2026-11-18T19:17:49Z",
               "status": 200,
               "bytes": 41072,
               "sha256_prefix": "e38a9ac18657d9d7",
               "changed": false
              }
             ]
            },
            {
             "at": "2026-11-18T19:12:24Z",
             "finished": "2026-11-18T19:12:26Z",
             "ok": 1,
             "failed": 0,
             "reads": [
              {
               "name": "warnings",
               "url": "https://api.ipma.pt/open-data/forecast/warnings/warnings_www.json",
               "at": "2026-11-18T19:12:26Z",
               "status": 200,
               "bytes": 41072,
               "sha256_prefix": "e38a9ac18657d9d7",
               "changed": false
              }
             ]
            },
            {
             "at": "2026-11-18T19:08:52Z",
             "finished": "2026-11-18T19:08:54Z",
             "ok": 1,
             "failed": 0,
             "reads": [
              {
               "name": "warnings",
               "url": "https://api.ipma.pt/open-data/forecast/warnings/warnings_www.json",
               "at": "2026-11-18T19:08:54Z",
               "status": 200,
               "bytes": 41072,
               "sha256_prefix": "e38a9ac18657d9d7",
               "changed": false
              }
             ]
            }
           ]
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "No such file"
     }
    }
   }
  },
  "/api/v1/ipma-warnings/card.json": {
   "get": {
    "operationId": "get_ipma_warnings_card",
    "tags": [
     "ipma-warnings"
    ],
    "summary": "IPMA weather warnings: the card",
    "description": "Who publishes the source, its reuse terms, the schedule, who owns it, what runs by code, by agents and by people, and the vault.",
    "responses": {
     "200": {
      "description": "The file",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "id": {
           "type": "string"
          },
          "title": {
           "type": "string"
          },
          "what": {
           "type": "string"
          },
          "publisher": {
           "type": "string"
          },
          "owner": {
           "type": "string"
          },
          "collector": {
           "type": "string"
          },
          "source_home": {
           "type": "string"
          },
          "reader_page": {
           "type": "string"
          },
          "schedule": {
           "type": "object",
           "properties": {
            "cadence": {
             "type": "string"
            },
            "how": {
             "type": "string"
            }
           },
           "required": [
            "cadence",
            "how"
           ]
          },
          "terms": {
           "type": "object",
           "properties": {
            "summary": {
             "type": "string"
            },
            "page": {
             "type": "string"
            },
            "read_at": {
             "type": "string"
            },
            "quote": {
             "type": "string"
            },
            "quote_lang": {
             "type": "string"
            },
            "republish": {
             "type": "string"
            },
            "open_question": {
             "type": "string"
            }
           },
           "required": [
            "summary",
            "page",
            "read_at",
            "quote",
            "quote_lang",
            "republish",
            "open_question"
           ]
          },
          "api": {
           "type": "object",
           "properties": {
            "latest": {
             "type": "string"
            },
            "reads": {
             "type": "string"
            },
            "card": {
             "type": "string"
            },
            "openapi": {
             "type": "string"
            },
            "page": {
             "type": "string"
            }
           },
           "required": [
            "latest",
            "reads",
            "card",
            "openapi",
            "page"
           ]
          },
          "vault": {
           "type": "object",
           "properties": {
            "id": {
             "type": "string"
            },
            "name": {
             "type": "string"
            },
            "endpoint": {
             "type": "string"
            },
            "read_key": {
             "type": "string"
            },
            "clone": {
             "type": "string"
            },
            "layout": {
             "type": "string"
            },
            "note": {
             "type": "string"
            },
            "created": {
             "type": "string"
            },
            "by": {
             "type": "string"
            }
           },
           "required": [
            "id",
            "name",
            "endpoint",
            "read_key",
            "clone",
            "layout",
            "note",
            "created",
            "by"
           ]
          },
          "split": {
           "type": "object",
           "properties": {
            "code": {
             "type": "array",
             "items": {
              "type": "string"
             }
            },
            "agents": {
             "type": "array",
             "items": {
              "type": "string"
             }
            },
            "people": {
             "type": "array",
             "items": {
              "type": "string"
             }
            }
           },
           "required": [
            "code",
            "agents",
            "people"
           ]
          },
          "cost": {
           "type": "object",
           "properties": {
            "per_run_tokens": {
             "type": "integer"
            },
            "per_run_model_cost_usd": {
             "type": "integer"
            },
            "runner": {
             "type": "string"
            },
            "build_tokens": {
             "type": "string"
            },
            "note": {
             "type": "string"
            }
           },
           "required": [
            "per_run_tokens",
            "per_run_model_cost_usd",
            "runner",
            "build_tokens",
            "note"
           ]
          },
          "since": {
           "type": "string"
          }
         },
         "required": [
          "id",
          "title",
          "what",
          "publisher",
          "owner",
          "collector",
          "source_home",
          "reader_page",
          "schedule",
          "terms",
          "api",
          "vault",
          "split",
          "cost",
          "since"
         ],
         "x-inferred": true
        },
        "examples": {
         "example": {
          "summary": "A real file, cut to a readable size",
          "value": {
           "id": "ipma-warnings",
           "title": "IPMA weather warnings",
           "what": "The weather warnings for every warning area of Portugal (the 18 mainland districts, Madeira and the Azores): yellow, orange and red in full, green counted.",
           "publisher": "IPMA, Instituto Português do Mar e da Atmosfera",
           "owner": "data@PrompTugal.dinis",
           "collector": "sources/ipma-warnings/collect.mjs",
           "source_home": "https://api.ipma.pt/open-data/forecast/warnings/warnings_www.json",
           "reader_page": "https://www.ipma.pt/en/otempo/prev-sam/",
           "schedule": {
            "cadence": "hourly",
            "how": "the Pages workflow (.github/workflows/pages.yml), on a schedule at 17 minutes past each hour, and on every push to dev"
           },
           "terms": {
            "summary": "IPMA: free to copy and use for personal or public use if the use has no profit-making or offensive purpose; always name IPMA as the source.",
            "page": "https://api.ipma.pt/",
            "read_at": "2026-11-17",
            "quote": "O Utilizador pode copiar, importar ou utilizar gratuitamente informações ou símbolos nacionais existentes neste site para uso pessoal ou público desde que dessa utilização não decorram finalidades lucrativas ou ofensivas. O Utilizador deve referir, sempre, a fonte de informação.",
            "quote_lang": "pt",
            "republish": "with conditions: attribution to IPMA; no profit-making purpose",
            "open_question": "Whether a paid reading meter on a PrompTugal site counts as a profit-making purpose under these terms is for Dinis to decide (or to ask IPMA). Until then the data site itself carries no meter."
           },
           "api": {
            "latest": "https://data.promptugal.news/api/v1/ipma-warnings/latest.json",
            "reads": "https://data.promptugal.news/api/v1/ipma-warnings/reads.json",
            "card": "https://data.promptugal.news/api/v1/ipma-warnings/card.json",
            "openapi": "https://data.promptugal.news/api/v1/ipma-warnings/openapi.json",
            "page": "https://data.promptugal.news/sources/ipma-warnings/"
           },
           "vault": {
            "id": "4ol6ht3d",
            "name": "promptugal-data-ipma-warnings",
            "endpoint": "https://dev.send.sgraph.ai",
            "read_key": "sgit_public_read_abcdeee55bcbc6bf3598876a7344effaf15d873a625f8ab00c09afe2afc2b531",
            "clone": "sgit clone sgit_public_read_abcdeee55bcbc6bf3598876a7344effaf15d873a625f8ab00c09afe2afc2b531:4ol6ht3d",
            "layout": "latest/<file> (the bytes as received, overwritten each run), <yyyy>/<mm>/<dd>/<hh>/<file>-<hhmmss>.json (a dated copy only when the bytes changed), latest/reads.json",
            "note": "Public read key: the source is public, so anyone may read the vault. A read key is derived one way and cannot write. The write key is never in this repository.",
            "created": "2026-11-17",
            "by": "data@PrompTugal.dinis"
           },
           "split": {
            "code": [
             "the collector reads the source and writes latest.json, reads.json and the vault copy",
             "GitHub Actions runs it every hour and deploys the site",
             "the build makes the API, the OpenAPI description and the pages"
            ],
            "agents": [
             "data@PrompTugal.dinis (Opus) wrote the collector, this card and the pages on 17 November 2026; data.dev@ and data.design@ (Sonnet) wrote parts of the site build and the design variations"
            ],
            "people": [
             "Dinis Cruz instructs; no person has checked the values yet (not reviewed)"
            ]
           },
           "cost": {
            "per_run_tokens": 0,
            "per_run_model_cost_usd": 0,
            "runner": "GitHub Actions on a public repository: no charge (GitHub's terms for public repositories); about 3 minutes a run for all sources together (measured locally, 17 November 2026)",
            "build_tokens": "not measured: accountant@'s ledger is not running on this account; to be added when it is",
            "note": "Code only: no model is called when the data is collected."
           },
           "since": "2026-11-17"
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "No such file"
     }
    }
   }
  },
  "/api/v1/ipma-warnings/openapi.json": {
   "get": {
    "operationId": "get_ipma_warnings_openapi",
    "tags": [
     "ipma-warnings"
    ],
    "summary": "IPMA weather warnings: this document",
    "responses": {
     "200": {
      "description": "The file",
      "content": {
       "application/json": {
        "schema": {
         "type": "string"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/ipma-warnings/raw/{file}": {
   "get": {
    "operationId": "get_ipma_warnings_raw",
    "tags": [
     "ipma-warnings"
    ],
    "summary": "IPMA weather warnings: the publisher's own file, as read",
    "description": "The bytes IPMA served at the latest read, parsed and re-serialised, unprocessed. The address each came from is in reads.json.",
    "parameters": [
     {
      "name": "file",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "warnings.json"
       ]
      },
      "example": "warnings.json"
     }
    ],
    "responses": {
     "200": {
      "description": "The file",
      "content": {
       "application/json": {
        "schema": {
         "type": "array",
         "items": {
          "type": "object",
          "properties": {
           "text": {
            "type": "string"
           },
           "awarenessTypeName": {
            "type": "string"
           },
           "idAreaAviso": {
            "type": "string"
           },
           "startTime": {
            "type": "string"
           },
           "awarenessLevelID": {
            "type": "string"
           },
           "endTime": {
            "type": "string"
           }
          },
          "required": [
           "text",
           "awarenessTypeName",
           "idAreaAviso",
           "startTime",
           "awarenessLevelID",
           "endTime"
          ]
         },
         "x-inferred": true
        },
        "examples": {
         "warnings.json": {
          "summary": "A real file, cut to a readable size",
          "value": [
           {
            "text": "",
            "awarenessTypeName": "Agitação Marítima",
            "idAreaAviso": "BGC",
            "startTime": "2026-11-18T17:19:00",
            "awarenessLevelID": "green",
            "endTime": "2026-11-21T17:00:00"
           },
           {
            "text": "",
            "awarenessTypeName": "Nevoeiro",
            "idAreaAviso": "BGC",
            "startTime": "2026-11-18T17:19:00",
            "awarenessLevelID": "green",
            "endTime": "2026-11-21T17:00:00"
           },
           {
            "text": "",
            "awarenessTypeName": "Tempo Quente",
            "idAreaAviso": "BGC",
            "startTime": "2026-11-18T17:19:00",
            "awarenessLevelID": "green",
            "endTime": "2026-11-21T17:00:00"
           }
          ]
         }
        }
       }
      }
     },
     "404": {
      "description": "No such file"
     }
    }
   }
  }
 },
 "tags": [
  {
   "name": "ipma-warnings",
   "description": "The weather warnings for every warning area of Portugal (the 18 mainland districts, Madeira and the Azores): yellow, orange and red in full, green counted."
  }
 ],
 "x-source": {
  "id": "ipma-warnings",
  "card": "https://data.promptugal.news/api/v1/ipma-warnings/card.json",
  "page": "https://data.promptugal.news/sources/ipma-warnings/"
 }
}
