ColorfulClouds Air Quality API

openapi: 3.0.3
info:
  title: Caiyun Weather Air Quality 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: Air Quality
  description: Real-time pollutant readings and AQI values under CHN and USA standards.
paths:
  /{token}/{lnglat}/air-quality:
    parameters:
    - $ref: '#/components/parameters/Token'
    - $ref: '#/components/parameters/LngLat'
    get:
      operationId: getRealtimeAirQuality
      summary: Caiyun Weather Get Realtime Air Quality
      description: Returns real-time air quality readings — PM2.5, PM10, O3, SO2, NO2, CO concentrations plus AQI values and category descriptions under both Chinese (HJ 633-2012) and US EPA standards.
      tags:
      - Air Quality
      parameters:
      - $ref: '#/components/parameters/Lang'
      responses:
        '200':
          description: Realtime air quality payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AirQualityRealtimeResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    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
    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
  schemas:
    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
    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
    AirQualityRealtime:
      title: AirQualityRealtime
      type: object
      description: Realtime pollutant concentrations and AQI.
      properties:
        aqi:
          $ref: '#/components/schemas/AQIValueDual'
        description:
          $ref: '#/components/schemas/AQIDescDual'
        pm25:
          type: number
          format: float
          description: PM2.5 concentration in µg/m³.
          example: 32.0
        pm10:
          type: number
          format: float
          example: 48.0
        o3:
          type: number
          format: float
          example: 96.0
        so2:
          type: number
          format: float
          example: 4.0
        no2:
          type: number
          format: float
          example: 21.0
        co:
          type: number
          format: float
          description: CO concentration in mg/m³.
          example: 0.6
      required:
      - aqi
      - description
    AirQualityRealtimeResponse:
      title: AirQualityRealtimeResponse
      allOf:
      - $ref: '#/components/schemas/EnvelopeBase'
      - type: object
        properties:
          result:
            type: object
            properties:
              realtime:
                type: object
                properties:
                  air_quality:
                    $ref: '#/components/schemas/AirQualityRealtime'
                required:
                - air_quality
            required:
            - realtime
    AQIDescDual:
      title: AQIDescDual
      type: object
      description: AQI category description under both standards.
      properties:
        chn:
          type: string
          example: Good
        usa:
          type: string
          example: Moderate
      required:
      - chn
      - usa
    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
  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.