canonical: https://jentic.com/apis/caiyunapp.com/caiyun # Caiyunapp ColorfulClouds Weather API Jentic publishes the only available OpenAPI specification for the ColorfulClouds Weather API, keeping it validated and agent-ready. ColorfulClouds (Caiyun) provides global weather data with a specialism in minutely precipitation nowcasting that is especially detailed for China. Six GET endpoints cover real-time conditions, minutely precipitation, hourly forecasts, daily forecasts, and a unified weather aggregate, each accepting longitude and latitude in the path along with an API token. The API supports multiple languages and unit systems through query parameters and is well-suited to outdoor activity, logistics, and travel agents that need short-horizon precipitation predictions. ## For AI agents Fetch real-time weather, minute-by-minute precipitation nowcasts, and hourly or daily forecasts for any longitude and latitude through the Caiyun ColorfulClouds Weather API. ## Scope Does not handle severe-weather alerting subscriptions, historical climate archives, or air quality forecasting - use for realtime conditions and short to medium-range forecasts at a coordinate only. ## Capabilities - Retrieve real-time weather conditions for any longitude and latitude via realtime.json - Get minute-by-minute precipitation nowcasts via minutely.json - Fetch hourly forecasts for the next 24 hours via hourly.json - Fetch multi-day daily forecasts via daily.json - Pull a combined realtime, hourly, and daily aggregate via weather.json - Localise responses by language and unit system using query parameters ## Use cases ### Outdoor Activity Rain Alert Power running, cycling, and outdoor sports apps with two-hour precipitation nowcasts by calling minutely.json for the user's current coordinates. ColorfulClouds is well known for accurate short-horizon rain prediction in China and provides global coverage at coarser granularity. The agent surfaces a 'rain in N minutes' string to the user without operating its own weather model. Example prompt: GET /{token}/{longitude},{latitude}/minutely.json with the user's coordinates and parse the precipitation array into a 'rain in N minutes' string. ### Logistics Route Weather Check For delivery and logistics platforms, retrieve hourly or daily forecasts along the route to flag risk windows for outdoor work, refrigerated cargo, or last-mile cycling. The hourly.json endpoint returns a 24-hour forecast, while daily.json covers multi-day planning. Both accept the same coordinate and token URL pattern, so a worker can sweep waypoints with one loop. Example prompt: For each waypoint, GET /{token}/{longitude},{latitude}/hourly.json and flag any hour where precipitation exceeds a threshold. ### Travel App Destination Weather Show travellers a unified weather summary using weather.json, which returns realtime, hourly, and daily forecasts in a single call. This avoids three separate round trips at app launch and keeps the destination card responsive even on slow networks. Travellers can also receive responses in their preferred language and unit system. Example prompt: GET /{token}/{longitude},{latitude}/weather.json with lang=en_US and unit=metric for the destination coordinates. ### AI Agent Weather Lookup via Jentic Through Jentic, an AI agent searches for an intent like 'get the current weather' and is returned the ColorfulClouds realtime operation along with its input schema. The agent fills in coordinates and executes, all without holding the raw token in its context. Wiring up takes under 30 minutes versus a few hours of direct integration to handle the unusual path-token auth. Example prompt: Use Jentic search for 'get the current weather', load the realtime.json schema, and execute it with the user's longitude and latitude. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/{token}/{longitude},{latitude}/realtime.json` | Real-time weather at a coordinate | | GET | `/{token}/{longitude},{latitude}/minutely.json` | Minute-by-minute precipitation nowcast | | GET | `/{token}/{longitude},{latitude}/hourly.json` | 24-hour hourly forecast | | GET | `/{token}/{longitude},{latitude}/daily.json` | Multi-day daily forecast | | GET | `/{token}/{longitude},{latitude}/weather.json` | Unified realtime, hourly, and daily aggregate | ## Key resources - **Realtime** — Current weather conditions at a coordinate. - **Minutely** — Minute-by-minute precipitation nowcast for the next two hours. - **Hourly** — 24-hour hourly forecast at a coordinate. - **Daily** — Multi-day daily forecast at a coordinate. - **Weather** — Unified aggregate combining realtime, hourly, and daily data in one response. ## Why Jentic - **Setup:** Wiring the ColorfulClouds Weather API by hand means embedding your token as a segment of the request URL and assembling the longitude and latitude path for each realtime or forecast call. Through Jentic you install once, import ColorfulClouds from the API Directory, store the token once, and your agent calls it. - **Permission scoping:** ColorfulClouds selects each request by the forecast path such as realtime.json or hourly.json rather than a resource id you own, so scoping stays at the operation level: you limit the agent to the read operations it needs, such as realtime conditions or the minutely rain forecast, and leave the others out unless you add them. - **Credential handling:** Your ColorfulClouds token is stored once, encrypted, by your own Jentic One instance and inserted into the request path only at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'get the current weather at a coordinate' or 'check for rain in the next hour', and Jentic returns the matching ColorfulClouds operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Bytescout API** — Bytescout handles document and barcode processing while ColorfulClouds delivers weather data - combine to embed weather snapshots in PDF reports. - **Caller API** — Caller API enriches phone numbers; pair with ColorfulClouds for SMS weather alerts where the recipient list needs validation. - **Calm API** — Calm delivers wellness content, not weather data - listed only for agents comparing third-party content APIs. ## FAQ ### Why is there no official OpenAPI spec for the ColorfulClouds Weather API? ColorfulClouds documents the API on open.caiyunapp.com but does not publish a downloadable OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call ColorfulClouds Weather API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the ColorfulClouds Weather API use? The API uses an API token passed as part of the URL path rather than a header - the token sits between the version and the coordinate segment, for example `/v2.5/{token}/{longitude}`,{latitude}/realtime.json. Through Jentic, the token is stored encrypted in the credential vault and substituted into the path at execution time. ### Can I get a precipitation nowcast for the next two hours? Yes. Call /{token}/{longitude},{latitude}/minutely.json to receive a minute-by-minute precipitation forecast covering the next two hours. ColorfulClouds is particularly known for nowcast accuracy in China, with global coverage at coarser granularity. ### What are the rate limits for the ColorfulClouds Weather API? Rate limits are not declared in the OpenAPI specification and are tied to the subscription tier rather than published per-endpoint. For high-volume agent workloads contact ColorfulClouds for the limits applied to your token before scheduling sweeps. ### How do I get the current weather through Jentic? Run a Jentic search for 'get the current weather', load the schema for the realtime.json operation, and execute it with the longitude and latitude. Install the SDK with pip install jentic and use the async search, load, and execute pattern. ### Is the ColorfulClouds Weather API free? ColorfulClouds offers free tokens with a daily call quota and paid plans for higher throughput and additional fields. Pricing is set by ColorfulClouds and is not declared in the OpenAPI spec - refer to open.caiyunapp.com for current tiers. ### Can I limit what my agent is allowed to do with the ColorfulClouds Weather API? Yes. Because you run Jentic One yourself, your own rules decide which ColorfulClouds operations and credentials the agent may use. Since the API picks each request by its forecast path rather than a resource you own, scoping stays at the operation level: you can allow only the read calls the agent needs, such as realtime.json for current conditions or minutely.json for the two-hour rain nowcast, and leave hourly.json, daily.json, or the weather.json aggregate out unless you add them. Your token is inserted into the request path only at execution time, so the agent can call exactly the operations you permit and nothing else.