乐于分享
好东西不私藏

海天气象开发文档 V2.1.3

海天气象开发文档 V2.1.3

海天气象(https://cornicelli.net/)是一个致力于为涉气象领域科学研究和技术应用提供统一规范、精准精细、高质高效的气象数据资源支持的数据信息服务平台,着力解决气象数据资源获取、存储、开发、应用等环节的一系列瓶颈难题,目前已发布全国市区县天气预报数据集、历史天气数据集、气象决策服务可视化图表、城市地理信息数据库、气象数据Python SDK等数据资源和服务应用资源。用户可以通过海天气象数据信息服务平台以极简优雅的方式一站式获取丰富的气象数据资源。

一、账户管理

1.账户注册

匿名用户可以点击右上角头像按钮,选择注册新账户跳转到账户注册页面,填写以下信息:

  • 昵称:在个人账户页面和社区论坛页面显示的公开称呼
  • 邮箱地址:常用邮箱,身份唯一识别,可用于重置密码和接收通知消息
  • 登录密码:自定义字符串

填写以上信息后会系统会自动注册用户并登录跳转到站点首页。可以点击右上角个人头像选择个人中心选项,浏览邮箱、电话、城市、API_KEY等账户信息,点击头像用户设置按钮可跳转到设置界面更改个人信息,可修改登录密码。

2.账户登录

匿名用户可以点击右上角头像按钮,选择登录已有账户跳转到账户登录页面,输入以下信息:

  • 邮箱地址
  • 登录密码

点击登录按钮即可登录账户,登录状态默认保持10天。站点大部分功能均需要登录状态下方能使用。

3.密码重置

匿名用户可以点击右上角头像按钮,选择登录已有账户跳转到账户登录页面,点击忘记密码按钮,即可跳转到密码重置页面,输入注册邮箱后,点击重置密码按钮,系统会将重置的新密码发送到注册邮箱,用户使用新密码登录后可以在用户设置页面重新修改密码。

4.账户升级

用户注册后为普通用户,可通过订阅的方式升级为高级用户和专业用户。点击导航栏订阅按钮跳转到订阅页面,选择合适的订阅计划,点击订阅此计划,选择升级用户类型(高级用户、专业用户)和时长(按月、按年),即可完成订阅。订阅后高级用户或专业用户后账户会自动升级,也可通过第三方平台完成订阅(需等待人工升级账户)。
不同等级的用户权限有所区别,具体对照表如下:

权限列表
普通用户
高级用户
专业用户
年付专业用户
管理使用个人账户
浏览城市预报摘要
查看天气预报图集
下载测试数据
注册使用论坛
下载全国市区县天气预报数据
×
下载高清气象决策可视化图表
×
下载全国市区县历史天气数据
×
×
历史/预报数据API在线调取
×
×
预报数据自动推送
×
×
本地化服务部署
×
×
全过程开发技术支持
×
×
全国市区县历史天气数据打包下载
×
×
×

注意:访问全国市区县历史天气数据需要专业用户

二、数据资源清单和详细说明

数据资源分为数据集和图片资源,数据集主要包括全国市区县未来10日逐小时天气预报和2000~2025年全国市区县逐小时历史天气数据,图片资源包括使用以上数据绘制的高清图片。
所有数据均提供免费测试数据,测试数据格式与所有可下载数据格式相同,用户可以先下载测试数据确认气象要素种类、空间分辨率、时间分辨率和其他细节信息之后,再下载需要的数据处理使用。

1.数据资源清单

截止目前V2.1.3版本,共有以下9项数据资源提供下载服务:

  1. 全国市区县未来10日逐小时天气预报数据集
  2. 全国0.1°网格未来10日逐小时天气预报数据集
  3. 全国市区县2000年至今逐小时历史天气数据集
  4. 全国市区县2000年至今逐日统计分析历史天气数据集
  5. 全国市区县2000年至今逐月统计分析历史天气数据集
  6. 全国市区县2000年至今逐年统计分析历史天气数据集
  7. 全国市区县经纬度坐标海拔数据集
  8. 全国城市未来7日天气预报图集
  9. 全国省会城市未来7日天气预报图集

2.数据资源详细参数

以上9项数据资源详细参数和对比如下:

数据名称
空间分辨率
地点数量
气象要素种类
格式
获取权限
下载链接
全国市区县未来10日逐小时天气预报数据集
县以上行政区
3191
32
CSV
高级用户
点击前往
全国0.1°网格未来10日逐小时天气预报数据集
0.1°(10千米)
0.1°网格
32
netCDF
专业用户
点击前往
全国市区县2000年至今逐小时历史天气数据集
县以上行政区
3191
40
CSV、Parquet
专业用户
点击前往
全国市区县2000年至今逐日统计分析历史天气数据集
县以上行政区
3191
40
CSV、Parquet
专业用户
点击前往
全国市区县2000年至今逐月统计分析历史天气数据集
县以上行政区
3191
40
CSV、Parquet
专业用户
点击前往
全国市区县2000年至今逐年统计分析历史天气数据集
县以上行政区
3191
40
CSV、Parquet
专业用户
点击前往
全国市区县经纬度坐标海拔数据集
县以上行政区
3191
0
CSV
普通用户
点击前往
全国城市未来7日天气预报图集
市以上行政区
371
32
PNG、SVG
高级用户
点击前往
全国省会城市未来7日天气预报图集
省会城市、首府
34
32
PNG、SVG
高级用户
点击前往

以上数据中,全国市区县天气预报数据(大小约52 MB)打包批量下载格式为CSV,全国城市历史天气数据(大小约7 GB)打包批量下载格式为CSV,全国市区县历史天气数据(大小约21 GB)和统计分析历史天气数据(大小不超过1.7 GB)打包批量下载格式为Parquet。提供Parquet格式是为了节省存储空间,这种格式是大数据专用的列式存储格式,具有读取快、处理灵活、占用空间小的特点,可以用专用的读取软件打开查看,也可以通过几行简单的代码转换为CSV格式:

pip install pandas pyarrow # 首先安装Pandas和Pyarrow库

import pandas as pd

csv_file = 'data.csv'
parquet_file = 'data.parquet'

df = pd.read_csv(csv_path)
df.to_parquet(parquet_path, engine='pyarrow', compression='snappy')  # CSV转Parquet

df = pd.read_parquet(parquet_path)  # Parquet转CSV
df.to_csv(csv_path, index=False)

3.气象要素分类

天气预报数据和历史天气数据共分为气温、气压、相对湿度、风、降水量、云、能见度、天气现象等13大类,其中天气预报数据一共有32种,历史天气数据一共有40种,覆盖了科研领域的绝大多数地面气象数据使用场景。

4.气象数据定义、单位和详细说明

用户下载CSV格式数据后,第一行为数据列名,可通过查找下表迅速找到对应的气象要素名称和定义:

字段名
物理名称
单位
定义和描述
date
时间
数据的时间标记。默认采用UTC+8时间(北京时间)。
temperature_2m
气温
距地面2米高度的气温。
relative_humidity_2m
相对湿度
%
距地面2米高度的空气相对湿度。
dew_point_2m
露点温度
距地面2米高度的空气露点温度。
apparent_temperature
体感温度
指将人体所感受到的冷暖程度,转换成同等之温度。体感温度会受到气温、风速与相对湿度的综合影响。
precipitation
降水量
mm
一定时间内,降落到水平面上,假如无渗漏,不流失,也不蒸发,累积起来的水的深度。
rain
降水量
mm
大尺度天气系统所引发的降水量。
showers
降水量
mm
中小尺度对流天气系统所引发的降水量。
snowfall
降雪量
cm
一定持续时间(1小时)内累积降雪的深度。大约为降水量的7倍。
snow_depth
雪深
m
当前时刻地面积雪深度。
weather_code
天气现象
WMO定义的天气现象代码(详见下文)。
pressure_msl
海平面气压
hPa
温度15摄氏度条件下,由本站气压推算到平均海平面上的气压值。
surface_pressure
气压
hPa
本站气压或场面气压,地表气压值。
cloud_cover
总云量
%
天空高、中、低云覆盖率。
cloud_cover_low
低云量
%
天空低云覆盖率。
cloud_cover_mid
中云量
%
天空中云覆盖率。
cloud_cover_high
高云量
%
天空高云覆盖率。
visibility
能见度
m
地面水平可视距离。
dew_point_2m
露点温度
距地面2米高度的空气露点温度。
et0_fao_evapotranspiration
蒸发量
mm
持续时间内(1小时内)地表蒸发的水量。
vapour_pressure_deficit
水汽压差
kPa
饱和水汽压与实际水汽压差值。
wind_speed_10m
平均风速
m/s
地面10米高度平均风速。
wind_direction_10m
风向
°
地面10米高度风向。
wind_gusts_10m
阵风风速
m/s
地面10米高度阵风风速。
surface_temperature
地表温度
地面温度,即地温。
soil_moisture_0_to_10cm
土壤温度
地下0~10厘米厚度层平均温度。
cape
对流有效位能
J/kg
CAPE,评估垂直大气是否稳定、对流是否容易发展的指标之一。
lifted_index
抬升指数
LI,自由对流高度以上不稳定能量大小的指数。
convective_inhibition
对流抑制能
J/kg
CIN,阻止气块自地面上升至自由对流高度的能量大小。
shortwave_radiation_instant
短波辐射
W/m²
波长短于3μm的太阳辐射。
direct_radiation_instant
直接短波辐射
W/m²
未被大气阻挡而能够直达到地面的太阳短波辐射。
diffuse_radiation_instant
散射辐射
W/m²
太阳光经大气层中的空气分子、云滴和气溶胶的散射作用(天空散射)以及地表漫反射(地面散射)等形成的辐射。
direct_normal_irradiance_instant
直接辐射
W/m²
DNI,未被大气阻挡而能够直达到地面的辐射。
global_tilted_irradiance_instant
倾角辐射
W/m²
特定倾斜面上接收到的直接辐射(DNI)和散射辐射(DHI)之和。
terrestrial_radiation_instant
地面辐射
W/m²
短波辐射和长波辐射之和,由地球本身的辐射和太阳辐照后的反射组成的辐射。

在统计分析历史天气数据中,以上气象要素名称后缀会加上_max_min、_mean、_sum_average,分别代表对应时间尺度的对应气象要素的最大值、最小值、平均值、累积值和均值,其中 _average是平均风向特有的后缀。

三、数据资源获取方式

主要提供以下3种数据资源获取方式:

  • 网页端直接下载
  • 使用在线API调取
  • 使用Python SDK获取数据(HtMeteo超级气象信息体)

如果是高密度数据使用场景,推荐使用第三种方式,功能更强大,集成度高,接口规范统一。

1.网页端直接下载

各数据集下载链接如下:

  • 天气预报数据集(https://cornicelli.net/meteo/data/forecast)
  • 历史天气数据集(https://cornicelli.net/meteo/data/history/)
  • 统计分析历史天气数据集(https://cornicelli.net/meteo/data/history_analysis/)
  • 全国城市未来7日天气预报图集(https://cornicelli.net/meteo/gallery/forecast/china/24)
  • 省会城市未来7日天气预报图集(https://cornicelli.net/meteo/gallery/forecast/city/北京市)
  • 全国市区县经纬度坐标海拔数据集(https://cornicelli.net/meteo/doc)

1.1下载天气预报数据

直接在数据下载页面选择对应日期的天气预报数据下载即可。下载的天气预报数据为当日全国3191个市区县的未来240小时逐小时天气预报数据,包含32种气象要素,打包为单独zip压缩文件,解压后即可得到所有地点的CSV格式天气预报数据。
过期的天气预报数据10日后会自动清除,可以选择往日天气预报数据下载。最新的天气预报数据当日凌晨4时前会更新完毕,在此之前不可下载。

1.2下载历史天气数据

历史天气数据包括逐小时历史天气数据和逐日逐月逐年统计分析历史天气数据,它们的下载方式相同。
用户在数据列表页面点击右上角查找城市查找区县按钮,选择需要下载数据的地点,即可跳转到对应地点的历史天气数据列表,再找到需要的年份,点击右侧下载数据按钮即可将CSV格式历史天气数据下载到本地。
其中逐小时历史天气数据按照年份分类存放,可以分别单独下载,逐日、逐月、逐年统计分析历史天气数据2000~2025年的全部数据都存放在一个CSV文件内,可以一次性下载全部。

查找城市

选择对应年份

进入数据下载页面

跳转城市数据列表

下载数据

CSV格式数据

1.3下载图片资源

用户点击天气预报图集链接后进入图片下载界面,天气预报图分为全国城市省会城市2种,前者包含全国371个城市未来24小时天气预报详情,后者分别为各省会城市未来7日天气预报详情,具体细节可在对应网页查看。
全国城市未来7日天气预报图集按照预报时效分为7张,分别为未来1~7日全国城市天气预报图,点击右上角选择预报时效按钮即可跳转到对应日期的天气预报图,选择好日期后点击右上角下载高清位图下载高清矢量图按钮即可分别下载高清PNG格式和SVG格式图片。
省会城市未来7日天气预报图集按照省会城市名称分为32张(不含港澳),分别为各省会城市未来7天天气预报图,点击右上角选择城市即可跳转到对应省会城市的天气预报图,再点击右上角下载高清位图下载高清矢量图按钮即可分别下载高清PNG格式和SVG格式图片。

1.3下载全国市区县经纬度坐标海拔数据

点击链接跳转到开发文档页面即可下载。该数据包含全国3191个市区县的经纬度坐标和海拔高度。

2.使用在线API调取

API可以嵌入WEB应用或本地程序中灵活使用,是一种轻量化的数据获取方式,适用于小规模数据获取和本地存储资源受限的使用场景。所有API调取数据均需要提供26位API_KEY参数,可在个人中心查看用户账户对应的API_KEY。目前开放的API列表如下:

API名称
API参数
主要功能
返回数据说明
某日某地天气预报查询
城市名称、年、月、日、API Key
查询该地点选定日期未来10日逐小时气象预报数据
选定日期至未来10天内240个时次32种气象要素数据
某坐标最新天气预报查询
坐标经度、坐标纬度、API Key
查询该坐标地点最新未来10日逐小时气象预报数据
该坐标未来10天内240个时次32种气象要素数据
某日某地历史天气查询
城市名称、年、月、日、API Key
查询该地点选定日期逐小时历史气象数据
选定日期当日的24个时次40种气象要素历史数据
某月某地历史天气查询
城市名称、年、月、API Key
查询该地点选定月份逐小时历史气象数据
选定月份当月的720个时次40种气象要素历史数据
某年某地历史天气查询
城市名称、年、API Key
查询该地点选定年份逐小时历史气象数据
选定年份当年的8760个时次40种气象要素历史数据
坐标地名信息查询
坐标经度、坐标纬度、API Key
查询该坐标的关联地名信息
坐标最近的区县名称和所在省、市以及和最近区县的大圆距离
统计分析历史天气数据查询
地名、时间类型、API Key
查询该地点的年、月、日统计分析数据
该地点2000~2025年全部逐年、逐月、逐日统计分析数据

2.1使用API调取天气预报数据

共有以下2种天气预报数据调取方式:

  • 通过市区县地名调取
  • 通过经纬度坐标调取

通过地名调取时仅需提供地名和日期参数,可调取该地点未来240小时(10天)的逐小时天气预报数据,日期参数为当前日期,如果需要调取过去的历史天气预报数据,日期参数可变更为过去10天内的日期(更早的天气预报数据会自动清除)。
通过经纬度坐标调取天气预报数据时须指定坐标经纬度参数,如果不知道该坐标的地名可以使用坐标地名信息查询API查询地名信息。

2.2使用API调取历史天气数据

逐小时历史天气数据和逐日逐月逐年统计分析历史天气数据均可通过API调取。
为高效利用网络资源,调取逐小时历史天气数据可以分别用日、月、年3种时间尺度,数据量依次渐增,返回的都是逐小时历史天气数据。
调取统计分析历史天气数据时,也可以用日、月、年3种时间尺度,分别代表按日、按月、按年分别统计分析逐小时历史天气数据,返回的是逐日、逐月、逐年的统计分析历史天气数据(最大值、最小值、平均值、累积值等)。

2.3使用API查询经纬度关联地名信息

可以查询到对应经纬度对应的地名信息,用于在不知晓地名仅知晓经纬度的情况下快速查询地名,由于海天气象数据都由地名索引,故提供本API使用户能够快速获取地名信息。

2.4 API参考源代码

以上所有API的参考源代码如下:

import requests

# api主要提供以下6个接口,其中1个用于调取天气预报数据,4个用于调取历史天气数据,1个用于查询坐标信息
# 1.调取某日天气预报数据,时间跨度:选定日期起未来10日,共240小时(通过地名和坐标两种方式)
# 2.调取某日历史天气数据,时间跨度:选定日期的当日,共24小时
# 3.调取某月历史天气数据,时间跨度:选定年月的当月,共30日720小时
# 4.调取某年历史天气数据,时间跨度:选定年的当年,共12月365日8760小时
# 5.通过坐标查询地名信息
# 6.调取统计分析历史天气数据,全国市区县逐年、逐月、逐日的统计分析数据,包括均值、极值、累积值

# API Key可以在“个人中心”页面查看,所有用户都有API Key但是仅专业用户可以使用API功能,所有接口都需要API Key
api_key = "您的26位API Key"

# -------------------------------------1.调取某日天气预报数据----------------------------------------
# -------------------------------------1.1 通过地名和日期调取----------------------------------------
# 日期年月日参数,整型,须为近30日的日期
year, month, day = 2025926

# 地名参数,目前收录全国333个地级市,城市列表请在说明文档中下载查看(https://app.cornicelli.net/meteo/download/resource/cities_list.csv)
city_name = '西安市'

# 构造url,获取该城市该日期起,未来10日逐小时天气预报
forecast_daily_url = f"https://app.cornicelli.net/meteo/api/forecast/daily/{city_name}/{year}/{month}/{day}/{api_key}"
forecast_daily_data = requests.get(forecast_daily_url)
print(forecast_daily_data.text)

# -------------------------------------1.2 通过地理坐标调取----------------------------------------
# 地理坐标经纬度参数
lon, lat = 108.94050934.617382

# 构造url,获取该坐标未来10日逐小时天气预报,如果需要查询确认坐标地名信息,参考第5点
forecast_coords_url = f"https://app.cornicelli.net/meteo/api/forecast/daily_coords/{lon}/{lat}/{api_key}"
forecast_coords_data = requests.get(forecast_daily_url)
print(forecast_coords_data.text)

# -------------------------------------2.调取某日历史天气数据----------------------------------------
# 日期年月日参数,整型,须为2000年1月1日至今日之间的日期,历史天气数据更新有1个月左右的延迟,所以近1个月的数据可能无法调取
year, month, day = 2025326

# 地名参数,目前收录全国333个地级市,城市列表请在说明文档中下载查看(https://app.cornicelli.net/meteo/download/resource_cities_list.csv)
city_name = '南京市'

# 构造url,获取该城市该日期内24个时次的历史天气数据
history_daily_url = f"https://app.cornicelli.net/meteo/api/history/daily/{city_name}/{year}/{month}/{day}/{api_key}"
history_daily_data = requests.get(history_daily_url)
print(history_daily_data.text)

# -------------------------------------3.调取某月历史天气数据----------------------------------------
# 年月参数,整型,须为2000年1月至今日之间的月份,历史天气数据更新有1个月左右的延迟,所以近1个月的数据可能无法调取
year, month = 20253

# 地名参数,目前收录全国333个地级市,城市列表请在说明文档中下载查看(https://app.cornicelli.net/meteo/download/resource/cities_list.csv)
city_name = '成都市'

# 构造url,获取该城市该月份内720个时次的历史天气数据
history_monthly_url = f"https://app.cornicelli.net/meteo/api/history/monthly/{city_name}/{year}/{month}/{api_key}"
history_monthly_data = requests.get(history_monthly_url)
print(history_monthly_data.text)


# -------------------------------------4.调取某年历史天气数据----------------------------------------
# 年份参数,整型,须为2000年至今日之间的年份,历史天气数据更新有1个月左右的延迟,所以近1个月的数据可能无法调取
year = 2025

# 地名参数,目前收录全国333个地级市,城市列表请在说明文档中下载查看(https://app.cornicelli.net/meteo/download/resource/cities_list.csv)
city_name = '上海市'

# 构造url,获取该城市该年份内8760个时次的历史天气数据
history_yearly_url = f"https://app.cornicelli.net/meteo/api/history/yearly/{city_name}/{year}/{api_key}"
history_yearly_data = requests.get(history_yearly_url)
print(history_yearly_data.text)

# -------------------------------------5.通过经纬度坐标查询地名信息----------------------------------------
# 地理坐标经纬度参数
lon, lat = 108.94050934.617382

# 构造url,获取该坐标关联的地名信息
coords_info_url = f"https://app.cornicelli.net/meteo/api/gis/coords_location/{lon}/{lat}/{api_key}"
coords_info_data = requests.get(coords_info_url).json()
print(coords_info_data)

# -------------------------------------6.调取统计分析历史天气数据----------------------------------------

# 地名、时间类型参数,时间类型daily、monthly、yearly代表分别按日、月、年统计分析
city_name = '三原县'
time_type = 'daily'# 'daily' 'monthly' 'yearly' 三选一

# 构造url,获取该坐标关联的地名信息
history_analysis_url = f"https://app.cornicelli.net/meteo/api/history_analysis/{time_type}/{city_name}/{api_key}/"
history_analysis_data = requests.get(history_analysis_url).json()
print(history_analysis_data)

3.使用Python SDK获取数据

海天气象Python SDK也叫“HtMeteo超级气象信息体”可以在知乎和GitHub详细了解它的工作原理。它集成了海天气象数据信息服务平台的全部功能,能够实现账户管理、数据下载、API使用等全部功能。本文档只给出精简的使用说明介绍。Python SDK可以在下载资源列表下载。

3.1初始化HtMeteo

使用如下代码初始化它:

from HtMeteo import HtMeteo

h = HtMeteo(username='abc', password='123456')  # 指定海天气象用户名和密码
print(h.account_info)  # 查看账户信息
print(h.username, h.password, h.api_key, h.account_type, h.subscribe_days)  # 分别查看用户名、密码、api_key、用户类型、订阅时间

3.2 HtMeteo属性和方法列表

属性/方法名称
功能说明
1.账户管理属性
——————————————————
account_info
详细的海天气象账户信息
username
用户名
password
密码
account_type
账户类型
api_key
api_key
subscribe_days
订阅天数
session
连接会话
2.数据调取属性
——————————————————
location
当前设定地点
locations
地点列表
history_mode
历史天气数据模式
forecast_mode
天气预报数据模式
years
历史数据年份列表2000~2025
3.工作目录属性
——————————————————
work_dirs
全部工作目录列表
temp_data_path
缓存目录
hourly_history_meteo_data_path
逐小时统计分析数据目录
daily_history_meteo_data_path
逐日统计分析数据目录
monthly_history_meteo_data_path
逐月统计分析数据目录
yearly_history_meteo_data_path
逐年统计分析数据目录
forecast_data_path
预报数据目录
4.账户管理方法
——————————————————
login_account
登录海天账户
create_work_dirs
创建所有工作目录
set_forecast_mode
设定天气预报数据模式
set_history_mode
设定历史天气数据模式
set_location
设定地点
5.数据拉取方法
——————————————————
data_status_check()
数据完整性校验
fetch_data()
从云端拉取数据
fetch_locations_data()
拉取多个地点数据
fetch_all_latest_forecast_data()
拉取全国城市天气预报数据
6.历史天气数据调取方法
——————————————————
hourly_value()
调取某小时历史天气数据
daily_value()
调取某天统计分析历史天气数据
monthly_value()
调取某月统计分析历史天气数据
yearly_value()
调取某年统计分析历史天气数据
hourly_series()
调取起止小时时段统计分析历史天气数据
daily_series()
调取起止天时段统计分析历史天气数据
monthly_series()
调取起止月时段统计分析历史天气数据
yearly_series()
调取起止年时段年统计分析历史天气数据
7.天气预报数据调取方法
——————————————————
forecast_hourly_series()
调取未来10日逐小时天气预报数据
forecast_daily_series()
调取未来10日逐日统计分析天气预报数据
8.在线接口API使用
——————————————————
api_history_hourly_of_day()
仅查看某天的逐小时历史天气数据
api_history_hourly_of_month()
仅查看某月的逐小时历史天气数据
api_history_hourly_of_year()
仅查看某年的逐小时历史天气数据
api_history_analysis()
仅查看日、月、年统计分析历史天气数据
api_forecast_hourly()
仅查看某地点的逐小时天气预报数据
api_forecast_hourly_by_coords()
仅查看某坐标的逐小时天气预报数据
find_location_by_coords()
查询某坐标的地名信息
9.其他方法
——————————————————
clear_data_dir()
清空工作目录内的所有数据

3.3 HtMeteo参考示例代码

'''
海天气象HtMeteo超级信息体使用示例代码
海天气象HtMeteo超级信息体,是海天气象数据信息服务平台开发的,基于平台数据合集和在线API的Python程序库,它能够实现账户认证、气象数据下载、气象数据
统计分析、气象数据在线API调用等功能,将海天气象平台的所有数据资源和在线接口整合在了一个Python库中,因此形象被命名为“超级信息体”。
开发它的初衷是为了变革气象领域科研人员、应用人员、学生获取地面气象数据的方式,无论是历史天气数据还是天气预报数据,它能够最大限度减少气象数据用户在数据
查找、统计分析、整理订正、存储调取环节的时间耗费,一站式解决所有的科研任务和实践应用的数据准备问题,让用户不再受制于数据准备的羁绊,从而专注于对
气象数据的潜能开发和价值创造。
在线支持:
https://cornicelli.net/meteo/doc  
https://github.com/uniquezhiyuan/HtMeteo  
https://zhuanlan.zhihu.com/p/2014329618442789506
'''

import time

from HtMeteo import HtMeteo

# -------------------------基本参数-------------------------
location = '西安市'
# locations = ['北京市', '三原县', '喀什地区', '贡山独龙族怒族自治县', '海北藏族自治州']
meteo_types = ['temperature_2m_max',
'surface_pressure_mean',
'relative_humidity_2m_mean',
'wind_speed_10m_mean',
'precipitation_sum',
'shortwave_radiation_min']

target_year, target_month, target_day, target_hour = 201942018

start_year, start_month, start_day, start_hour = 2019122518
end_year, end_month, end_day, end_hour = 202032618

# -------------------------用户认证 示例代码-------------------------
# 初始化HtMeteo超级信息体
h = HtMeteo(username='htqx', password='C0rn!ce11!')  # 指定海天气象用户名和密码
# h = HtMeteo()  # 不指定用户名和密码,无法拉取在线数据,只能分析本地数据
# h.login_account()
print(h.account_info)  # 查看账户信息
print(h.username, h.password, h.api_key, h.account_type, h.subscribe_days)  # 分别查看用户名、密码、api_key、用户类型、订阅时间

# -------------------------历史天气数据统计分析 示例代码-------------------------
h = HtMeteo(username='htqx', password='C0rn!ce11!')  # 实例化超级信息体
h.set_location('西安市')  # 设定地点,会自动检测目录数据状态,如果数据缺失会自动从云端拉取,默认只拉区历史数据,如果需要预报数据需开启预报模式

# 1.获取单一时间历史气象数据,
# 读取西安市2019年4月20日18时历史气象数据,包含气象要素:2米气温、平均地面气压、平均2米相对湿度、10米平均风速、累积降水量和短波辐射
# 可以指定meteo_types参数改变气象要素类型,所有的历史气象要素列表在文档末尾,meteo_types是一个列表
# meteo_types = history_meteo_types_options  # 指定所有气象要素
h.hourly_value(meteo_types=meteo_types, year=target_year, month=target_month, day=target_day, hour=target_hour)
# 返回pandas series类型,可以通过气象要素名称索引
meteo_data = h.hourly_value(meteo_types=meteo_types, year=target_year, month=target_month, day=target_day,
                            hour=target_hour)
print(meteo_data['temperature_2m'])  # 输出2米气温数值
print(meteo_data.index)  # 查看所有索引

# 读取西安市2019年4月20日历史气象数据
h.daily_value(meteo_types=meteo_types, year=2019, month=4, day=20)

# 读取西安市2019年4月历史气象数据
h.monthly_value(meteo_types=meteo_types, year=2019, month=4)

# 读取西安市2019年历史气象数据
h.yearly_value(meteo_types=meteo_types, year=2019)

# 2.获取时间段内连续历史气象数据
# 读取西安市2019年12月31日0时至2020年1月1日23时历史气象数据
h.hourly_series(meteo_types=meteo_types,
                start_year=2019, start_month=12, start_day=31, start_hour=0,
                end_year=2020, end_month=1, end_day=1, end_hour=23)  # 起止时间都包含,可跨年读取
# 返回pandas dataframe,可以通过时间、气象要素名称索引
meteo_data = h.hourly_series(meteo_types=meteo_types,
                             start_year=2019, start_month=12, start_day=31, start_hour=0,
                             end_year=2020, end_month=1, end_day=1, end_hour=23)
print(meteo_data['temperature_2m'].iloc[0])  # 输出第一个2米气温数值
print(meteo_data['wind_speed_10m'].iloc[-5:].tolist())  # 输出最后5个10米平均风速数值,并转换为列表
print(meteo_data.index)  # 查看所有索引
print(meteo_data.columns)  # 查看所有列名

# 读取西安市2019年12月31日至2020年1月1日历史气象数据
h.daily_series(meteo_types=meteo_types,
               start_year=2019, start_month=12, start_day=31,
               end_year=2020, end_month=1, end_day=1)  # 起止时间都包含,可跨年读取

# 读取西安市2019年12月31日至2020年1月1日历史气象数据
h.monthly_series(meteo_types=meteo_types,
                 start_year=2019, start_month=12,
                 end_year=2020, end_month=1)  # 起止时间都包含,可跨年读取

# 读取西安市2019年至2025年历史气象数据
h.yearly_series(meteo_types=meteo_types,
                start_year=2019,
                end_year=2025)  # 起止时间都包含,可跨年读取

# -------------------------天气预报数据统计分析 示例代码-------------------------
# 3.读取预报数据
h.set_forecast_mode('on')  # 开启预报模式,预报模式默认为关闭,开启后方能使用预报数据读取功能,如果关闭不会下载天气预报数据
h.set_history_mode('off')  # 如果不使用历史数据,可以先关闭它,否则设定地点后,历史数据也会被自动下载,耗费时间
h.set_location('三原县')
# 读取三原县未来240小时逐小时天气预报原始数据
h.forecast_hourly_series()
meteo_data = h.forecast_daily_series()
print(meteo_data.columns)  # 查看所有气象要素名称

# 读取三原县未来10日逐日天气预报统计分析数据
h.forecast_daily_series()
meteo_data = h.forecast_daily_series()
print(meteo_data.columns)  # 查看所有气象要素名称

# 4.只想下载数据,或者关注的地点较多,想先下载完数据再读取处理以节省时间
locations = ['南京市''疏勒县''顺德区''大理白族自治州']
h.set_forecast_mode('on')  # 开启预报数据模式,若关闭则不会下载预报数据
h.set_history_mode('on')  # 开启历史数据模式,否则不会下载历史数据
# 如果不设定历史数据模式或者预报数据模式,则只下载历史数据,因为预报数据模式默认为关闭状态

# 批量下载多个地点的天气预报数据和历史天气数据
h.fetch_locations_data(locations)

# 5.批量下载全国3191个市区县预报数据3191
h.fetch_all_latest_forecast_data()

# 6.需要查询经纬度所在地名和海拔
lon, lat = 11640
h.find_location_by_coords(lon, lat)
location_name = h.find_location_by_coords(lon, lat)  # 将查询到的坐标地点名称赋值给location_name
# time.sleep(1000)

# -------------------------在线API 示例代码-------------------------
# 7.直接从API调取数据,不再下载数据到本地
h.set_forecast_mode('off')  # 关闭预报数据模式,不再从云端下载数据到本地,直接API调取
h.set_history_mode('off')  # 关闭历史数据模式,不再从云端下载数据到本地,直接API调取
# 通过地名调取未来10日逐小时天气预报数据
meteo_data = h.api_forecast_hourly()  # 从API直接调取西安市未来10日逐小时天气预报数据
print(meteo_data.index)  # 输出时间索引
print(meteo_data.columns)  # 输出气象要素列表

# 通过经纬度坐标调取未来10日逐小时天气预报数据
lon, lat = 11640
meteo_data = h.api_forecast_hourly_by_coords(lon, lat)  # 从API直接调取西安市未来10日逐小时天气预报数据
print(meteo_data.index)  # 输出时间索引
print(meteo_data.columns)  # 输出气象要素列表

# 调取某一天的逐小时历史天气数据
year, month, day = 2019420
meteo_data = h.api_history_hourly_of_day(year, month, day)  # 从API直接调取西安市2019年4月20日的逐小时历史天气数据
print(meteo_data.index)  # 输出时间索引
print(meteo_data.columns)  # 输出气象要素列表

# 调取某一月的逐小时历史天气数据
year, month = 20194
meteo_data = h.api_history_hourly_of_month(year, month)  # 从API直接调取西安市2019年4月的逐小时历史天气数据
print(meteo_data.index)  # 输出时间索引
print(meteo_data.columns)  # 输出气象要素列表

# 调取某一年的逐小时历史天气数据
year = 2019
meteo_data = h.api_history_hourly_of_year(year)  # 从API直接调取西安市2019年的逐小时历史天气数据
print(meteo_data.index)  # 输出时间索引
print(meteo_data.columns)  # 输出气象要素列表

# 调取2000~2025年全时段统计分析历史天气数据
time_type = 'monthly'# 'daily''monthly''yearly' 三选一,分别代表日、月、年尺度的统计分析数据
meteo_data = h.api_history_analysis(time_type)  # 从API直接调取西安市2000~2025年的月统计分析历史天气数据
print(meteo_data.index)  # 输出时间索引
print(meteo_data.columns)  # 输出气象要素列表


# 8.其他功能
# h.clear_work_dirs()  # 清空./data目录内的所有数据,重置工作目录,谨慎操作

# 9.注意事项
# 全国有大约30个区名重复,冠以所在市名称加以区分,全国市区县地名清单下载地址:https://cornicelli.net/meteo/doc

3.4 HtMeteo气象要素参数列表

历史气象数据中的可选气象要素参数列表:

history_meteo_types_options = [
'temperature_2m_min',
'temperature_2m_max',
'temperature_2m_mean',
'dew_point_2m_min',
'dew_point_2m_max',
'dew_point_2m_mean',
'pressure_msl_min',
'pressure_msl_max',
'pressure_msl_mean',
'surface_pressure_min',
'surface_pressure_max',
'surface_pressure_mean',
'relative_humidity_2m_min',
'relative_humidity_2m_max',
'relative_humidity_2m_mean',
'wind_speed_10m_min',
'wind_speed_10m_max',
'wind_speed_10m_mean',
'wind_gusts_10m_min',
'wind_gusts_10m_max',
'wind_gusts_10m_mean',
'wind_direction_10m_average',
'wind_speed_100m_min',
'wind_speed_100m_max',
'wind_speed_100m_mean',
'wind_direction_100m_average',
'precipitation_sum',
'weather_code_max',
'cloud_cover_min',
'cloud_cover_max',
'cloud_cover_mean',
'shortwave_radiation_min',
'shortwave_radiation_max',
'shortwave_radiation_mean',
'boundary_layer_height_min',
'boundary_layer_height_max',
'boundary_layer_height_mean',
'et0_fao_evapotranspiration_min',
'et0_fao_evapotranspiration_max',
'et0_fao_evapotranspiration_mean',
'vapour_pressure_deficit_min',
'vapour_pressure_deficit_max',
'vapour_pressure_deficit_mean',
'soil_temperature_7_to_28cm_min',
'soil_temperature_7_to_28cm_max',
'soil_temperature_7_to_28cm_mean',
'soil_temperature_28_to_100cm_min',
'soil_temperature_28_to_100cm_max',
'soil_temperature_28_to_100cm_mean',
'soil_temperature_100_to_255cm_min',
'soil_temperature_100_to_255cm_max',
'soil_temperature_100_to_255cm_mean',
'soil_moisture_7_to_28cm_min',
'soil_moisture_7_to_28cm_max',
'soil_moisture_7_to_28cm_mean',
'soil_moisture_28_to_100cm_min',
'soil_moisture_28_to_100cm_max',
'soil_moisture_28_to_100cm_mean',
'soil_moisture_100_to_255cm_min',
'soil_moisture_100_to_255cm_max',
'soil_moisture_100_to_255cm_mean',
'total_column_integrated_water_vapour_min',
'total_column_integrated_water_vapour_max',
'total_column_integrated_water_vapour_mean',
]

天气预报数据中的气象要素参数列表(日统计分析天气预报数据舍弃了一些用不着的气象要素):

forecast_meteo_types_options = [
'date',
'temperature_2m',
'relative_humidity_2m',
'dew_point_2m',
'apparent_temperature',
'precipitation',
'rain',
'snowfall',
'weather_code',
'pressure_msl',
'surface_pressure',
'cloud_cover',
'cloud_cover_low',
'cloud_cover_mid',
'cloud_cover_high',
'vapour_pressure_deficit',
'wind_speed_10m',
'wind_speed_100m',
'wind_direction_10m',
'wind_direction_100m',
'wind_gusts_10m',
'surface_temperature',
'soil_temperature_0_to_7cm',
'soil_moisture_0_to_7cm',
'soil_moisture_7_to_28cm',
'runoff',
'cape',
'total_column_integrated_water_vapour',
'shortwave_radiation_instant',
'direct_radiation_instant',
'diffuse_radiation_instant',
'direct_normal_irradiance_instant',
'global_tilted_irradiance_instant'
]

三、本地天气预报数据的自动更新

在大多数使用场景下都需要实现自动将每日最新的天气预报数据下载到本地的功能。海天气象提供2种方式将最新的天气预报数据打包下载到本地:

  • 使用Python脚本自动拉取最新天气预报数据
  • 使用Python SDK自动下载最新天气预报数据(推荐)

以上2种方式均需要配置本地计算机定时任务,时间务必设定在每日的凌晨4:00之后。

3.1 使用Python脚本自动拉取最新天气预报数据

脚本参考代码如下:

# 请勿使用爬虫爬取本站数据,本站是公益性质的气象数据共享平台,旨在为气象爱好者和从业者提供优质精细的数据信息服务,
# 仅通过低廉订阅费用和捐助维持运行,因此网络带宽和服务器计算资源负载十分有限,为了他人的正常使用请勿使用网络爬虫程序抓取本站数据。
'''
这是海天气象数据自动更新脚本,能够将“海天气象”天气预报信息服务网站的ECMWF、CMA数值天气预报数据同步到本地计算机,使用
本脚本前请确保您的账户已升级订阅海天气象“专业用户”,服务器端数据更新时间一般在每日凌晨04时(UTC+8),因此务必在此时
间之后运行本数据更新脚本。本脚本运行需要Python环境,并正确安装BeautifulSoup、requests等库,如果成功下载文件但无法打开
请检查登录用户名和密码是否正确。如需更多使用帮助请浏览 https://app.cornicelli.net/meteo/doc,或通过邮件与开发者取
得联系:cornicelli@outlook.com。
'''

import requests
from bs4 import BeautifulSoup
import datetime
import time

# -----------------------⬇请修改以下参数:本地数据存放目录、海天气象网站专业用户账号、密码⬇-----------------------
DATA_SAVE_DIR = "C:/Users/Administrator/Desktop/"# 本地计算机数据存放目录,更改时不要遗漏最后一个斜线字符
USER_NAME = "htqx@cornicelli.net"# 您的海天账户注册账号(邮箱),须先升级为高级用户或者专业用户
USER_PASSWORD = "htqx123456"# 您的登录密码
PROJECT_CODE = "cn"# 项目代号,默认cn无需更改
# ---------------------------------------⬆请修改以上参数⬆---------------------------------------

# 定义待下载数据文件名(以当前日期命名)
today = datetime.datetime.now().strftime("%Y-%m-%d")  # 定义当前日期,即下载最新数据
# some_day = "2024-05-01"  # 如需下载历史数据,请用该格式定义目标日期,历史数据留存留存时限为最近1个月,此前无数据
FILE_NAME_ECMWF = f"ecmwf_{PROJECT_CODE}_10_days_hourly_weather_forecast_csv_{today}.zip"# ECMWF预报模式数据文件名
DATA_URL_ECMWF = f"https://app.cornicelli.net/meteo/download/project/{PROJECT_CODE}/{FILE_NAME_ECMWF}"

print(f"正在通过 {USER_NAME} 登录海天气象...")
# 模拟人工登录网站,验证用户名和密码
login_url = "https://app.cornicelli.net/meteo/login"
session = requests.Session()
resp = session.get(login_url)
soup = BeautifulSoup(resp.text, 'html.parser')
csrf_token = soup.find('input', {'name':'csrfmiddlewaretoken'}).get('value')
login_data = {
'csrfmiddlewaretoken': csrf_token,
'user-email': USER_NAME,
"user-password": USER_PASSWORD
}
headers = {
'user-agent''Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36',
'referer''https://app.cornicelli.net/meteo/'
}
login_resp = session.post(login_url, data=login_data, headers=headers)

print(f"正在下载{today}数据...")
# 下载数据,数据文件会被保存在设定目录下
print(f"请勿关闭本窗口,预计需等待不超过26秒。")
ecmwf_data_file = session.get(f"{DATA_URL_ECMWF}")
withopen(DATA_SAVE_DIR + FILE_NAME_ECMWF, "wb"as f:
    f.write(ecmwf_data_file.content)

print(f"{FILE_NAME_ECMWF} 数据文件下载完成...")
print(f"所有数据下载完毕,请在 {DATA_SAVE_DIR} 目录查看。\n5秒后程序自动退出。")
time.sleep(5)

3.2 使用Python SDK自动下载最新天气预报数据

参考示例代码如下:

from HtMeteo import HtMeteo

# 初始化HtMeteo超级信息体
h = HtMeteo(username='abc', password='123456')  # 指定海天气象用户名和密码

# 批量下载全国3191个市区县预报数据3191
h.fetch_all_latest_forecast_data()

四、社区论坛使用

用户可通过社区论坛发帖提问的方式寻求帮助,所有注册用户均可发布问题和回答问题,在数据使用过程中遇到瓶颈也可在社区论坛交流,开发者会第一时间为每位用户解难帮困。
点击导航栏论坛按钮即可进入社区论坛,点击右上角搜索框可以实现问题快速搜索,点击发布新问题按钮可在论坛中插入新的话题。

五、常见问题

常见问题页面收录了用户使用过程中的一些常见问题,通过浏览FAQ页面可以解决用户的大多数问题,如果还没有解决就去社区论坛提问吧,或者邮箱联系开发者。

六、更新记录

可以在更新记录页面查看本站的所有历史版本更新记录。

本站文章均为手工撰写未经允许谢绝转载:夜雨聆风 » 海天气象开发文档 V2.1.3

猜你喜欢

  • 暂无文章
本站作品均采用知识共享署名-非商业性使用-相同方式共享 4.0进行许可,资源收集于网络仅供用于学习和交流,本站一切资源不代表本站立场,我们尊重软件和教程作者的版权,如有不妥请联系本站处理!

 沪ICP备2023009708号

© 2017-2026 夜雨聆风   | sitemap | 网站地图