OpenWeather API

The OpenWeather API for CWC provides comprehensive access to weather data, including current conditions, forecasts, air quality indices, and map tiles. This guide will help you get started with integrating our weather data into your applications.

Authentication

All API requests require the use of an API key (appid). You can obtain an API key by enrolling Caner Developer. Ensure to pass your API key as a query parameter in each request.

Example request with an API key:

https://api.cwc.caner.hk/app/owm?appid=YOUR_API_KEY

API Endpoints

Current Weather

Retrieve current weather conditions for a specified location.

Endpoint: /app/owm/?data=3.0&type=current
HTTP Method: GET
Required Parameters:
lat (float): Latitude of the location.
lon (float): Longitude of the location.
Optional Parameters:
units (string): Measurement units. Options: metric, imperial. Defaults to metric.
lang (string): Response language. Defaults to zh_CN.
Example

To fetch the current weather for a specific location, specify the lat (latitude) and lon (longitude) parameters. Optionally, you can include units and lang parameters to customize the response.

GET /app/owm/?data=3.0&type=current&lat=40.712776&lon=-74.005974&units=metric&lang=en&appid=YOUR_API_KEY

Weather Forecast

Get weather forecasts for a specified location.

Endpoint: /app/owm/?data=2.5&type=forecast
HTTP Method: GET
Required Parameters:
lat (float): Latitude of the location.
lon (float): Longitude of the location.
Optional Parameters:
cnt (integer): Number of time points to return in the forecast.
units, lang: Same as in Current Weather.
Example

For weather forecasts, the process is similar, but you can also specify the cnt parameter to control the number of forecasted data points returned.

GET /app/owm/?data=2.5&type=forecast&lat=40.712776&lon=-74.005974&units=metric&lang=en&cnt=5&appid=YOUR_API_KEY

Weather Map Tiles

Access weather map tiles for layer-based representations.

Endpoint: /app/owm/?data=2.5&type=map
HTTP Method: GET
Parameters:
layer (string): Type of map layer (e.g., clouds_new).
z (integer): Map zoom level.
x, y (integer): Tile coordinates.
Example

Requesting map tiles requires specifying the type of map layer, as well as the z (zoom), x, and y (tile coordinates) parameters.

GET /app/owm/?data=2.5&type=map&layer=clouds_new&z=1&x=0&y=0&appid=YOUR_API_KEY

Air Quality Index (AQI)

Fetch air quality data for current conditions, forecasts, or historical data.

Endpoint: /app/owm/?data=2.5&type=aqi&genre=[now|forecast|history]
HTTP Method: GET
Required Parameters:
lat, lon: Same as in Current Weather.
Additional Parameters for history:
start, end (Unix timestamps): Start and end times for historical data.
Example

To access air quality data, use the aqi type and specify whether you're interested in current (now), forecasted (forecast), or historical (history) data. For historical data, also include start and end Unix timestamps.

GET /app/owm/?data=2.5&type=aqi&genre=now&lat=40.712776&lon=-74.005974&appid=YOUR_API_KEY

GET /app/owm/?data=2.5&type=aqi&genre=history&lat=40.712776&lon=-74.005974&start=1385856000&end=1385942400&appid=YOUR_API_KEY

Icons

Retrieve weather condition icons.

Endpoint: /app/owm/?data=img
HTTP Method: GET
Parameters:
icon (string): Icon code.
res (string): Icon resolution, defaults to 2x.
Example

Fetch weather icons by specifying the icon code and desired resolution (res).

GET /app/owm/?data=img&icon=10d&res=2x

Error Handling

The API uses standard HTTP response codes to indicate the success or failure of a request. In the case of an error, the response will include a JSON object with more details.

400 Bad Request: The request cannot be processed due to malformed syntax.
401 Unauthorized: Missing or invalid API key. Make sure you have configured 2FA in your client.
404 Not Found: The requested resource does not exist.
500 Internal Server Error: An unexpected error occurred on the server.