API Reference

Spec v1.0 · Service rolling out

The HTTP API below is the interface specification. Field names, units and accumulation conventions are identical to the CSV data specification. CSV delivery is the primary channel today; the HTTP service opens progressively per customer onboarding — please confirm the delivery method with sales.

General Conventions

• Responses use a unified { code, message, data } structure; code = 0 means success;
• Time parameters are Beijing-time ISO 8601 (with offset); the issue time (issue) is UTC;
• Field units match the CSV specification (K, Pa, J/m² accumulated); conversions are the caller's responsibility (see Usage Notes).

Endpoints

Method	Path	Description
GET	/api/v1/farms	Site list (farm_id, coordinates)
GET	/api/v1/forecast/issues	Available model-run (issue) list
GET	/api/v1/forecast	Query forecast data (main endpoint)

Query Forecast Data

GET /api/v1/forecast

Request Parameters

Param	Type	Required	Description
farm_id	string	one of farm_id / coords	Site ID, e.g. HuaR_093
lon	decimal	one of farm_id / coords	Longitude; must be provided together with lat
lat	decimal	one of farm_id / coords	Latitude
issue	string	no	Issue time (UTC, yyyyMMddHH); defaults to the latest run
start	string	no	Start valid time (Beijing time, ISO 8601); defaults to +0h
end	string	no	End valid time; defaults to +360h
elements	string[]	no	Field subset; defaults to all 15 data fields
page / size	int	no	Pagination; default size = 96 (one day)

Request Example

curl "http://api.example.com/api/v1/forecast
     ?farm_id=HuaR_093
     &start=2026-08-27T20:00:00
     &end=2026-08-28T20:00:00
     &elements=t2m,spd100,tr"

Response Example (HTTP 200)

{
  "code": 0,
  "message": "ok",
  "data": {
    "farm_id": "HuaR_093",
    "lat": 36.35208,
    "lon": 102.95839,
    "issue_time_utc": "2026-08-27T12:00:00Z",
    "timezone": "UTC+8",
    "resolution_minutes": 15,
    "total": 96,
    "items": [
      {
        "date_time": "2026-08-27T20:00:00+08:00",
        "t2m": 289.08,
        "spd100": 2.83,
        "tr": 0.0
      }
    ]
  }
}

Error Codes

HTTP	code	Description
400	40001	Missing or malformed parameter
404	40401	farm_id or issue time not found
422	42201	Coordinates out of service range
500	50000	Internal server error