图层产品快速开始

图层产品可直接加载到 WebGIS 可视化大屏，适用于天气图层展示、点位取值和业务态势看板。

效果预览：

如果预览未正常加载，可直接访问： https://mirror-earth.com/meteo_maps/

在开始之前，我们需要有几个概念：

• 模型(model)：图层数据来源，例如美国GFS，欧洲ECMWF
• 要素(element)：气象数据要素，例如 温度、湿度、风速等
• 层级(level)：有些气象数据要素包含多个层级，比如温度有常用的2m气温，还有高空气温，等压面层例如500hPa气温。有些参数只有默认层级，就不用这个参数了，例如降雨量、气压等。 本接口获取图层数据的参数都是 mdoel/element_level

1. 两种加载方式

1. 图片渲染 + 点击取值接口
2. WebGL 渲染

使用建议:

• WebGL 渲染: 无需额外点击取值接口，渲染效率高、视觉效果好，适合动态叠加和大屏展示。
• 图片渲染: 接入门槛低、上线快，适合快速集成。

2. 要素支持矩阵

3. 支持模型

4. 要素与模型支持

4.1 公共气压层级

支持的气压层如下：

1000hPa, 950hPa, 925hPa, 900hPa, 850hPa, 800hPa, 700hPa, 600hPa, 500hPa, 400hPa, 300hPa, 250hPa, 200hPa, 150hPa

说明：只有配置了气压层的要素才可传入上述层级；未配置的要素无需传层级参数。

4.2 要素参数

接入建议：

• 温度、湿度、风速在传参时可以指定高度层或气压层。
• 降水、气压、辐射、云量、雷达、卫星云图不需要传层级参数。
• 未单独配置覆盖范围的要素，默认按全球范围处理。

4.3 模型参数

补充说明：

• 雷达（composite_reflectivity）和卫星云图（himawari）已定义为独立图层要素，但不在 ECMWF、GFS、HRES 这三个数值模式的支持列表中。
• 如果业务侧需要传层级参数，优先判断当前要素是否支持气压层，避免传入无效参数。

5. 接入流程

建议按以下顺序接入：先获取可用时间，再根据展示方式选择图片接入或 WebGL 接入。

5.1 获取 apikey

调用接口前，需要先获取平台分配的 apikey。后续所有请求都需要携带该参数。

5.2 查询图层可用时间

在加载图层前，建议先调用元数据接口获取当前模型或图层的可用时间列表。

接口格式：

https://api.mirror-earth.com/api/vis/{model}/meta?apikey={apikey}&timezone=Asia/Shanghai

参数说明：

• model：模型名称，例如 hres、ecmwf、archive_gfs、radar、himawari
• apikey：平台分配的访问凭证
• timezone：返回时间的时区；不传时默认返回 UTC 时间，建议国内业务统一传 Asia/Shanghai

示例：获取卫星云图最新时间列表

https://api.mirror-earth.com/api/vis/himawari/meta?apikey={apikey}&timezone=Asia/Shanghai

返回示例：

{
    "data": [
        "202604020810",
        "202604020820",
        "202604020830",
        "202604020840",
        "202604020850"
    ]
}

说明：

• 返回结果中的 data 为当前图层可用时间列表。
• 建议优先使用列表中的最新时间作为图层加载时间。

5.3 组织 element 参数

图层请求中的 element 通常由“要素参数名 + 层级”拼接而成。

常见示例：

• 温度 2 米层：temperature_2m
• 湿度 2 米层：relative_humidity_2m
• 风速 10 米层：wind_10m
• 风速 100 米层：wind_100m
• 温度 850hPa：temperature_850hPa
• 风速 500hPa：wind_500hPa

对于不支持层级的要素，直接使用要素参数名即可；如果实际接入中平台提供的是固定别名，请以业务接口约定为准。

5.4 图片接入

适用于直接在地图上叠加图片图层的场景，返回结果可直接作为图片资源使用。

接口格式：

https://api.mirror-earth.com/api/vis/part/{model}/{element}/{time}.webp?apikey={apikey}&timezone=Asia/Shanghai

示例：获取 HRES 风速 10 米层图片

https://api.mirror-earth.com/api/vis/part/hres/wind_10m/202604030300.webp?apikey={apikey}&timezone=Asia/Shanghai

适用场景：

• 快速接入地图图片图层
• 不需要自定义 WebGL 解码与渲染
• 雷达、卫星云图等可直接贴图展示的场景

5.5 WebGL 接入

适用于需要高性能渲染、动态调色、交互取值或大屏展示的场景。

接口格式：

https://api.mirror-earth.com/api/vis/{model}/{element}/{time}.jpeg?size=2048&apikey={apikey}&timezone=Asia/Shanghai

参数补充：

• size：返回图像尺寸，常用值为 2048

示例：获取 ECMWF 温度 2 米层 WebGL 数据

https://api.mirror-earth.com/api/vis/ecmwf/temperature_2m/202604030900.jpeg?size=2048&apikey={apikey}&timezone=Asia/Shanghai

此数据需要webgl解析才能还原出图像

说明：

• 雷达和卫星云图返回结果可直接作为地图图片使用。
• 其它数值模式返回的是编码后的栅格数据，需要通过 WebGL 解码后再渲染。
• WebGL 具体加载方式请参考下一节。

5.6 推荐接入顺序

1. 获取 apikey。
2. 调用 meta 接口获取可用时间列表。
3. 根据业务场景确定 model、element、time。
4. 如果是快速展示或图片叠加，优先使用图片接口。
5. 如果是动态渲染、交互分析或大屏展示，使用 WebGL 接口。

5.7 接入注意事项

• timezone 不传时，默认返回 UTC 时间；国内项目建议统一传 Asia/Shanghai。
• 只有温度、湿度、风速支持高度层或气压层，其它要素不要传层级参数。
• HRES 覆盖中国区域，ECMWF 和 GFS 覆盖全球；雷达和卫星云图使用各自独立覆盖范围。
• 在正式加载图层前，建议始终先查询一次 meta 接口，避免请求到无效时间。