跳到主要内容

气象预测API

域名​

https://weather-api.xm-opt.com

GET 查看气象预测-逐小时​

GET /v1/forecast 查看逐小时气象预测数据。

数据源：全球范围内的精度1km网格级多源融合天气预报

预报时长：

  • 提供未来15天的天气预报，每日08:00（东八区时间）新增未来第15天的预报。
  • 支持查询历史预报数据，最长可查询近3个月内的存档数据。
  • 查询示例：以5月30日8:00 之后为例，可查询的时间范围为3月15日至6月14日。（若您输入的时间段超过这个限制，系统将返回错误表示调用失败，可修改时间范围后重试。）

更新频率：每1小时更新未来时段预报数据

空间分辨率：1km*1km

时间分辨率：逐小时

请求参数​

--header apikey=您的API密钥（获取方式详见官网密钥管理）

名称位置类型必选说明
longitudequerynumber是经度，数值模式
latitudequerynumber是纬度，数值模式
start_datequerystring是开始日期
end_datequerystring是结束日期
timezonequerystring是时区
hourlyqueryarray[string]是逐小时预测属性列表
elevationquerynumber否海拔高度

返回示例

成功

{
  "latitude": 30.25,
  "longitude": 120.1875,
  "timezone": "Asia/Shanghai",
  "elevation": 5,
  "hourly_units": {
    "time": "iso8601",
    "temperature_2m": "°C",
    "relative_humidity_2m": "%"
  },
  "hourly": {
    "time": [
      "2024-04-16T00:00",
      "2024-04-16T01:00",
      ......
      "2024-04-16T23:00"
    ],
    "temperature_2m": [
      16.8,
      16.5,
      ......
      16.6
    ],
    "relative_humidity_2m": [
      97,
      98,
      ......
      99
    ]
  },
  "model"="v1"
}

请求有误

{
  "errors": [
    "invalid parameter: longitude must be a number"
  ]
}

返回结果​

状态码状态码含义说明数据模型
200OK成功Inline
400Bad Request请求有误Inline

返回数据结构​

状态码 400

名称类型必选约束中文名说明
» errors[string]truenonenone

若出现400的报错，有可能是因为您【选择的时间范围超过数据有效期】或【输入的参数错误】导致的，可将时间范围或参数修改正确后重试。

调用示例​

curl --location --request GET 'http://weather-api.xm-opt.com/v1/forecast?longitude=120.21&latitude=30.25&hourly=temperature_2m,relative_humidity_2m&start_date=2024-04-16&end_date=2024-04-16&timezone=Asia/Shanghai' \
--header 'apikey: 您的官网apikey' 

{"latitude":30.25,"longitude":120.1875,"utc_offset_seconds":28800,"timezone":"Asia/Shanghai","timezone_abbreviation":"CST","elevation":5.0,"hourly_units":{"time":"iso8601","temperature_2m":"°C","relative_humidity_2m":"%"},"hourly":{"time":["2024-04-16T00:00","2024-04-16T01:00","2024-04-16T02:00","2024-04-16T03:00","2024-04-16T04:00","2024-04-16T05:00","2024-04-16T06:00","2024-04-16T07:00","2024-04-16T08:00","2024-04-16T09:00","2024-04-16T10:00","2024-04-16T11:00","2024-04-16T12:00","2024-04-16T13:00","2024-04-16T14:00","2024-04-16T15:00","2024-04-16T16:00","2024-04-16T17:00","2024-04-16T18:00","2024-04-16T19:00","2024-04-16T20:00","2024-04-16T21:00","2024-04-16T22:00","2024-04-16T23:00"],"temperature_2m":[16.8,16.5,16.4,16.3,15.9,16.2,16.0,16.2,16.3,16.6,17.2,20.6,23.1,24.9,25.0,24.0,23.6,20.2,18.3,17.6,17.2,16.6,16.2,16.4],"relative_humidity_2m":[97,98,99,99,99,99,99,99,99,99,99,88,81,75,74,77,77,93,98,99,99,99,99,98]}}

逐小时预测属性列表​

::: temperature_2m,relative_humidity_2m,dew_point_2m,apparent_temperature,precipitation_probability,precipitation,rain,showers,snowfall,snow_depth,weather_code,pressure_msl,surface_pressure,cloud_cover,cloud_cover_low,cloud_cover_mid,cloud_cover_high,visibility,evapotranspiration,et0_fao_evapotranspiration,vapour_pressure_deficit,wind_speed_10m,wind_speed_80m,wind_speed_120m,wind_speed_180m,wind_direction_10m,wind_direction_80m,wind_direction_120m,wind_direction_180m,wind_gusts_10m,temperature_80m,temperature_120m,temperature_180m,soil_temperature_0cm,soil_temperature_6cm,soil_temperature_18cm,soil_temperature_54cm,soil_moisture_0_to_1cm,soil_moisture_1_to_3cm,soil_moisture_3_to_9cm,soil_moisture_9_to_27cm,soil_moisture_27_to_81cm,uv_index,uv_index_clear_sky,is_day,cape,freezing_level_height,sunshine_duration,shortwave_radiation,direct_radiation,diffuse_radiation,direct_normal_irradiance,global_tilted_irradiance,terrestrial_radiation,shortwave_radiation_instant,direct_radiation_instant,diffuse_radiation_instant,direct_normal_irradiance_instant,global_tilted_irradiance_instant,terrestrial_radiation_instant :::

详细说明见逐小时预测气象属性说明

