openapi: 3.0.3
info:
  title: Meteomatics Weather API
  description: >
    The Meteomatics Weather API provides access to over 1,800 weather parameters
    including hyperlocal forecasts, historical data back to 1940, climate scenarios
    to 2100, marine conditions, and environmental variables at up to 1 km resolution
    globally. The API supports point, multi-location, route, and polygon queries,
    and returns data in JSON, CSV, XML, PNG, GeoTIFF, WebP, HTML, and NetCDF formats.
    Authentication is via HTTP Basic Auth or an OAuth2 bearer token.
  version: "3.0"
  termsOfService: https://www.meteomatics.com/en/terms-and-conditions/
  contact:
    name: Meteomatics Support
    email: support@meteomatics.com
    url: https://www.meteomatics.com/en/contact/
  license:
    name: Commercial
    url: https://www.meteomatics.com/en/pricing/

externalDocs:
  description: Full API documentation
  url: https://www.meteomatics.com/en/api/

servers:
  - url: https://api.meteomatics.com
    description: Meteomatics production API

security:
  - basicAuth: []
  - bearerAuth: []

tags:
  - name: Weather Data
    description: Query weather parameters for point, grid, multi-location, and route requests
  - name: Authentication
    description: Obtain OAuth2 bearer tokens
  - name: User
    description: Account usage statistics

paths:

  /user_stats:
    get:
      summary: Get user statistics (HTML)
      description: Returns current query limits and usage statistics for the authenticated user in HTML format.
      operationId: getUserStats
      tags:
        - User
      responses:
        "200":
          description: HTML page with user statistics
          content:
            text/html:
              schema:
                type: string
        "401":
          $ref: "#/components/responses/Unauthorized"

  /user_stats_json:
    get:
      summary: Get user statistics (JSON)
      description: Returns current query limits and usage statistics for the authenticated user in JSON format.
      operationId: getUserStatsJson
      tags:
        - User
      responses:
        "200":
          description: JSON object with user statistics
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserStats"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /{validdatetime}/{parameters}/{location}/json:
    get:
      summary: Query weather data — JSON output
      description: >
        Retrieve weather data for a given datetime or time range, one or more weather
        parameters, and a point or multi-point location. Returns results as JSON.

        **URL pattern:**
        `/{validdatetime}/{parameters}/{location}/json`

        - `validdatetime` — ISO 8601 timestamp or range+step, e.g.
          `2026-06-12T00:00:00Z` or `2026-06-12T00:00:00Z--2026-06-15T00:00:00Z:PT1H`
        - `parameters` — comma-separated parameter codes, e.g. `t_2m:C,precip_1h:mm`
        - `location` — `{lat},{lon}` for a point, or `{lat1},{lon1}+{lat2},{lon2}+...`
          for multiple points
      operationId: getWeatherDataJson
      tags:
        - Weather Data
      parameters:
        - $ref: "#/components/parameters/validdatetime"
        - $ref: "#/components/parameters/parameters"
        - $ref: "#/components/parameters/location"
        - $ref: "#/components/parameters/model"
        - $ref: "#/components/parameters/access_token"
      responses:
        "200":
          description: Weather data in JSON format
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WeatherResponse"
              example:
                version: "3.0"
                user: "api_user"
                dateGenerated: "2026-06-12T00:01:00Z"
                status: "OK"
                data:
                  - parameter: "t_2m:C"
                    coordinates:
                      - lat: 52.5206
                        lon: 13.4618
                        dates:
                          - date: "2026-06-12T00:00:00Z"
                            value: 18.4
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"

  /{validdatetime}/{parameters}/{location}/csv:
    get:
      summary: Query weather data — CSV output
      description: >
        Retrieve weather data and return as CSV. See the JSON endpoint for full parameter
        descriptions.
      operationId: getWeatherDataCsv
      tags:
        - Weather Data
      parameters:
        - $ref: "#/components/parameters/validdatetime"
        - $ref: "#/components/parameters/parameters"
        - $ref: "#/components/parameters/location"
        - $ref: "#/components/parameters/model"
        - $ref: "#/components/parameters/access_token"
      responses:
        "200":
          description: Weather data in CSV format
          content:
            text/csv:
              schema:
                type: string
                description: CSV rows with header; columns depend on requested parameters.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"

  /{validdatetime}/{parameters}/{location}/xml:
    get:
      summary: Query weather data — XML output
      description: >
        Retrieve weather data and return as XML. See the JSON endpoint for full parameter
        descriptions.
      operationId: getWeatherDataXml
      tags:
        - Weather Data
      parameters:
        - $ref: "#/components/parameters/validdatetime"
        - $ref: "#/components/parameters/parameters"
        - $ref: "#/components/parameters/location"
        - $ref: "#/components/parameters/model"
        - $ref: "#/components/parameters/access_token"
      responses:
        "200":
          description: Weather data in XML format
          content:
            application/xml:
              schema:
                type: string
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"

  /{validdatetime}/{parameters}/{location}/png:
    get:
      summary: Query weather data — PNG image output
      description: >
        Retrieve weather data rendered as a PNG raster image.
      operationId: getWeatherDataPng
      tags:
        - Weather Data
      parameters:
        - $ref: "#/components/parameters/validdatetime"
        - $ref: "#/components/parameters/parameters"
        - $ref: "#/components/parameters/location"
        - $ref: "#/components/parameters/model"
        - name: colormap
          in: query
          schema:
            type: string
          description: Colormap name to use for rendering (e.g. `blue-white-red`).
        - $ref: "#/components/parameters/access_token"
      responses:
        "200":
          description: PNG raster image of the requested weather parameter
          content:
            image/png:
              schema:
                type: string
                format: binary
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/v1/token:
    get:
      summary: Obtain OAuth2 bearer token
      description: >
        Exchange Basic Auth credentials for a short-lived JWT bearer token (valid
        2 hours). Use the returned token as `?access_token=<token>` on subsequent
        requests or as `Authorization: Bearer <token>`.
      operationId: getToken
      tags:
        - Authentication
      security:
        - basicAuth: []
      servers:
        - url: https://login.meteomatics.com
          description: Meteomatics login server
      responses:
        "200":
          description: Bearer token issued successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"

