openapi: 3.0.3
info:
  title: Rainbow.AI Nowcast Tiles API
  description: The Rainbow.AI Nowcast API delivers hyperlocal precipitation forecasts with minute-by-minute predictions for the next 4 hours at 1 km spatial resolution. It returns precipitation type and intensity for any global coordinate, updated every 10 minutes. Authentication is via API key in header or query parameter.
  version: '1.0'
  termsOfService: https://developer.rainbow.ai/terms-of-service
  contact:
    url: https://developer.rainbow.ai/
  x-tags:
  - Weather
  - Nowcast
  - Precipitation
  - Forecasting
servers:
- url: https://api.rainbow.ai/v1
  description: Rainbow.AI Production API
security:
- ApiKeyHeader: []
- ApiKeyQuery: []
tags:
- name: Tiles
  description: Weather map tile retrieval operations
paths:
  /map/tile/{z}/{x}/{y}:
    get:
      operationId: getMapTile
      summary: Get Weather Map Tile
      description: Returns a 256x256 PNG weather map tile at the specified zoom level and tile coordinates using the XYZ tiling scheme. Tiles show precipitation forecasts and can be overlaid on any mapping library (Leaflet, Mapbox, Google Maps, etc.).
      tags:
      - Tiles
      parameters:
      - name: z
        in: path
        required: true
        description: Zoom level (0-18)
        schema:
          type: integer
          minimum: 0
          maximum: 18
          example: 10
      - name: x
        in: path
        required: true
        description: Tile X coordinate
        schema:
          type: integer
          example: 301
      - name: y
        in: path
        required: true
        description: Tile Y coordinate
        schema:
          type: integer
          example: 385
      - name: timestamp
        in: query
        required: false
        description: ISO 8601 timestamp for the desired forecast time. If omitted, returns the current precipitation tile.
        schema:
          type: string
          format: date-time
          example: '2026-05-02T12:00:00Z'
      - name: layer
        in: query
        required: false
        description: The weather layer type to render
        schema:
          type: string
          enum:
          - precipitation
          - radar
          default: precipitation
      responses:
        '200':
          description: PNG weather map tile image
          content:
            image/png:
              schema:
                type: string
                format: binary
        '401':
          description: Unauthorized - missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Tile not found for the given coordinates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests - rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /map/timestamps:
    get:
      operationId: getAvailableTimestamps
      summary: Get Available Tile Timestamps
      description: Returns a list of available timestamps for which weather tile data is available. Use this to build time-slider controls for animated weather visualizations.
      tags:
      - Tiles
      responses:
        '200':
          description: List of available tile timestamps
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimestampsResponse'
        '401':
          description: Unauthorized - missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    TimestampsResponse:
      type: object
      description: Available tile timestamps for weather data
      properties:
        past:
          type: array
          description: Available historical radar timestamps
          items:
            type: string
            format: date-time
        future:
          type: array
          description: Available forecast timestamps (up to 4 hours ahead)
          items:
            type: string
            format: date-time
        updated_at:
          type: string
          format: date-time
          description: When this list was last updated
    ErrorResponse:
      type: object
      description: Error response object
      properties:
        error:
          type: string
          description: Error type identifier
        message:
          type: string
          description: Human-readable error message
        status:
          type: integer
          description: HTTP status code
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: Ocp-Apim-Subscription-Key
      description: API key passed in the Ocp-Apim-Subscription-Key header
    ApiKeyQuery:
      type: apiKey
      in: query
      name: token
      description: API key passed as a token query parameter