GET 查询气象预测-逐15分钟​

GET /v1/forecast15Minutes 查看逐15分钟气象预测数据。

数据源：全球范围内的精度1km网格级多源融合天气预报。

预报时长：

  • 提供未来15天的天气预报，每日08:00（东八区时间）新增未来第15天的预报。
  • 支持查询历史预报数据，最长可查询近3个月内的存档数据。
  • 查询示例：以5月30日8:00 之后为例，可查询的时间范围为3月15日至6月14日。（若您输入的时间段超过这个限制，系统将返回错误表示调用失败，可修改时间范围后重试。）

更新频率：每1小时更新未来时段预报数据

空间分辨率：1km*1km

时间分辨率：逐15分钟

请求参数​

--header apikey=您的API密钥（获取方式详见官网密钥管理）

名称位置类型必选说明
longitudequerynumber是经度，数值模式
latitudequerynumber是纬度，数值模式
start_datequerystring是开始日期
end_datequerystring是结束日期
timezonequerystring是时区
minutely_15queryarray[string]是逐15分钟预测属性列表

返回示例

成功

{
  "latitude": 30.25,
  "longitude": 120.1875,
  "timezone": "Asia/Shanghai",
  "elevation": 5,
  "minutely_15_units": {
    "time": "iso8601",
    "temperature_2m": "°C",
    "relative_humidity_2m": "%"
  },
  "minutely_15": {
    "time": [
      "2024-04-17T00:00",
      "2024-04-17T00:15",
      ......
      "2024-04-17T23:45"
    ],
    "temperature_2m": [
      16.2,
      16.1,
      ......
      12.4
    ],
    "relative_humidity_2m": [
      98,
      98,
      ......
      91
    ]
  },
  "model":"v1"
}

请求有误

{
  "errors": [
    "invalid parameter: longitude must be a number"
  ]
}

返回结果​

状态码状态码含义说明数据模型
200OK成功Inline
400Bad Request请求有误Inline

返回数据结构​

状态码 400

名称类型必选约束中文名说明
» errors[string]truenonenone

若出现400的报错，有可能是因为您【选择的时间范围超过数据有效期】或【输入的参数错误】导致的，可将时间范围或参数修改正确后重试。

逐15分钟预测属性列表​

::: temperature_2m,relative_humidity_2m,dew_point_2m,apparent_temperature,precipitation,rain,snowfall,snow_depth,freezing_level_height,sunshine_duration,weather_code,wind_speed_10m,wind_speed_80m,wind_direction_10m,wind_direction_80m,wind_gusts_10m,visibility,cape,is_day,shortwave_radiation,direct_radiation,diffuse_radiation,direct_normal_irradiance,global_tilted_irradiance,terrestrial_radiation,shortwave_radiation_instant,direct_radiation_instant,diffuse_radiation_instant,direct_normal_irradiance_instant,global_tilted_irradiance_instant,terrestrial_radiation_instant :::

详细说明见逐15分钟预测气象属性说明

GET 查询气象预测-逐日​

GET /v1/forecastDaily 查看逐日气象预测数据。

数据源：全球范围内的精度1km网格级多源融合天气预报

预报时长：

  • 提供未来15天的天气预报，每日08:00（东八区时间）新增未来第15天的预报。
  • 支持查询历史预报数据，最长可查询近3个月内的存档数据。
  • 查询示例：以5月30日8:00 之后为例，可查询的时间范围为3月15日至6月14日。（若您输入的时间段超过这个限制，系统将返回错误表示调用失败，可修改时间范围后重试。）

更新频率：每1小时更新未来时段预报数据

空间分辨率：1km*1km

时间分辨率：逐日

请求参数​

--header apikey=您的API密钥（获取方式详见官网密钥管理）

名称位置类型必选说明
longitudequerynumber是经度，数值模式
latitudequerynumber是纬度，数值模式
start_datequerystring是开始日期
end_datequerystring是结束日期
timezonequerystring是时区
dailyqueryarray[string]是逐日预测属性列表

返回示例

成功

{
  "latitude": 30.25,
  "longitude": 120.1875,
  "timezone": "Asia/Shanghai",
  "elevation": 5,
  "daily_units": {
    "time": "iso8601",
    "temperature_2m_max": "°C"
  },
  "daily": {
    "time": [
      "2024-04-17"
    ],
    "temperature_2m_max": [
      16.2
    ]
  },
  "model":"v1"
}

请求有误

{
  "errors": [
    "invalid parameter: longitude must be a number"
  ]
}

返回结果​

状态码状态码含义说明数据模型
200OK成功Inline
400Bad Request请求有误Inline

返回数据结构​

状态码 400

名称类型必选约束中文名说明
» errors[string]truenonenone

若出现400的报错，有可能是因为您【选择的时间范围超过数据有效期】或【输入的参数错误】导致的，可将时间范围或参数修改正确后重试。

逐日预测属性列表​

::: weather_code,temperature_2m_max,temperature_2m_min,apparent_temperature_max,apparent_temperature_min,sunrise,sunset,daylight_duration,sunshine_duration,uv_index_max,uv_index_clear_sky_max,precipitation_sum,rain_sum,showers_sum,snowfall_sum,precipitation_hours,precipitation_probability_max,wind_speed_10m_max,wind_gusts_10m_max,wind_direction_10m_dominant,shortwave_radiation_sum,et0_fao_evapotranspiration :::

详细说明见逐日预测气象属性说明