openapi: 3.0.0
info:
  title: WeatherXM Pro API
  description: WeatherXM Pro API
  version: 0.0.1

servers:
  - url: https://playground.weatherxm.com/b2b
    description: Development
  - url: http://localhost:3004
    description: Local

paths:
  /stations/radius:
    get:
      summary: Get a list of stations within a radius from a location
      description: Provide a lat, lon as the central location and a radius (in km) to get a list of stations within that radius
      parameters:
        - name: lat
          in: query
          required: true
          description: Latitude of the center of the area
          schema:
            type: number
          example: 48.684298
        - name: lon
          in: query
          required: true
          description: Longitude of the center of the area
          schema:
            type: number
          example: 12.098126
        - name: radius
          in: query
          required: true
          description: Radius (in km) for which stations are queried
          schema:
            type: number
          example: 50
        - name: x-wxm-api-key
          in: header
          description: WXM API key
          schema:
            type: string
      responses:
        '200':
          description: A list of stations
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    name:
                      type: string
                    lastDayQod:
                      type: string
                    lat:
                      type: number
                    lon:
                      type: number
                    cellId:
                      type: string
        '400':
          description: Invalid query parameters
        '401':
          description: No API key provided or invalid API key
        '429':
          description: Api call request limit exceeded

  /stations/bbox:
    get:
      summary: Get a list of stations within a bounding box
      description: Provide bounding box coordinates (minLat, minLon, maxLat, maxLon) to get a list of stations
      parameters:
        - name: minLat
          in: query
          required: true
          schema:
            type: number
        - name: minLon
          in: query
          required: true
          schema:
            type: number
        - name: maxLat
          in: query
          required: true
          schema:
            type: number
        - name: maxLon
          in: query
          required: true
          schema:
            type: number
        - name: x-wxm-api-key
          in: header
          description: WXM API key
          schema:
            type: string
      responses:
        '200':
          description: A list of stations in the bounding box
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    name:
                      type: string
                    lastDayQod:
                      type: string
                    lat:
                      type: number
                    lon:
                      type: number
                    cellId:
                      type: string
        '400':
          description: Invalid query parameters
        '401':
          description: No API key provided or invalid API key
        '429':
          description: Api call request limit exceeded

  /stations:
    get:
      summary: Get a complete list of stations
      description: Retrieve all available stations
      parameters:
        - name: x-wxm-api-key
          in: header
          description: WXM API key
          schema:
            type: string
      responses:
        '200':
          description: A complete list of stations
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    name:
                      type: string
                    lastDayQod:
                      type: string
                    lat:
                      type: number
                    lon:
                      type: number
                    cellId:
                      type: string
        '401':
          description: No API key provided or invalid API key
        '429':
          description: Api call request limit exceeded

  /stations/{stationId}:
    get:
      summary: Fetch weather history data for a specific station
      description: Retrieves historical weather data for a specific station within a given time range.
      parameters:
        - name: stationId
          in: path
          required: true
          schema:
            type: string
        - name: start_datetime
          in: query
          required: true
          schema:
            type: string
            format: date-time
        - name: end_datetime
          in: query
          required: true
          schema:
            type: string
            format: date-time
        - name: content_type
          in: header
          schema:
            type: string
            default: application/json
        - name: x-wxm-api-key
          in: header
          description: WXM API key
          schema:
            type: string
      responses:
        '200':
          description: Data retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    gps_lat:
                      type: string
                    gps_lon:
                      type: string
                    gps_alt:
                      type: string
                    gps_sats:
                      type: string
                    temperature:
                      type: string
                    humidity:
                      type: string
                    precipitation_accumulated:
                      type: string
                    wind_speed:
                      type: string
                    wind_gust:
                      type: string
                    wind_direction:
                      type: string
                    illuminance:
                      type: string
                    solar_irradiance:
                      type: string
                    fo_uv:
                      type: string
                    uv_index:
                      type: string
                    precipitation_rate:
                      type: string
                    pressure:
                      type: string
                    ts:
                      type: string
                    qod_score:
                      type: string
                    qod_version:
                      type: string
                    daily_score:
                      type: string
                    pol_score:
                      type: string
                    daily_annotation:
                      type: string
                    validation_score_qod_pol:
                      type: string
                    qod_daily_annotation:
                      type: string
                    qod_hourly_score:
                      type: string
                    pol_reason:
                      type: string
                    pol_cell:
                      type: string
                    pol_annotation:
                      type: string
                    pol_resolved_cell:
                      type: string
                    pol_version:
                      type: string
        '404':
          description: Station not found
        '401':
          description: No API key provided or invalid API key
        '429':
          description: Api call request limit exceeded

  /cells/search:
    get:
      summary: Search for cells by region name
      description: Returns a list of cells based on a string search for a specific region name.
      parameters:
        - name: query
          in: query
          required: true
          description: The name of the region to search for cells
          schema:
            type: string
          example: 'Europe'
        - name: x-wxm-api-key
          in: header
          description: WXM API key
          schema:
            type: string
      responses:
        '200':
          description: A list of cells matching the region search
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cellIndex:
                      type: string
                      example: 'cell12345'
        '401':
          description: No API key provided or invalid API key
        '429':
          description: Api call request limit exceeded

  /history/sync/{device_id}:
    get:
      summary: Fetch device history synchronously.
      description: Retrieves historical weather data for a specific device within a given time range.
      parameters:
        - name: device_id
          in: path
          required: true
          schema:
            type: string
        - name: start_datetime
          in: query
          required: true
          schema:
            type: string
            format: date-time
        - name: end_datetime
          in: query
          required: true
          schema:
            type: string
            format: date-time
        - name: x-wxm-api-key
          in: header
          description: WXM API key
          schema:
            type: string
      responses:
        200:
          description: Data retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                example:
                  [
                    {
                      'timestamp': 1658448016000,
                      'gps_lat': 51.8968277,
                      'gps_lon': -114.1117783,
                      'gps_alt': 1107.900024,
                      'metadata_latitude': 51.89688,
                      'metadata_longitude': -114.11175,
                      'metadata_altitude': 1100.0,
                      'temperature': 28.5,
                      'humidity': 34.0,
                      'pressure': 884.9768677,
                      'precipitation_accumulated': 12.95400047,
                      'wind_speed': 0.837200046,
                      'wind_gust': 1.529999971,
                      'wind_direction': 43.0,
                      'illuminance': 420330.0,
                      'solar_irradiance': 0.0,
                      'name': 'Test Bisque Nowcast',
                      'owner': 'test@yahoo.ca',
                      'utc_datetime': '2022-07-22 00:00:16',
                      'device_id': 'test0780-d8f6-11ec-960f-d7d4cf200cc9',
                    },
                  ]
            text/csv:
              schema:
                type: string
                format: binary
            application/octet-stream:
              schema:
                type: string
                format: binary
              example: 'Serialized Parquet data in binary format'
        '404':
          description: Device not found
        '401':
          description: No API key provided or invalid API key
        '429':
          description: Api call request limit exceeded