openapi: 3.0.1
info:
  title: MeteoAlarm API
  description: MeteoAlarm is an Early Warning Dissemination System that visualises, aggregates, and accessibly provides awareness information from 38 European National Meteorological and Hydrological Services. MeteoAlarm aggregates and accessibly provides warnings from the MeteoAlarm Members through this OGC API.  
  version: 1.0.0
servers:
  - url: https://api.meteoalarm.org/edr/v1
    description: MeteoAlarm Api endpoint
  - url: https://api-test.meteoalarm.org/edr/v1
    description: MeteoAlarm Api endpoint - TEST system
  - url: https://api.met.dev/edr/v1
    description: MeteoAlarm Api endpoint - STAGING system
paths:


  /:
    get:
      summary: MQTT - Real-time warnings are served through MQTT.
      responses: 
        '200':
      description: >
          Real-time warnings are served through MQTT. Subscribe to the listed topics to receive updates.
          The API requires a valid authentication token.
        
            - broker: mqtts://api.meteoalarm.org
            - broker-test: mqtts://api-test.meteoalarm.org
            - qos: 1
            - retain: true
            - messageFormat: GeoJSON
            - authentication: token
            
          topics:
            - warnings-ALL
            - warnings-MT
            - warnings-SI
            - warnings-EE
            - warnings-SE
            - warnings-FR
            - warnings-LT
            - warnings-PL
            - warnings-RO
            - warnings-IT
            - warnings-GR
            - warnings-BA
            - warnings-NL
            - warnings-CH
            - warnings-MD
            - warnings-BG
            - warnings-IE
            - warnings-SK
            - warnings-HR
            - warnings-CZ
            - warnings-ES
            - warnings-UK
            - warnings-NO
            - warnings-CY
            - warnings-RS
            - warnings-FI
            - warnings-MK
            - warnings-PT
            - warnings-LU
            - warnings-UA
            - warnings-HU
            - warnings-DK
            - warnings-IL
            - warnings-LV
            - warnings-DE
            - warnings-IS
            - warnings-BE
            - warnings-ME
            - warnings-AT

  /collections/warnings/locations:
    get:
      summary: Retrieve available locations within the warnings collection
      operationId: getLocations
      security:
        - bearerAuth: []
        - tokenQuery: []
      parameters:
        - $ref: '#/components/parameters/collectionId'
      responses:
        '200':
          description: available locations within the collection
          content:
            application/geo+json:
              schema:
                $ref: '#/components/schemas/featureCollectionGeoJSONForLocations'
            text/html:
              schema:
                type: string
        '401':
          description: Unauthorized - Invalid or missing authentication token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
  /collections/warnings/locations/{locationId}:
    get:
      summary: Query warning data of collection for location
      operationId: queryLocation
      security:
        - bearerAuth: []
        - tokenQuery: []
      parameters:
        - $ref: '#/components/parameters/collectionId'
        - $ref: '#/components/parameters/locationId'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/datetime'
        - $ref: '#/components/parameters/active'
        - $ref: '#/components/parameters/language'
        - $ref: '#/components/parameters/awareness_type'
        - $ref: '#/components/parameters/awareness_level'
      responses:
        '200':
          description: A feature
          content:
            application/geo+json:
              schema:
                $ref: '#/components/schemas/featureGeoJSON'
        '401':
          description: Unauthorized - Invalid or missing authentication token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
        default:
          description: An error occured.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
            text/html:
              schema:
                type: string
