openapi: 3.1.0
info:
  title: WeatherXM Pro API Documentation
  description: >
    ## Introduction
      
      Welcome to the WeatherXM Pro API documentation. This API is part of WeatherXM Pro, a robust platform designed to provide enhanced tools for exploring weather station observations, hyperlocal forecasts, and historical weather data. The API is a critical component, enabling developers to seamlessly integrate WeatherXM's high-quality data into their applications.
      
      This documentation page provides comprehensive details, use cases, and examples to help you make the most of the WeatherXM Pro API.

    ---

    ## What You Can Do with the API


    The WeatherXM Pro API enables you to:

      - Retrieve weather stations in specific areas using bounding boxes or proximity searches.
      - Access historical observation data for specific weather stations.
      - Fetch forecasts, both hourly and daily, for specific geospatial areas (H3 cells).
      - Monitor station metadata, including location, health, and data quality scores.
      
      The API's versatility makes it suitable for applications in agriculture, logistics, energy, and more.

    ---

    OpenApi specifications for AI agents: https://pro.weatherxm.com/api/spec

    ---

    ## Example Use Case: Get the Latest Weather Data from a Station in a
    Specific Area


    This example demonstrates how to:
      
      1. Retrieve a list of weather stations within a bounding box.
      2. Fetch the latest observation data from one of the retrieved stations.
      
      For this example, we will use a bounding box around Central Park, NY.

    ### Step 1: Get a List of Stations Within a Bounding Box
      
      **Endpoint:** `GET /stations/bounds`
      
      This step retrieves weather stations within a bounding box defined by latitude and longitude.
      
      #### Request Example
      ```bash
      curl -X GET "https://pro.weatherxm.com/api/stations/bounds?min_lat=40.76&min_lon=-73.98&max_lat=40.79&max_lon=-73.94" \
    -H "X-API-KEY: YOUR_API_KEY"
      ```

    #### Query Parameters

    - `min_lat`: Minimum latitude of the bounding box.

    - `min_lon`: Minimum longitude of the bounding box.

    - `max_lat`: Maximum latitude of the bounding box.

    - `max_lon`: Maximum longitude of the bounding box.


    #### Example Response
      ```json
      {
        "stations": [
          {
            "id": "3355b780-438d-11ef-8e8d-b55568dc8e66",
            "name": "Scrawny Magnolia Sunset",
            "lastDayQod": 0.9990059523809524,
            "cellId": "872a10089ffffff",
            "createdAt": "2024-09-06T00:01:49.685Z",
            "location": {
              "lat": 40.77334213256836,
              "lon": -73.94979095458984
            }
          },
          {
            "id": "efae5a90-8db9-11ec-900c-abdec1c57354",
            "name": "Odd Foggy Noreaster",
            "lastDayQod": 0,
            "cellId": "872a10089ffffff",
            "createdAt": "2022-03-21T09:04:35.157Z",
            "location": {
              "lat": 40.782613,
              "lon": -73.96528
            }
          }
        ]
      }
      ```
      
      ### Step 2: Fetch the Latest Observation Data for a Station
      
      Using the first station from the previous response (`3355b780-438d-11ef-8e8d-b55568dc8e66`), this step retrieves the latest observation data for that station.
      
      **Endpoint:** `GET /stations/{station_id}/latest`
      
      #### Request Example
      ```bash
      curl -X GET "https://pro.weatherxm.com/api/stations/3355b780-438d-11ef-8e8d-b55568dc8e66/latest" \
    -H "X-API-KEY: YOUR_API_KEY"
      ```

    #### Path Parameters

    - `station_id`: The unique identifier of the station.


    #### Example Response
      ```json
      {
        "observation": {
          "timestamp": "2025-01-17T15:42:20.248Z",
          "temperature": 1.4,
          "feels_like": 1.4,
          "dew_point": -1.1717342238520458,
          "humidity": 83,
          "precipitation_rate": 0,
          "wind_speed": 0,
          "wind_gust": 0,
          "wind_direction": 180,
          "uv_index": 0,
          "pressure": 975.33,
          "solar_irradiance": 2.6,
          "created_at": "2025-01-17T15:42:20.248Z"
        },
        "health": {
          "timestamp": "2025-01-16T00:00:00.000Z",
          "data_quality": { "score": 0.9527791666666667 },
          "location_quality": { "score": 1, "reason": "-" }
        }
      }
      ```

    ---


    ## Example Use Case: Calculate Precipitation Accumulation


    ### This example demonstrates how to get the total precipitation accumulated
    in time period.


    For the sake of the example we are going to get the daily precipitation
    accumulated for a station in a day


    ```python

    function calculate_precipitation_accumulated():
      response = http_get('https://pro.weatherxm.com/api/v1/stations/4a6df0c0-b7d9-11ef-96c4-2f3b3806a23a/history?date=2025-05-24')
      
      total = 0

      for i from 0 to length(response.data) - 1:
          previous = data[i - 1].precipitation_accumulated
          current = data[i].precipitation_accumulated

          if current >= previous:
              diff = current - previous
          else:
              # Handle counter reset
              diff = current

          total += diff

      return total
    ```


    ---


    ## Authentication
      
      The WeatherXM Pro API uses an API key for authentication. Include your key in the `X-API-KEY` header for every request.
      
      You can find and copy your API key on the [API Management page](https://pro.weatherxm.com/api-management).

    Example:
      ```bash
    -H "X-API-KEY: YOUR_API_KEY"
      ```

    ---


    ## Feedback and Support


    If you have any questions or need assistance, here are two ways to get
    support:
      
      1. **Open a Ticket:** Use our [Support Site](https://support.weatherxm.com) to open a ticket and receive help from our team.
      2. **Send Feedback:** Share your thoughts about the app or API via our [Feedback Form](https://tally.so/r/3jo8zE).
      
      We value your feedback and are here to help you make the most of WeatherXM Pro API. Thank you for choosing WeatherXM!
  version: 1.13.4
servers:
  - url: https://pro.weatherxm.com/api/v1
    description: Production
tags:
  - name: stations
    description: Weather stations
  - name: cells
    description: Hexagonal geospatial areas for grouping stations
  - name: observations
    description: Historical weather observations
  - name: rewards
    description: Weather station rewards and incentives
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: Authentication via your WeatherXM Pro API key
      in: header
      name: X-API-KEY
  responses:
    InvalidRequest:
      description: Invalid query parameters
    UnauthorizedError:
      description: API key is missing or invalid
    ForbiddenError:
      description: Access to resource is not allowed
    TooManyRequests:
      description: Api call request limit exceeded
    BadRequest:
      description: Wrong query or path parameters
    UnknownError:
      description: Unknown error occurred
  schemas:
    Location:
      type: object
      properties:
        lat:
          type: number
          format: float
          description: Latitude
          examples:
            - 37.97168
        lon:
          type: number
          format: float
          description: Longitude
          examples:
            - 23.725697
        elevation:
          type: number
          format: float
          description: Elevation in meters
          examples:
            - 1400
    Cell:
      type: object
      properties:
        index:
          type: string
          description: >-
            Cell index, based on H3 algorithm's index definition. [Read
            more](https://h3geo.org/docs/core-library/h3Indexing).
          examples:
            - 822d57fffffffff
        center:
          $ref: '#/components/schemas/Location'
        station_count:
          type: integer
          description: The number of stations in the cell
    Station:
      type: object
      properties:
        id:
          type: string
          description: The station's unique identifier
          examples:
            - 04f39e90-f3ce-11ec-960f-d7d4cf200cc9
        name:
          type: string
          description: The station's unique name
        cellIndex:
          type: string
          description: >-
            The index of the Cell this station belongs to, based on H3
            algorithm''s index definition. [Read
            more](https://h3geo.org/docs/core-library/h3Indexing).'
          examples:
            - 871eda664ffffff
        location:
          $ref: '#/components/schemas/Location'
        createdAt:
          type: string
          description: The ISO8601 datetime this station has observation data since.
    StationMetadata:
      type: object
      properties:
        id:
          type: string
          description: The station's unique identifier
        name:
          type: string
          description: The station's name
        label:
          type: string
          description: The station's label
        bundle:
          type: string
          description: The station's bundle name (e.g., D1, M5, H1, H2, PULSE)
        claimed:
          type: object
          properties:
            status:
              type: boolean
              description: Whether the station is claimed
            last_at:
              type: string
              description: The timestamp of the last claim status change
        activity:
          type: object
          properties:
            online:
              type: boolean
              description: Whether the station is online
            last_at:
              type: string
              description: The timestamp of the last activity
        location:
          type: object
          description: Weather station's latest GPS coordinates
          properties:
            station_gps:
              type: object
              properties:
                latitude:
                  type: number
                  format: float
                longitude:
                  type: number
                  format: float
            user_set:
              type: object
              description: User set station's location
              properties:
                latitude:
                  type: number
                  format: float
                longitude:
                  type: number
                  format: float
                altitude:
                  type: number
                  format: float
        battery:
          type: object
          properties:
            is_low:
              type: boolean
              description: Whether the battery is low
            last_at:
              type: string
              description: The timestamp of the last battery check
        signal:
          type: object
          properties:
            gateway:
              type:
                - number
                - 'null'
              description: Gateway signal strength (RSSI)
            weather_station:
              type:
                - number
                - 'null'
              description: Weather station signal strength (RSSI)
    Observation:
      type: object
      description: Station weather observation
      properties:
        timestamp:
          description: Timestamp of the observation, in ISO8601 datetime, with time zone
          type: string
          format: date-time
          examples:
            - '2024-03-20T15:30:00+02:00'
        temperature:
          description: Temperature, in degrees Celsius
          type: number
          format: float
          examples:
            - 23.5
        feels_like:
          description: Felt temperature, in degrees Celsius
          type: number
          format: float
          examples:
            - 23.5
        dew_point:
          description: Dew point, in degrees Celsius
          type: number
          format: float
          examples:
            - 12.8
        precipitation_rate:
          description: Precipitation rate, in mm/h
          type: number
          format: float
          examples:
            - 12.8
        precipitation_accumulated:
          description: >-
            This field reports the total accumulated precipitation in
            millimeters (mm) as a continuously increasing counter that resets to
            0 when it reaches its maximum value or on station reboot. To
            calculate daily precipitation, iterate over all the values and
            subtract each previous value from the current one to get the
            difference. if the current value is less than the previous
            (indicating a reset), assume the current value is the difference.
            Sum all differences over the day to get the total precipitation in
            mm.
          type: number
          format: float
          examples:
            - 150.4
        humidity:
          description: Relative humidity, percentage
          type: number
          format: float
          examples:
            - 65.4
        wind_speed:
          description: Wind speed, in m/s
          type: number
          format: float
          examples:
            - 4.2
        wind_gust:
          description: Wind gust, in m/s
          type: number
          format: float
          examples:
            - 8.7
        wind_direction:
          description: Wind direction, in degrees
          type: integer
          examples:
            - 180
        uv_index:
          description: UV index
          type: number
          examples:
            - 6.5
        pressure:
          description: Barometric pressure, in hPa
          type: number
          format: float
          examples:
            - 1013.2
        solar_irradiance:
          description: Solar irradiance, in watts per square metre (W/m²)
          type: number
          format: float
          examples:
            - 850.5
        icon:
          description: Icon name corresponding to current weather conditions
          type: string
          examples:
            - partly-cloudy-day
    Health:
      type: object
      properties:
        timestamp:
          description: >-
            Timestamp when the health metrics were calculated, in ISO8601
            datetime
          type: string
          format: date-time
          examples:
            - '2024-03-20T15:30:00+02:00'
        data_quality:
          type: object
          properties:
            score:
              description: The data quality score (percentage)
              type: number
              format: float
              examples:
                - 0.459
        location_quality:
          type: object
          properties:
            score:
              description: The location quality score (percentage)
              type: number
              format: float
              examples:
                - 0.459
            reason:
              description: |
                The location quality score (percentage) Possible reasons:
                 * `LOCATION_NOT_VERIFIED` - Station's location could not be verified through the station's GPS sensor data
                 * `LOCATION_UNKNOWN` - Station's location is unknown
              type: string
              enum:
                - LOCATION_NOT_VERIFIED
                - LOCATION_UNKNOWN
              x-nullable: true
        photos_quality:
          type: object
          properties:
            score:
              description: The photos quality score (0-1)
              type: number
              format: float
              examples:
                - 0.459
    DailyForecastData:
      type: object
      description: Station weather forecast
      properties:
        temperature_max:
          description: Forecasted max temperature, in degrees Celsius
          type: number
          format: float
          examples:
            - 25.6
        temperature_min:
          description: Forecasted min temperature, in degrees Celsius
          type: number
          format: float
          examples:
            - 15.2
        precipitation_probability:
          description: Forecasted precipitation probability
          type: number
          format: float
          examples:
            - 0.75
        precipitation_intensity:
          description: Forecasted precipitation intensity in mm
          type: number
          format: float
          examples:
            - 2.5
        humidity:
          description: Humidity
          type: number
          format: float
          examples:
            - 65.5
        uv_index:
          description: Forecasted UV index
          type: number
          format: float
          examples:
            - 8.2
        pressure:
          description: Forecasted pressure, in hPa
          type: number
          format: float
          examples:
            - 1013.2
        icon:
          description: Icon representing forecasted weather conditions
          type: string
          examples:
            - partly-cloudy-day
        precipitation_type:
          description: Forecasted precipitation type
          type: string
          examples:
            - rain
        wind_speed:
          description: Forecasted wind speed, in m/s
          type: number
          format: float
          examples:
            - 15.7
        wind_direction:
          description: Forecasted wind direction, in degrees
          type: number
          format: float
          examples:
            - 180
        timestamp:
          description: Timestamp of the forecast, in ISO8601 datetime, with time zone
          type: string
          format: date-time
          examples:
            - '2025-05-28T06:00:00.000Z'
    HourlyForecastData:
      type: object
      description: Hourly forecast data
      properties:
        timestamp:
          description: Timestamp of the forecast, in ISO8601 datetime, with time zone
          type: string
          format: date-time
          examples:
            - '2025-05-28T06:00:00.000Z'
        precipitation:
          description: Forecasted precipitation
          type: number
          format: float
          examples:
            - 2.5
        precipitation_probability:
          description: Forecasted precipitation probability
          type: number
          format: float
          examples:
            - 80.5
        temperature:
          description: Forecasted temperature, in degrees Celsius
          type: number
          format: float
          examples:
            - 25.7
        icon:
          description: Icon representing forecasted weather conditions
          type: string
          examples:
            - partly-cloudy-day
        wind_speed:
          description: Forecasted wind speed, in m/s
          type: number
          format: float
          examples:
            - 15.7
        wind_direction:
          description: Forecasted wind direction, in degrees
          type: number
          format: float
          examples:
            - 180
        humidity:
          description: Humidity
          type: number
          format: float
          examples:
            - 65.5
        pressure:
          description: Forecasted pressure, hPa
          type: number
          format: float
          examples:
            - 1013.2
        uv_index:
          description: Forecasted UV index
          type: number
          format: float
          examples:
            - 8.2
        feels_like:
          description: Forecasted feels like temperature, in degrees Celsius
          type: number
          format: float
          examples:
            - 27.3
    HyperlocalHourlyForecastData:
      type: object
      description: Hourly forecast data
      required:
        - timestamp
      properties:
        timestamp:
          description: Timestamp of the forecast, in ISO8601 datetime, with time zone
          type: string
          format: date-time
          examples:
            - '2024-01-17T15:00:00.000Z'
        variable:
          description: The weather variable requested
          type: string
          examples:
            - temperature
        value:
          description: The forecast value
          type: number
          format: float
          examples:
            - 25.7
    Forecast:
      type: object
      description: Station weather observation
      required:
        - tz
        - date
      properties:
        tz:
          description: Timezone
          type: string
          examples:
            - Europe/Athens
        date:
          description: Date for this forecast object
          type: string
          examples:
            - '2024-01-17'
        hourly:
          type: array
          items:
            $ref: '#/components/schemas/HourlyForecastData'
        daily:
          $ref: '#/components/schemas/DailyForecastData'
    HyperlocalForecast:
      type: object
      description: Hyperlocal forecast
      required:
        - tz
        - date
      properties:
        tz:
          description: Timezone
          type: string
          examples:
            - Europe/Athens
        date:
          description: Date for this forecast object
          type: string
          examples:
            - '2024-01-17'
        hourly:
          type: array
          items:
            $ref: '#/components/schemas/HyperlocalHourlyForecastData'
    ForecastModelWithRank:
      type: object
      description: Forecast model with rank for a weather variable
      properties:
        name:
          description: The name of the forecast model
          type: string
          examples:
            - GFS
        rank:
          description: >-
            The rank of the forecast emodel compared with other forecast models
            in the dataset
          type: number
          examples:
            - 1
        avgErrorDistance:
          description: The average error for the forecasts from this model
          type: number
          examples:
            - 2.3
        errorDistance:
          description: >-
            Detailed errors for the forecasts from this model for the analyzed
            period
          type: array
          items:
            type: number
          examples:
            - - 2.1
              - 1.8
              - 2.4
              - 3.2
              - 2.7
              - 1.9
              - 2.5
              - 2.8
    ModelWithRank:
      type: object
      description: Forecast model with rank for a weather variable
      properties:
        errorMetric:
          description: The error metric used to calculate average error
          type: string
          examples:
            - RMSE
        models:
          type: array
          items:
            $ref: '#/components/schemas/ForecastModelWithRank'
    FactModel:
      type: object
      description: Weather forecast model with error value
      properties:
        name:
          description: Weather forecast model name
          type: string
        errorDistance:
          description: Weather forecast model error
          type: number
    FactVariableRanking:
      type: object
      description: >-
        Model ranking for weather forecast models per day ahead for a specific
        variable
      properties:
        daysAhead:
          description: Days ahead from the forecast evaluation date
          type: number
        model:
          description: The best model for the "daysAhead"
          $ref: '#/components/schemas/FactModel'
    ModelRanking:
      type: object
      description: Model ranking per weather variable for a station
      properties:
        temperature:
          description: Model ranking for the temperature weather variable
          type: array
          items:
            $ref: '#/components/schemas/FactVariableRanking'
        humidity:
          description: Model ranking for the humidity weather variable
          type: array
          items:
            $ref: '#/components/schemas/FactVariableRanking'
        precipitation:
          description: Model ranking for the precipitation weather variable
          type: array
          items:
            $ref: '#/components/schemas/FactVariableRanking'
        windSpeed:
          description: Model ranking for the windSpeed weather variable
          type: array
          items:
            $ref: '#/components/schemas/FactVariableRanking'
        windDirection:
          description: Model ranking for the windDirection weather variable
          type: array
          items:
            $ref: '#/components/schemas/FactVariableRanking'
    TodayData:
      type: object
      description: >
        Signed S3 URL to csv files containing data for all active stations in a
        specified 5 minute window and its corresponding datetime. Also give a
        Signed S3 URL to a QOD (Quality of Data) file for each date.

        ### CSV Format for station files:

        ```

        id,timestamp,temperature,humidity,precipitation_rate,precipitation_accumulated,wind_speed,wind_gust,wind_direction,pressure,solar_irradiance,uv_index,illuminance

        ```

        ### Fields Description:

          - `id`: The station's unique identifier
          - `timestamp`: Date time at the end of the 5 minute window, in ISO8601 UTC datetime
          - `temperature`: Average temperature, in degrees Celsius, over the 5 minute window
          - `humidity`: Average relative humidity, percentage, over the 5 minute window
          - `precipitation_rate`: Precipitation rate, in mm, maximum over the 5 minute window
          - `precipitation_accumulated`: Total accumulated precipitation in millimeters (mm) from the start of the current date
          - `wind_speed`: Average wind speed, in m/s, over the 5 minute window
          - `wind_gust`: Maximum wind gust, in m/s, over the 5 minute window
          - `wind_direction`: Vector average wind direction, in degrees, over the 5 minute window
          - `pressure`: Average barometric pressure, in hPa, over the 5 minute window
          - `solar_irradiance`: Average solar irradiance, in watts per square metre (W/m²), over the 5 minute window
          - `uv_index`: Average of UV index, over the 5 minute window
          - `illuminance`: Average illuminance, in lux, over the 5 minute window

        ### CSV Format for QOD files:

        ``` id, date, qod_score ``` ### Fields Description:

          - `id`: The station's unique identifier
          - `date`: Date for the QOD score, in ISO8601 date
          - `qod_score`: The Quality of Data score (0-1, 1 being the best) for the station for that date
          
      properties:
        files:
          type: array
          description: Array of CSV file objects for each 5-minute window.
          items:
            type: object
            properties:
              datetime:
                type: string
                description: ISO8601 datetime string for the file
                example: '2025-09-30T00:10:00.000Z'
              url:
                type: string
                description: Signed S3 URL for the file.
                example: https://s3.amazonaws.com/csv/2025-09-30/00%3A10-00%3A15.csv
              lastModified:
                type: string
                description: The ISO8601 datetime the file was last modified.
                example: '2025-09-30T12:38:00.000Z'
        qod:
          type: array
          description: Array of QOD file objects for each date.
          items:
            type: object
            properties:
              datetime:
                type: string
                description: ISO8601 date string for the QOD file
                example: '2025-09-30'
              url:
                type: string
                description: Signed S3 URL for the QOD file.
                example: https://s3.amazonaws.com/csv/2025-09-30/qod.csv
    Reward:
      type: object
      properties:
        total_rewards:
          type: number
          description: Total rewards earned
        total_business_rewards:
          type: number
          description: Total business rewards earned
    RewardDetails:
      type: object
      properties:
        date:
          type: string
          format: date
          description: Date of the reward
        amount:
          type: number
          description: Amount of the reward
    TokenSummary:
      type: object
      properties:
        date:
          type: string
          format: date
          description: Date of the summary
        total:
          type: number
          description: Total tokens earned
paths:
  /stations/near:
    get:
      operationId: get-stations-in-radius
      summary: Get a list of stations within a radius from a location
      description: >-
        Provide the center (location latitude and longitude) and a radius (in
        meters) to get a list of stations within that radius
      tags:
        - stations
      security:
        - ApiKeyAuth: []
      parameters:
        - name: lat
          in: query
          required: true
          description: Latitude of the center of the area
          schema:
            type: number
        - name: lon
          in: query
          required: true
          description: Longitude of the center of the area
          schema:
            type: number
        - name: radius
          in: query
          required: true
          description: Radius (in meters) for which stations are queried
          schema:
            type: number
      responses:
        '200':
          description: A list of stations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Station'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /stations/bounds:
    get:
      operationId: get-stations-in-bounds
      summary: Get a list of stations within a bounding box
      description: Provide bounding box coordinates to get a list of stations
      tags:
        - stations
      security:
        - ApiKeyAuth: []
      parameters:
        - name: min_lat
          in: query
          required: true
          description: The minimum latitude of the bounding box
          schema:
            type: number
        - name: min_lon
          in: query
          required: true
          description: The minimum longitude of the bounding box
          schema:
            type: number
        - name: max_lat
          in: query
          required: true
          description: The maximum latitude of the bounding box
          schema:
            type: number
        - name: max_lon
          in: query
          required: true
          description: The maximum longitude of the bounding box
          schema:
            type: number
      responses:
        '200':
          description: A list of stations in the bounding box
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Station'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /stations:
    get:
      operationId: get-stations
      summary: Get a complete list of stations
      description: Retrieve all available stations
      tags:
        - stations
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: A complete list of stations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Station'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /cells/search:
    get:
      operationId: search-by-name
      summary: Search for cells by city or region name.
      description: >-
        Returns a list of cells based on a string search for a specific area,
        region or city e.g. "London", "Ney York", "Athens", "Crete".
      tags:
        - cells
      security:
        - ApiKeyAuth: []
      parameters:
        - name: query
          in: query
          required: true
          description: The name of the region to search for cells
          schema:
            type: string
      responses:
        '200':
          description: A list of cells matching the region search
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Cell'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /cells/{cell_index}/forecast/wxmv1:
    get:
      operationId: get-wxmv1-forecast
      summary: Get 7 day WXMv1 forecast for a cell
      description: Returns WXMv1 weather forecast up to a week ahead for a cell
      tags:
        - forecast
      security:
        - ApiKeyAuth: []
      parameters:
        - name: from
          description: The first day for which to get forecast data. Defaults to now
          in: query
          required: true
          schema:
            type: string
            format: date
            examples:
              - '2024-10-29'
        - name: to
          description: >-
            The last day for which to get forecast data. Defaults to 7 days from
            now
          in: query
          required: true
          schema:
            type: string
            format: date
            examples:
              - '2024-10-29'
        - name: cell_index
          in: path
          required: true
          description: The H3 index with resolution of the cell to return forecast for
          schema:
            type: string
        - name: include
          in: query
          required: true
          description: >-
            The types of forecast to include. Accepted values are daily and
            hourly
          schema:
            type: string
      responses:
        '200':
          description: Forecast for the requested cell
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Forecast'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /cells/{cell_index}/stations:
    get:
      operationId: get-stations-in-cell
      summary: Get all stations in a H3 cell
      description: Returns a list of stations that are deployed within the cell.
      tags:
        - cells
      security:
        - ApiKeyAuth: []
      parameters:
        - name: cell_index
          in: path
          required: true
          description: The H3 index of the cell to return stations for
          schema:
            type: string
      responses:
        '200':
          description: A list of cells matching the region search
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Station'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /cells/{cell_index}/mm/models:
    get:
      operationId: get-multimodel-cell-forecast-models
      summary: Get available models for a cell forecast
      description: Returns a list of all available forecast models for a specific cell
      tags:
        - forecast
      security:
        - ApiKeyAuth: []
      parameters:
        - name: cell_index
          in: path
          required: true
          description: The H3 index of the cell to retrieve forecast models for
          schema:
            type: string
            examples:
              - 8712ccc0cffffff
      responses:
        '200':
          description: List of available forecast models for the requested cell
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          description: Server error
  /cells/{cell_index}/mm/forecast:
    get:
      operationId: get-multimodel-forecast-for-cell
      summary: Get multi-model forecast for a cell
      description: Returns 7 day weather forecast from multiple models for a specific cell
      tags:
        - forecast
      security:
        - ApiKeyAuth: []
      parameters:
        - name: cell_index
          in: path
          required: true
          description: The H3 index of the cell to return multi-model forecast for
          schema:
            type: string
            examples:
              - 8712ccc0cffffff
        - name: startTs
          in: query
          description: >-
            Start date for forecast data (must not be in the past). Defaults to
            current date.
          schema:
            type: string
            format: date-time
            examples:
              - '2025-05-04'
              - 2025-05-04T10:00
        - name: endTs
          in: query
          description: >-
            End date for forecast data (must not be in the past and must be
            after startTs). Defaults to 7 days from current date.
          schema:
            type: string
            format: date-time
            examples:
              - 2025-05-012
              - 2025-05-012T10:00
        - name: timezone
          in: query
          description: >-
            Timezone to use for the forecast data. If not provided, timezone
            will be determined from cell location.
          schema:
            type: string
            examples:
              - UTC
              - Europe/Athens
        - name: models
          in: query
          description: Specific forecast models to include in the response
          schema:
            type: array
            items:
              type: string
            examples:
              - ICON
              - UMGLOBAL10
          style: form
          explode: true
      responses:
        '200':
          description: Multi-model forecast for the requested cell
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Forecast'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          description: No data found or invalid model requested
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /stations/{station_id}/latest:
    get:
      operationId: get-latest-observations
      summary: Latest observation
      description: >-
        Retrieves the latest observation for a specific station.

        Note: The "health" field in the response is deprecated and will be moved
        to the  new /stations/{station_id}/health endpoint.
      tags:
        - observations
      security:
        - ApiKeyAuth: []
      parameters:
        - name: station_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  observation:
                    $ref: '#/components/schemas/Observation'
                  health:
                    $ref: '#/components/schemas/Health'
                    deprecated: true
                  location:
                    $ref: '#/components/schemas/Location'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          description: Station not found
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /stations/{station_id}/health:
    get:
      operationId: get-station-health
      summary: Station's health
      description: >-
        Retrieves the health of a specific station, including data quality and
        location quality.
      tags:
        - observations
      security:
        - ApiKeyAuth: []
      parameters:
        - name: station_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  health:
                    $ref: '#/components/schemas/Health'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          description: Station not found
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /stations/{station_id}/metadata:
    get:
      operationId: get-station-metadata
      summary: Get station metadata
      description: Retrieve metadata for a specific station.
      tags:
        - stations
      security:
        - ApiKeyAuth: []
      parameters:
        - name: station_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StationMetadata'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          description: Station not found
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /stations/{station_id}/history:
    get:
      operationId: get-historical-observations
      summary: Historical observations for a specific date or date range
      description: >-
        Retrieves historical observations for a specific station on a specific
        date or date range. Either `date` or `start` and `end` parameters are
        required. The range can not be greater than 7 days.
      tags:
        - observations
      security:
        - ApiKeyAuth: []
      parameters:
        - name: station_id
          in: path
          required: true
          description: The id of the station to get he historical observaions for
          schema:
            type: string
        - name: date
          description: The date (in UTC) to get observation data for.
          in: query
          required: false
          schema:
            type: string
            format: date
            examples:
              - '2024-10-29'
        - name: start
          description: >-
            The start date (in UTC) to get observation data for. Required if
            date is not provided.
          in: query
          required: false
          schema:
            type: string
            format: date
            examples:
              - '2024-10-29'
        - name: end
          description: >-
            The end date (in UTC) to get observation data for. Required if start
            is provided.
          in: query
          required: false
          schema:
            type: string
            format: date
            examples:
              - '2024-10-30'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  date:
                    description: Date, in ISO8601 date format
                    type: string
                    format: date
                  health:
                    $ref: '#/components/schemas/Health'
                  observations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Observation'
                  location:
                    $ref: '#/components/schemas/Location'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          description: Station not found
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /stations/{station_id}/forecast/wxmv2:
    get:
      operationId: get-wxmv2-forecast
      summary: Get 7 day WXMv2 forecast for a station
      description: >-
        Retrieves 7 day WXMv2 forecast for a station for a specific weather
        variable. Weather variables are temperature, humidity, precipitation,
        wind_speed and wind_direction.
      tags:
        - forecast
      security:
        - ApiKeyAuth: []
      parameters:
        - name: station_id
          in: path
          required: true
          description: The station to get the forecast for
          schema:
            type: string
        - name: variable
          in: query
          required: true
          description: >-
            The weather variable to get the forecast for. Accepted values are
            temperature, humidity, precipitation, wind_speed and wind_direction.
          schema:
            type: string
        - name: timezone
          in: query
          required: false
          description: >-
            The timezone to get forecast for. Defaults to station location
            timezone
          schema:
            type: string
        - name: allDay
          in: query
          required: false
          description: >-
            Whether to get the forecast for the entire day or from present time.
            Defaults to false
          schema:
            type: boolean
      responses:
        '200':
          description: Hyperlocal forecast for the requested station
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HyperlocalForecast'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /stations/{station_id}/forecast/wxmv3:
    get:
      operationId: get-wxmv3-forecast
      summary: Get 7 day WXMv3 forecast for a station
      description: >
        The WXMv3 is a highly accurate, high-resolution forecast generated by an
        advanced post-processing system that combines outputs from multiple
        global and regional numerical weather prediction (NWP) models.


        Key Features:
          - Multi-model blending: Integrates data from over 40 different weather models, including ECMWF, GFS, and others.
          - Machine learning algorithms: Uses statistical and AI-based methods to optimize forecast accuracy by correcting systematic errors.
          - High-resolution output: Delivers detailed forecasts at resolutions down to 1 km, depending on the region.
          - Location-specific calibration: Forecasts are tailored using historical data and terrain-specific adjustments for hyper-local accuracy.
        The WXMv3 is included in all platform plans with forecasts for a
        specific set of demo stations, 23fb0d80-438d-11ef-8e8d-b55568dc8e66,
        52894530-4ead-11ed-960f-d7d4cf200cc9,
        df2c0430-512f-11ed-9972-4f669f2d96bd, while the Enterprise plan
        additionally provides WXMv3 forecast for one user-selected station.
        Contact us to get access to more stations.
      tags:
        - forecast
      security:
        - ApiKeyAuth: []
      parameters:
        - name: station_id
          in: path
          required: true
          description: The station to get the forecast for
          schema:
            type: string
        - name: timezone
          in: query
          required: false
          description: >-
            The timezone to get forecast for. Defaults to station location
            timezone
          schema:
            type: string
      responses:
        '200':
          description: MLM forecast for the requested station
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forecast'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /forecast/wxmv1:
    get:
      operationId: get-enhanced-wxmv1-forecast
      summary: Get enhanced WXMv1 forecast for a location
      description: >
        Get enhanced WXMv1 forecast for a specific location defined by latitude
        and longitude.
      tags:
        - forecast
      security:
        - ApiKeyAuth: []
      parameters:
        - name: lat
          in: query
          required: true
          description: Latitude
          schema:
            type: number
            format: float
        - name: lon
          in: query
          required: true
          description: Longitude
          schema:
            type: number
            format: float
        - name: from
          in: query
          required: false
          description: Start date (YYYY-MM-DD)
          schema:
            type: string
            format: date
        - name: to
          in: query
          required: false
          description: End date (YYYY-MM-DD)
          schema:
            type: string
            format: date
        - name: include
          in: query
          required: false
          description: >
            Comma separated list of intervals to include. Supported values:
            hourly, daily. Default: hourly
          schema:
            type: string
            default: hourly
      responses:
        '200':
          description: WXMv1 forecast for the requested location
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Forecast'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          description: Internal Server Error
  /stations/{station_id}/fact/performance:
    get:
      operationId: get-fact-performance
      summary: Get forecast models performance ranking per variable
      description: >-
        Get forecast models performance ranking per variable. Supported
        variables are temperature, humidity, precipitation, windSpeed and
        windDirection.
      tags:
        - fact
      security:
        - ApiKeyAuth: []
      parameters:
        - name: station_id
          in: path
          required: true
          description: The station to get the forecast performance for
          schema:
            type: string
          example: 0f7a89cb-123e-45d6-789f-0123456789ab
        - name: variable
          in: query
          required: true
          description: >-
            The weather variable to get the forecast for. Supported variables
            are temperature, humidity, precipitation, windSpeed and
            windDirection.
          schema:
            type: string
          example: temperature
      responses:
        '200':
          description: >-
            Forecast models performance ranking per variable for the requested
            station
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelWithRank'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /stations/{station_id}/fact/ranking:
    get:
      operationId: get-fact-ranking
      summary: Get forecast models ranking for a station per weather variable
      description: Get forecast models ranking for a station per weather variable
      tags:
        - fact
      security:
        - ApiKeyAuth: []
      parameters:
        - name: station_id
          in: path
          required: true
          description: The station to get the forecast ranking for
          schema:
            type: string
          example: 0f7a89cb-123e-45d6-789f-0123456789ab
      responses:
        '200':
          description: Forecast models ranking for the requested station
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelRanking'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-stoplight:
        id: qgr94eai1mbcc
  /stations/today:
    get:
      operationId: get-today-files
      summary: Get S3 file URLs for a time range (up to 24h)
      description: >-
        Returns a list of S3 file URLs for the specified time range. The start
        and end datetimes must be in ISO8601 format (e.g., '2025-05-15T10:00Z')
        and can be up to 24 hours in the past until the current datetime.
      tags:
        - observations
      security:
        - ApiKeyAuth: []
      parameters:
        - name: start
          in: query
          required: true
          description: Start datetime in ISO8601 UTC format (up to 24h in the past)
          schema:
            type: string
            format: date-time
            example: 2025-05-28T06:00:00.000Z
        - name: end
          in: query
          required: false
          description: End datetime in ISO8601 UTC format (up to now)
          schema:
            type: string
            format: date-time
            example: 2025-05-28T06:00:00.000Z
      responses:
        '200':
          description: >-
            List of URLs for the requested time range containing the latest data
            for all stations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TodayData'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /stations/today/{customer}:
    get:
      operationId: get-today-customer-files
      summary: Get S3 file URLs for a time range (up to 24h) for customer
      description: >-
        Returns a list of S3 file URLs for the specified time range. The start
        and end datetimes must be in ISO8601 format (e.g., '2025-05-15T10:00Z')
        and can be up to 24 hours in the past until the current datetime.
      tags:
        - observations
      security:
        - ApiKeyAuth: []
      parameters:
        - name: customer
          in: path
          required: true
          description: Customer ID
          schema:
            type: string
          example: customer-plan
        - name: start
          in: query
          required: true
          description: Start datetime in ISO8601 UTC format (up to 24h in the past)
          schema:
            type: string
            format: date-time
            example: 2025-05-28T06:00:00.000Z
        - name: end
          in: query
          required: false
          description: End datetime in ISO8601 UTC format (up to now)
          schema:
            type: string
            format: date-time
            example: 2025-05-28T06:00:00.000Z
      responses:
        '200':
          description: >-
            List of URLs for the requested time range containing the latest data
            for all stations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TodayData'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /rewards/{station_id}:
    get:
      operationId: get-station-rewards
      summary: Get the latest info about rewards earned by a specific station
      description: Info about the latest state of the station's rewards
      tags:
        - rewards
      security:
        - ApiKeyAuth: []
      parameters:
        - name: station_id
          in: path
          description: The id of the station
          required: true
          schema:
            type: string
            example: 3355b780-438d-11ef-8e8d-b55568dc8e66
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reward'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/UnknownError'
  /rewards/{station_id}/details:
    get:
      operationId: get-station-reward-details
      summary: Get reward details for a specific station on a specific date
      description: >-
        Get detailed information about the rewards distribution for a specific
        station
      tags:
        - rewards
      security:
        - ApiKeyAuth: []
      parameters:
        - name: station_id
          in: path
          description: The id of the station
          required: true
          schema:
            type: string
            example: 3355b780-438d-11ef-8e8d-b55568dc8e66
        - name: date
          in: query
          description: The date of the day of interest (format YYYY-MM-DD)
          required: true
          schema:
            type: string
            format: date
            example: '2025-07-01'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RewardDetails'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/UnknownError'
  /rewards/{station_id}/timeline:
    get:
      operationId: get-station-rewards-timeline
      summary: Get rewards details for a specific station in a time period
      description: >-
        Retrieves a timeline of rewards for a specific station, with optional
        filtering and pagination
      tags:
        - rewards
      security:
        - ApiKeyAuth: []
      parameters:
        - name: station_id
          in: path
          description: The id of the station
          required: true
          schema:
            type: string
            example: 3355b780-438d-11ef-8e8d-b55568dc8e66
        - name: timezone
          in: query
          description: What timezone to use
          required: false
          schema:
            type: string
            example: Europe/Athens
        - name: skip
          in: query
          description: >-
            Number of records to skip for pagination. Used to implement
            offset-based pagination.
          required: false
          schema:
            type: integer
            minimum: 0
            example: 0
        - name: limit
          in: query
          description: Maximum number of records to return. Must be between 1 and 50.
          required: false
          schema:
            type: integer
            minimum: 0
            maximum: 50
            example: 10
        - name: fromDate
          in: query
          description: What date to start from. Format is 'YYYY-MM-DD'
          required: false
          schema:
            type: string
            format: date
            example: '2025-06-01'
        - name: toDate
          in: query
          description: The ending date of the requested time period. Format is 'YYYY-MM-DD'
          required: false
          schema:
            type: string
            format: date
            example: '2025-07-01'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/TokenSummary'
                  pagination:
                    type: object
                    properties:
                      currentPage:
                        type: integer
                        description: Current page number
                        example: 0
                      pageSize:
                        type: integer
                        description: Number of items per page
                        example: 30
                      totalItems:
                        type: integer
                        description: Total number of items available
                        example: 120
                      totalPages:
                        type: integer
                        description: Total number of pages available
                        example: 4
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/UnknownError'