ColorfulClouds Forecast API

openapi: 3.0.3
info:
  title: Caiyun Weather Air Quality Forecast API
  version: '2.6'
  description: Caiyun Weather API v2.6 from ColorfulClouds Tech (彩云科技). Hyperlocal weather, minute-level precipitation nowcasting, hourly forecast up to 360 hours, daily forecast up to 15 days, real-time air quality with CHN + USA AQI standards, severe-weather alerts, life indices, and a precipitation map raster. All operations share a single base URL pattern with the API token embedded in the path and lng,lat as a path tuple.
  contact:
    name: ColorfulClouds Tech (彩云科技)
    url: https://docs.caiyunapp.com/weather-api/
    email: hi@caiyunapp.com
  license:
    name: Commercial — Caiyun Weather API Terms
    url: https://platform.caiyunapp.com/
  x-generated-from: documentation+sdk
  x-source-urls:
  - https://docs.caiyunapp.com/weather-api/
  - https://github.com/caiyunapp/mcp-caiyun-weather
  - https://github.com/caiyunapp/caiyun-weather-api-python-sdk
  x-last-validated: '2026-05-30'
servers:
- url: https://api.caiyunapp.com/v2.6
  description: Caiyun Weather API v2.6 production endpoint
security:
- pathToken: []
tags:
- name: Forecast
  description: Minute-level, hourly, and daily forecast endpoints.