components:
  schemas:
    exception:
      required:
        - code
      type: object
      properties:
        code:
          type: string
        description:
          type: string
    root:
      required:
        - links
      type: object
      properties:
        links:
          type: array
          example:
            - href: /edr/v1
              rel: self
              type: application/json
              title: Landing Page
            - href: /edr/v1/api
              rel: service-desc
              type: application/json
              title: API definition
            - href: https://api.meteoalarm.org/conformance
              rel: conformance
              type: application/json
              title: OGC conformance classes implemented by this API
            - href: https://api.meteoalarm.org/ogc-api/collections
              rel: data
              type: application/json
              title: Metadata about the resource collections
          items:
            $ref: '#/components/schemas/linkurl'
    documentation:
      required:
        - description
        - title
        - url
      type: object
      properties:
        description:
          type: string
        title:
          type: string
        url:
          type: string
    req-classes:
      required:
        - conformsTo
      type: object
      properties:
        conformsTo:
          type: array
          example:
            - http://www.opengis.net/spec/ogcapi-edr-1/1.0/conf/core
            - http://www.opengis.net/spec/ogcapi-common-1/1.0/conf/core
            - http://www.opengis.net/spec/ogcapi-common-2/1.0/conf/collections
            - http://www.opengis.net/spec/ogcapi-edr-1/1.0/conf/html
            - http://www.opengis.net/spec/ogcapi-edr-1/1.0/conf/geojson
          items:
            type: string
    linkurl:
      required:
        - href
      type: object
      properties:
        href:
          type: string
        rel:
          type: string
          example: prev
        type:
          type: string
          example: application/geo+json
        hreflang:
          type: string
          example: en
    collections:
      required:
        - collections
        - links
      type: object
      properties:
        links:
          type: array
          example:
            - href: /edr/v1/collections
              rel: self
              type: application/json
              title: List of collections
          items:
            $ref: '#/components/schemas/linkurl'
        collections:
          type: array
          items:
            $ref: '#/components/schemas/collection'
    collection:
      required:
        - links
      type: object
      properties:
        id:
          type: string
          description: the id of the collection
          example: warnings
        title:
          type: string
          description: Title of the collection
          example: Warning Collection
        description:
          type: string
          description: Description of the collection
          example: Access to realtime and archived warnings issued by the MeteoAlarm Members
        links:
          type: array
          example:
            - href: /edr/v1/collections/warnings
              rel: self
              type: application/json
              title: Warnings Collection
            - href: /edr/v1/collections/warnings/locations
              rel: data
              type: application/geo+json
              title: Locations for Warnings Collection
        extent:
          $ref: '#/components/schemas/extent'
        output_formats:
          type: array
          description: supported output formats
          example:
            - GeoJSON
        default_output_format: 
          type: string
          description: the default output format
          example: GeoJSON
        crs:
          type: array
          description: The coordinate reference systems in which geometries may be retrieved. This is always "http://www.opengis.net/def/crs/OGC/1.3/CRS84", i.e.WGS84 longitude/latitude.
          items:
            type: string
          default:
            - http://www.opengis.net/def/crs/OGC/1.3/CRS84
        mqtt:
          $ref: '#/components/schemas/mqtt'
    mqtt:
      type: object
      properties:
        broker_url:
          type: string
          description: the url of the MQTT broker
          example: mqtt://api.meteoalarm.org
        description:
          type: string
          description: the description of the MQTT broker
        topics:
          type: array
          description: available topics
          example:
            - realtime/HU
            - realtime/ALL
    extent:
      type: object
      properties:
        crs:
          type: string
          description: Coordinate reference system of the coordinates in the spatial extent.  Only WGS84 longitude / latitude is supported.
          enum:
            - http://www.opengis.net/def/crs/OGC/1.3/CRS84
          default: http://www.opengis.net/def/crs/OGC/1.3/CRS84
        spatial:
          type: array
          description: West, north, east, south edges of the spatial extent. Only WGS84 longitude / latitude is supported.
          example:
            - -180
            - -90
            - 180
            - 90
          items:
            type: number
        trs:
          type: string
          description: Temporal reference system of the coordinates in the temporal extent (property `temporal`). Only the Gregorian calendar is supported. 
          enum:
            - http://www.opengis.net/def/uom/ISO-8601/0/Gregorian
          default: http://www.opengis.net/def/uom/ISO-8601/0/Gregorian
        temporal:
          type: array
          description: Begin and end times of the temporal extent.
          example:
            - '2023-11-11T12:22:11Z'
            - '2023-11-24T12:32:43Z'
          items:
            type: string
    featureCollectionGeoJSONForLocations:
      required:
        - features
        - type
      type: object
      properties:
        type:
          type: string
          enum:
            - FeatureCollection
        features:
          type: array
          items:
            $ref: '#/components/schemas/locationFeatureGeoJSON'
      example:
        type: "FeatureCollection"
        features:
          - geometry:
              coordinates:
                - - - -25
                    - 35
                  - - 45
                    - 35
                  - - 45
                    - 75
                  - - -25
                    - 75
                  - - -25
                    - 35
              type: "Polygon"
            id: "ALL"
            properties:
              title: "All of Europe"
            type: "Feature"
    featureCollectionGeoJSON:
      required:
        - features
        - type
      type: object
      properties:
        type:
          type: string
          enum:
            - FeatureCollection
        features:
          type: array
          items:
            $ref: '#/components/schemas/featureGeoJSON'
        links:
          type: array
          items:
            $ref: '#/components/schemas/linkurl'
        timeStamp:
          type: string
        numberMatched:
          type: integer
        numberReturned:
          type: integer
          
    locationFeatureGeoJSON:
      required:
        - geometry
        - properties
        - type
        - id
      type: object
      properties:
        id: 
          type: string 
          description: Location identifier (country code or 'ALL' for all of Europe)
          example: "ALL"
        type:
          type: string
          enum:
            - Feature
        geometry:
          $ref: '#/components/schemas/geometryGeoJSON'
        properties:
          type: object
          required:
            - title
          properties:
            title: 
              type: string 
              description: Human-readable name of the location
              example: "All of Europe"
      example:
        id: "ALL"
        type: "Feature"
        geometry:
          type: "Polygon"
          coordinates:
            - - - -25
                - 35
              - - 45
                - 35
              - - 45
                - 75
              - - -25
                - 75
              - - -25
                - 35
        properties:
          title: "All of Europe"
    featureGeoJSON:
      required:
        - geometry
        - properties
        - type
      type: object
      properties:
        type:
          type: string
          enum:
            - Feature
        geometry:
          $ref: '#/components/schemas/geometryGeoJSON'
        links: 
          $ref: '#/components/schemas/geometryLinks'
        properties:
          type: object
          properties:
            geometryTyoe: 
              type: string
              enum: 
                - exact
                - bbox
              example: bbox
            geometryDescription:
              type: string 
              example: "geometry is bbox only, geometryUrl points to geojson describing the exact shape"
            OBJECTID:
              type: string
              example: 81da3377-4c35-4479-ab26-4fe5418ca464
            alertId:
              type: string
              example: 830b871b-da1d-49a7-9d75-c8f7276de440
            countryCode:
              type: string
              example: AT
            featureType:
              type: string
              enum:
                - geocode
                - polygon
              example: geocode
            hubLink: 
              type: string 
              example: https://storage.meteoalarm.org/api/warnings/aee7f756-c1f6-49d3-8691-96038b6d4e3a.xml?AWSAccessKeyId=DO00LYPLJBWUUWC6D6NU&Expires=1746626459&Signature=n1QpmM3KvemLgXW6zloUI6mn5mM%3D
            hubLanguage:
              type: string
              example: de-DE
            indexArea:
              type: integer
              example: 0
            indexFeature:
              type: integer
              example: 0
            indexInfo:
              type: integer
              example: 0
        id:
          type: string
    geometryLinks: 
      type: array
      example:
        - href: https://storage.meteoalarm.org/api/warnings/aee7f756-c1f6-49d3-8691-96038b6d4e3a.json?AWSAccessKeyId=DO00LYPLJBWUUWC6D6NU&Expires=1746626459&Signature=n1QpmM3KvemLgXW6zloUI6mn5mM%3D
          rel: json
          type: application/json
        - href: https://storage.meteoalarm.org/api/warnings/aee7f756-c1f6-49d3-8691-96038b6d4e3a.xml?AWSAccessKeyId=DO00LYPLJBWUUWC6D6NU&Expires=1746626459&Signature=n1QpmM3KvemLgXW6zloUI6mn5mM%3D
          rel: xml
          type: application/xml
        - href: https://storage.meteoalarm.org/api/warnings/cee7f756-c1f6-49d3-8691-96038b6d4e3a.geojson?AWSAccessKeyId=DO00LYPLJBWUUWC6D6NU&Expires=1746626459&Signature=n1QpmM3KvemLgXW6zloUI6mn5mM%3D
          rel: canonical
          type: application/geo+json
    geometryGeoJSON:
      required:
        - type
      type: object
      properties:
        type:
          type: string
          enum:
            - Polygon
            - MultiPolygon
    timeStamp:
      type: string
      description: This property indicates the time and date when the response was generated.
  parameters:
    collectionId:
      name: collectionId
      in: path
      description: id of the collection
      required: true
      schema:
        type: string
        enum:
          - warnings
    locationId:
      name: locationId
      in: path
      description: id of the location
      required: true
      schema:
        type: string
        enum:
          - ALL
          - SE
          - SI
          - RO
          - MK
          - PL
          - FR
          - EE
          - GR
          - LU
          - LT
          - IT
          - DE
          - ES
          - BA
          - NL
          - CH
          - FI
          - PT
          - RS
          - MD
          - SK
          - HR
          - BG
          - IE
          - CZ
          - LV
          - IS
          - HU
          - UK
          - BE
          - DK
          - ME
          - AT
          - MT
          - CY
          - IL
          - UA
    page:
      name: page
      in: query
      description: specifies page number of result to be retrieved
      required: false
      schema:
        type: integer
    datetime:
      name: datetime
      in: query
      description: Filter, warning sent within this time interval. ISO8601 interval format using '/' separator (e.g., '2025-04-16T16:25:04+02:00/2025-04-17T16:25:04+02:00'). Both start and end dates are required.
      example: "2025-04-16T16:25:04+02:00/2025-04-17T16:25:04+02:00"
      required: true
      explode: false
      schema:
        type: string
    active:
      name: active
      in: query
      description: Filter, warning active within this time interval. ISO8601 interval format using '/' separator (e.g., '2025-04-16T16:25:04+02:00/2025-04-17T16:25:04+02:00'). Start or end may be omitted for open-ended intervals.
      example: "2025-04-16T16:25:04+02:00/2025-04-17T16:25:04+02:00"
      required: false
      explode: false
      schema:
        type: string
    language:
      name: language
      in: query
      description: Filter, language of the info block. The format is a locale, 2-digit ISO 639-1 language code followed by a dash (-), followed by an ISO 3166-1 country code
      example: en-GB
      required: false
      explode: false
      schema:
        type: string
    awareness_type:
      name: awareness_type
      in: query
      description: Filter, warning having this awareness_type. One awareness_type, or several awareness_type values separated by a pipe symbol (|).
      example: 14; Marine-Hazard
      required: false
      explode: false
      schema:
        type: string
    awareness_level:
      name: awareness_level
      in: query
      description: Filter, warning having this awareness_level. One awareness_level, or several awareness_level values separated by a pipe symbol (|).
      example: 2; yellow; Moderate
      required: false
      explode: false
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: "Use Bearer token in Authorization header: 'Authorization: Bearer <token>'"
    tokenQuery:
      type: apiKey
      in: query
      name: token
      description: "Use token as query parameter: '?token=<token>'"
  