components:

  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication using Meteomatics account credentials.
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        JWT bearer token obtained from `https://login.meteomatics.com/api/v1/token`.
        May also be supplied as the `access_token` query parameter.

  parameters:
    validdatetime:
      name: validdatetime
      in: path
      required: true
      description: >
        ISO 8601 datetime, or a range with step in the form
        `{start}--{end}:{step}` (e.g. `2026-06-12T00:00:00Z` or
        `2026-06-12T00:00:00Z--2026-06-15T00:00:00Z:PT1H`).
      schema:
        type: string
        example: "2026-06-12T00:00:00Z"
    parameters:
      name: parameters
      in: path
      required: true
      description: >
        Comma-separated list of weather parameter codes with units, e.g.
        `t_2m:C,precip_1h:mm,wind_speed_10m:ms`. Over 1,800 parameters supported.
      schema:
        type: string
        example: "t_2m:C,precip_1h:mm"
    location:
      name: location
      in: path
      required: true
      description: >
        Point: `{lat},{lon}` (e.g. `52.52,13.40`).
        Multi-point: `{lat1},{lon1}+{lat2},{lon2}`.
        Grid: `{lat_min},{lon_min}_{lat_max},{lon_max}:{lat_res},{lon_res}`.
      schema:
        type: string
        example: "52.52,13.40"
    model:
      name: model
      in: query
      required: false
      description: >
        Data source / model to use. `mix` (default) blends the best available
        sources. Other values: `ecmwf-ifs`, `ncep-gfs`, `mch-cosmo-1e`, etc.
      schema:
        type: string
        example: "mix"
    access_token:
      name: access_token
      in: query
      required: false
      description: JWT bearer token as an alternative to the Authorization header.
      schema:
        type: string

  schemas:

    WeatherResponse:
      type: object
      description: Top-level JSON response for weather data queries.
      properties:
        version:
          type: string
          description: API response schema version.
          example: "3.0"
        user:
          type: string
          description: Username associated with the request.
          example: "api_user"
        dateGenerated:
          type: string
          format: date-time
          description: UTC timestamp when the response was generated.
          example: "2026-06-12T00:01:00Z"
        status:
          type: string
          description: Response status indicator.
          enum: [OK, ERROR]
          example: "OK"
        data:
          type: array
          description: Array of weather parameter result objects.
          items:
            $ref: "#/components/schemas/ParameterData"

    ParameterData:
      type: object
      description: Weather data for a single parameter.
      properties:
        parameter:
          type: string
          description: Parameter code with unit (e.g. `t_2m:C`).
          example: "t_2m:C"
        coordinates:
          type: array
          description: Results per requested location.
          items:
            $ref: "#/components/schemas/CoordinateData"

    CoordinateData:
      type: object
      description: Weather values at a single geographic coordinate.
      properties:
        lat:
          type: number
          format: double
          description: Latitude in decimal degrees (WGS84).
          example: 52.52
        lon:
          type: number
          format: double
          description: Longitude in decimal degrees (WGS84).
          example: 13.40
        dates:
          type: array
          description: Time-value pairs.
          items:
            $ref: "#/components/schemas/DateValue"

    DateValue:
      type: object
      description: A single time-stamped weather value.
      properties:
        date:
          type: string
          format: date-time
          description: UTC timestamp of the observation or forecast.
          example: "2026-06-12T00:00:00Z"
        value:
          type: number
          description: Numeric value of the weather parameter.
          example: 18.4

    TokenResponse:
      type: object
      description: OAuth2 bearer token response.
      properties:
        access_token:
          type: string
          description: JWT bearer token, valid for 2 hours.
          example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
        token_type:
          type: string
          example: "bearer"
        expires_in:
          type: integer
          description: Token lifetime in seconds (7200 = 2 hours).
          example: 7200

    UserStats:
      type: object
      description: Account usage and quota statistics.
      properties:
        user:
          type: string
          description: Username.
          example: "api_user"
        requests_today:
          type: integer
          description: Number of API requests made today.
          example: 142
        requests_limit:
          type: integer
          description: Maximum requests allowed per day.
          example: 5000
        data_points_today:
          type: integer
          description: Number of data points retrieved today.
          example: 14200
        data_points_limit:
          type: integer
          description: Maximum data points allowed per day.
          example: 500000

    ErrorResponse:
      type: object
      description: Standard error envelope.
      properties:
        status:
          type: string
          example: "ERROR"
        message:
          type: string
          description: Human-readable error description.
          example: "Invalid parameter: t_999m:C"

  responses:
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    BadRequest:
      description: The request is malformed — check datetime, parameter codes, or location format.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    RateLimitExceeded:
      description: Daily request or data-point quota exceeded.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"