paths:
  /{token}/{lnglat}/minutely:
    parameters:
    - $ref: '#/components/parameters/Token'
    - $ref: '#/components/parameters/LngLat'
    get:
      operationId: getMinutelyPrecipitation
      summary: Caiyun Weather Get Minutely Precipitation Forecast
      description: Returns 120-minute minute-level precipitation nowcast (mm/hr) and per-minute probability series for the requested location, plus a natural-language summary of the precipitation pattern.
      tags:
      - Forecast
      parameters:
      - $ref: '#/components/parameters/Lang'
      - $ref: '#/components/parameters/Unit'
      responses:
        '200':
          description: Minutely precipitation payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MinutelyResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{token}/{lnglat}/hourly:
    parameters:
    - $ref: '#/components/parameters/Token'
    - $ref: '#/components/parameters/LngLat'
    get:
      operationId: getHourlyForecast
      summary: Caiyun Weather Get Hourly Weather Forecast
      description: Returns hourly forecast series for up to 360 hours covering temperature, apparent temperature, humidity, cloud cover, sky condition, precipitation (value + probability), pressure, visibility, downward shortwave radiation, wind, and air quality (AQI + PM2.5). When the begin parameter is supplied the series is anchored at that Unix epoch second instead of "now".
      tags:
      - Forecast
      parameters:
      - $ref: '#/components/parameters/Lang'
      - $ref: '#/components/parameters/Unit'
      - $ref: '#/components/parameters/HourlySteps'
      - $ref: '#/components/parameters/Begin'
      responses:
        '200':
          description: Hourly forecast payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HourlyResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /{token}/{lnglat}/daily:
    parameters:
    - $ref: '#/components/parameters/Token'
    - $ref: '#/components/parameters/LngLat'
    get:
      operationId: getDailyForecast
      summary: Caiyun Weather Get Daily Weather Forecast
      description: Returns daily forecast series for up to 15 days covering astronomical sunrise/sunset, precipitation, temperature, humidity, cloud cover, pressure, visibility, downward shortwave radiation, wind, sky condition, air quality, and life indices. Includes daytime (08h-20h) and nighttime (20h-32h) splits for skycon, precipitation, temperature, and wind. Free tier returns 3 days; paid tiers extend to 15.
      tags:
      - Forecast
      parameters:
      - $ref: '#/components/parameters/Lang'
      - $ref: '#/components/parameters/Unit'
      - $ref: '#/components/parameters/DailySteps'
      - $ref: '#/components/parameters/Begin'
      responses:
        '200':
          description: Daily forecast payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DailyResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    HourlyResponse:
      title: HourlyResponse
      allOf:
      - $ref: '#/components/schemas/EnvelopeBase'
      - type: object
        properties:
          result:
            type: object
            properties:
              hourly:
                $ref: '#/components/schemas/Hourly'
              primary:
                type: integer
            required:
            - hourly
    DailyPrecipitationItem:
      title: DailyPrecipitationItem
      type: object
      properties:
        date:
          type: string
          format: date
        max:
          type: number
          format: float
        min:
          type: number
          format: float
        avg:
          type: number
          format: float
        probability:
          type: number
          format: float
      required:
      - date
      - max
      - min
      - avg
      - probability
    HourlyPM25Item:
      title: HourlyPM25Item
      type: object
      properties:
        datetime:
          type: string
          format: date-time
        value:
          type: number
          format: float
      required:
      - datetime
      - value
    MinutelyResponse:
      title: MinutelyResponse
      allOf:
      - $ref: '#/components/schemas/EnvelopeBase'
      - type: object
        properties:
          result:
            type: object
            properties:
              minutely:
                $ref: '#/components/schemas/Minutely'
              primary:
                type: integer
              forecast_keypoint:
                type: string
            required:
            - minutely
    HourlyAirQuality:
      title: HourlyAirQuality
      type: object
      properties:
        aqi:
          type: array
          items:
            $ref: '#/components/schemas/HourlyAQIItem'
        pm25:
          type: array
          items:
            $ref: '#/components/schemas/HourlyPM25Item'
    DailyWindItem:
      title: DailyWindItem
      type: object
      properties:
        date:
          type: string
          format: date
        max:
          $ref: '#/components/schemas/DailyWindProperty'
        min:
          $ref: '#/components/schemas/DailyWindProperty'
        avg:
          $ref: '#/components/schemas/DailyWindProperty'
      required:
      - date
      - max
      - min
      - avg
    HourlyPrecipitationItem:
      title: HourlyPrecipitationItem
      type: object
      properties:
        datetime:
          type: string
          format: date-time
        value:
          type: number
          format: float
          description: Precipitation intensity in mm/hr.
        probability:
          type: number
          format: float
          description: Per-hour precipitation probability (0-100).
      required:
      - datetime
      - value
      - probability
    DailyMinMaxAvgItem:
      title: DailyMinMaxAvgItem
      type: object
      properties:
        date:
          type: string
          format: date
        max:
          type: number
          format: float
        min:
          type: number
          format: float
        avg:
          type: number
          format: float
      required:
      - date
      - max
      - min
      - avg
    DailyAstroItem:
      title: DailyAstroItem
      type: object
      properties:
        date:
          type: string
          format: date
        sunrise:
          $ref: '#/components/schemas/DailyAstroTime'
        sunset:
          $ref: '#/components/schemas/DailyAstroTime'
      required:
      - date
      - sunrise
      - sunset
    SkyCon:
      title: SkyCon
      type: string
      description: Normalized weather phenomenon (sky condition) enum.
      enum:
      - CLEAR_DAY
      - CLEAR_NIGHT
      - PARTLY_CLOUDY_DAY
      - PARTLY_CLOUDY_NIGHT
      - CLOUDY
      - LIGHT_HAZE
      - MODERATE_HAZE
      - HEAVY_HAZE
      - LIGHT_RAIN
      - MODERATE_RAIN
      - HEAVY_RAIN
      - STORM_RAIN
      - FOG
      - LIGHT_SNOW
      - MODERATE_SNOW
      - HEAVY_SNOW
      - STORM_SNOW
      - DUST
      - SAND
      - WIND
      example: PARTLY_CLOUDY_DAY
    DailyAstroTime:
      title: DailyAstroTime
      type: object
      properties:
        time:
          type: string
          example: 05:48
      required:
      - time
    DailyAQIItem:
      title: DailyAQIItem
      type: object
      properties:
        date:
          type: string
          format: date
        max:
          $ref: '#/components/schemas/AQIValueDual'
        min:
          $ref: '#/components/schemas/AQIValueDual'
        avg:
          $ref: '#/components/schemas/AQIValueDual'
      required:
      - date
      - max
      - min
      - avg
    HourlyWindItem:
      title: HourlyWindItem
      type: object
      properties:
        datetime:
          type: string
          format: date-time
        speed:
          type: number
          format: float
        direction:
          type: number
          format: float
      required:
      - datetime
      - speed
      - direction
    EnvelopeBase:
      title: EnvelopeBase
      type: object
      description: Common envelope fields returned by every Caiyun Weather endpoint.
      properties:
        status:
          type: string
          example: ok
        api_version:
          type: string
          example: v2.6
        api_status:
          type: string
          example: active
        lang:
          type: string
          example: en_US
        unit:
          type: string
          example: metric:v2
        tzshift:
          type: integer
          description: Time zone shift in seconds from UTC.
          example: 28800
        timezone:
          type: string
          example: Asia/Shanghai
        server_time:
          type: integer
          description: Server time as Unix epoch seconds.
          example: 1748563200
        location:
          type: array
          items:
            type: number
            format: float
          minItems: 2
          maxItems: 2
          description: Resolved (lat,lng) the response was generated for.
      required:
      - status
      - api_version
      - api_status
    DailyAirQuality:
      title: DailyAirQuality
      type: object
      properties:
        aqi:
          type: array
          items:
            $ref: '#/components/schemas/DailyAQIItem'
        pm25:
          type: array
          items:
            $ref: '#/components/schemas/DailyMinMaxAvgItem'
    DailyLifeIndexEntry:
      title: DailyLifeIndexEntry
      type: object
      properties:
        date:
          type: string
          format: date
        index:
          oneOf:
          - type: number
          - type: string
        desc:
          type: string
      required:
      - date
      - index
      - desc
    Daily:
      title: Daily
      type: object
      description: Daily forecast series block.
      properties:
        status:
          type: string
          example: ok
        astro:
          type: array
          items:
            $ref: '#/components/schemas/DailyAstroItem'
        precipitation:
          type: array
          items:
            $ref: '#/components/schemas/DailyPrecipitationItem'
        precipitation_08h_20h:
          type: array
          items:
            $ref: '#/components/schemas/DailyPrecipitationItem'
        precipitation_20h_32h:
          type: array
          items:
            $ref: '#/components/schemas/DailyPrecipitationItem'
        temperature:
          type: array
          items:
            $ref: '#/components/schemas/DailyMinMaxAvgItem'
        temperature_08h_20h:
          type: array
          items:
            $ref: '#/components/schemas/DailyMinMaxAvgItem'
        temperature_20h_32h:
          type: array
          items:
            $ref: '#/components/schemas/DailyMinMaxAvgItem'
        humidity:
          type: array
          items:
            $ref: '#/components/schemas/DailyMinMaxAvgItem'
        cloudrate:
          type: array
          items:
            $ref: '#/components/schemas/DailyMinMaxAvgItem'
        pressure:
          type: array
          items:
            $ref: '#/components/schemas/DailyMinMaxAvgItem'
        visibility:
          type: array
          items:
            $ref: '#/components/schemas/DailyMinMaxAvgItem'
        dswrf:
          type: array
          items:
            $ref: '#/components/schemas/DailyMinMaxAvgItem'
        wind:
          type: array
          items:
            $ref: '#/components/schemas/DailyWindItem'
        wind_08h_20h:
          type: array
          items:
            $ref: '#/components/schemas/DailyWindItem'
        wind_20h_32h:
          type: array
          items:
            $ref: '#/components/schemas/DailyWindItem'
        skycon:
          type: array
          items:
            $ref: '#/components/schemas/DailySkyconItem'
        skycon_08h_20h:
          type: array
          items:
            $ref: '#/components/schemas/DailySkyconItem'
        skycon_20h_32h:
          type: array
          items:
            $ref: '#/components/schemas/DailySkyconItem'
        life_index:
          $ref: '#/components/schemas/DailyLifeIndex'
        air_quality:
          $ref: '#/components/schemas/DailyAirQuality'
      required:
      - status
    DailySkyconItem:
      title: DailySkyconItem
      type: object
      properties:
        date:
          type: string
          format: date
        value:
          $ref: '#/components/schemas/SkyCon'
      required:
      - date
      - value
    DateTimeValuePair:
      title: DateTimeValuePair
      type: object
      properties:
        datetime:
          type: string
          format: date-time
          example: '2026-05-30T15:00:00+08:00'
        value:
          type: number
          format: float
          example: 23.1
      required:
      - datetime
      - value
    Hourly:
      title: Hourly
      type: object
      description: Hourly forecast series block.
      properties:
        status:
          type: string
          example: ok
        description:
          type: string
          example: clear weather over the next 24 hours
        precipitation:
          type: array
          items:
            $ref: '#/components/schemas/HourlyPrecipitationItem'
        temperature:
          type: array
          items:
            $ref: '#/components/schemas/DateTimeValuePair'
        apparent_temperature:
          type: array
          items:
            $ref: '#/components/schemas/DateTimeValuePair'
        humidity:
          type: array
          items:
            $ref: '#/components/schemas/DateTimeValuePair'
        cloudrate:
          type: array
          items:
            $ref: '#/components/schemas/DateTimeValuePair'
        skycon:
          type: array
          items:
            $ref: '#/components/schemas/HourlySkyconItem'
        pressure:
          type: array
          items:
            $ref: '#/components/schemas/DateTimeValuePair'
        visibility:
          type: array
          items:
            $ref: '#/components/schemas/DateTimeValuePair'
        dswrf:
          type: array
          items:
            $ref: '#/components/schemas/DateTimeValuePair'
        wind:
          type: array
          items:
            $ref: '#/components/schemas/HourlyWindItem'
        air_quality:
          $ref: '#/components/schemas/HourlyAirQuality'
      required:
      - status
      - description
    DailyWindProperty:
      title: DailyWindProperty
      type: object
      properties:
        speed:
          type: number
          format: float
        direction:
          type: number
          format: float
      required:
      - speed
      - direction
    HourlySkyconItem:
      title: HourlySkyconItem
      type: object
      properties:
        datetime:
          type: string
          format: date-time
        value:
          $ref: '#/components/schemas/SkyCon'
      required:
      - datetime
      - value
    ErrorResponse:
      title: ErrorResponse
      type: object
      description: Error envelope returned for invalid requests, auth failures, and rate-limit violations.
      properties:
        status:
          type: string
          example: failed
        error:
          type: string
          example: Invalid token
        api_status:
          type: string
          example: deactive
      required:
      - status
    DailyResponse:
      title: DailyResponse
      allOf:
      - $ref: '#/components/schemas/EnvelopeBase'
      - type: object
        properties:
          result:
            type: object
            properties:
              daily:
                $ref: '#/components/schemas/Daily'
              primary:
                type: integer
            required:
            - daily
    DailyLifeIndex:
      title: DailyLifeIndex
      type: object
      properties:
        ultraviolet:
          type: array
          items:
            $ref: '#/components/schemas/DailyLifeIndexEntry'
        carWashing:
          type: array
          items:
            $ref: '#/components/schemas/DailyLifeIndexEntry'
        dressing:
          type: array
          items:
            $ref: '#/components/schemas/DailyLifeIndexEntry'
        comfort:
          type: array
          items:
            $ref: '#/components/schemas/DailyLifeIndexEntry'
        coldRisk:
          type: array
          items:
            $ref: '#/components/schemas/DailyLifeIndexEntry'
    Minutely:
      title: Minutely
      type: object
      description: Minute-level precipitation nowcast block (next 120 minutes).
      properties:
        status:
          type: string
          example: ok
        datasource:
          type: string
          example: radar
        precipitation_2h:
          type: array
          items:
            type: number
            format: float
          minItems: 120
          maxItems: 120
          description: 120 minutes of precipitation intensity in mm/hr.
        precipitation:
          type: array
          items:
            type: number
            format: float
          minItems: 60
          maxItems: 60
          description: 60 minutes of precipitation intensity in mm/hr.
        probability:
          type: array
          items:
            type: number
            format: float
          description: Per-segment precipitation probability (0-1).
        description:
          type: string
          description: Natural-language summary of the precipitation pattern.
          example: clear weather over the next 2 hours
      required:
      - status
      - description
    HourlyAQIItem:
      title: HourlyAQIItem
      type: object
      properties:
        datetime:
          type: string
          format: date-time
        value:
          $ref: '#/components/schemas/AQIValueDual'
      required:
      - datetime
      - value
    AQIValueDual:
      title: AQIValueDual
      type: object
      description: AQI numeric value under both Chinese and US standards.
      properties:
        chn:
          type: number
          format: float
          example: 78.0
        usa:
          type: number
          format: float
          example: 95.0
      required:
      - chn
      - usa
  parameters:
    HourlySteps:
      name: hourlysteps
      in: query
      required: false
      description: Number of hourly forecast steps to return.
      schema:
        type: integer
        minimum: 1
        maximum: 360
        default: 48
      example: 72
    Unit:
      name: unit
      in: query
      required: false
      description: Unit system for numeric values (temperature, wind, precipitation, pressure).
      schema:
        type: string
        enum:
        - metric
        - metric:v1
        - metric:v2
        - imperial
        - SI
        default: metric
      example: metric:v2
    DailySteps:
      name: dailysteps
      in: query
      required: false
      description: Number of daily forecast days to return. Free tier caps at 3.
      schema:
        type: integer
        minimum: 1
        maximum: 15
        default: 5
      example: 7
    Token:
      name: token
      in: path
      required: true
      description: Caiyun Weather API token issued by the Open Platform (platform.caiyunapp.com). Embedded in the path rather than a header.
      schema:
        type: string
      example: TAkhjf8d1nlSlspN
    Lang:
      name: lang
      in: query
      required: false
      description: Response language for description fields.
      schema:
        type: string
        enum:
        - zh_CN
        - zh_TW
        - ja
        - en_GB
        - en_US
        default: en_US
      example: en_US
    LngLat:
      name: lnglat
      in: path
      required: true
      description: Longitude,latitude tuple as `lng,lat` (note the order — longitude first). Use WGS84 decimal degrees.
      schema:
        type: string
        pattern: ^-?\d+(\.\d+)?,-?\d+(\.\d+)?$
      example: 116.4074,39.9042
    Begin:
      name: begin
      in: query
      required: false
      description: Anchor the forecast or historical series at a specific Unix epoch second instead of "now". Used to fetch past 24h (historical) or shift the start of the forecast window.
      schema:
        type: integer
      example: 1748563200
  responses:
    RateLimited:
      description: Per-token quota exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Malformed request (invalid coordinates, parameter out of range)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Invalid or missing API token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    pathToken:
      type: apiKey
      in: query
      name: token
      description: Caiyun Weather API token. Note that the token is conventionally embedded in the path between the API version and the lng,lat segment rather than sent as a header or query parameter. This security scheme is recorded for tooling completeness; clients should construct the URL with the token in the path as documented.