NetCDF 格式返回

1.接口说明

接口路径： https://api.tjweather.com/nc/beta

当前版本： v1.0.0

请求方式： GET

返回类型： NetCDF

请求数据类型：

接口描述： 查询单点坐标最新的气象高精度预报数据，范围全球可选，预报时长可选，时间分辨率提供 15 分钟、1 小时选项，返回 NetCDF 格式数据流。

2.请求参数

参数名	说明	参数类型	默认值	必填	备注
key	您的私钥	字符串	无	是	暂时线下交付
loc	位置	字符串	无	是	支持全球范围任意经纬度查询，经度范围[-180,180]或[0,360]，纬度范围[-90,90]格式：经度在前纬度在后，按照“,“分隔，分隔符支持中文和英文。举例：116.23128,40.22077
t_res	时间分辨率	字符串	1h	否	支持查询时间分辨率为 15 分钟(格式：15min)、1 小时(格式：1h)的数据，缺省为 1h
fcst_days	预报天数	整数	3	否	支持选择未来 D 天的不同预报长度的预报数据，D>=0，支持总时长 5、10、15、30、45 天内数据
fcst_hours	预报小时数	整数	0	否	支持选择未来 H 小时的不同预报长度的预报数据，H>=0，缺省为 0
fields	要素	字符串	ws10m	否	支持要素请参照要素编码列表，缺省为10米风，按照“,“分隔，举例：ws100m,ws10m,t2m
tz	时区	整数	8	否	缺省为北京时，8，范围[-12,12]
grid	网格大小	字符串	1	否	1 表示 1*1 网格，缺省为:"1"，格点数据支持，"1","3","5","7"
download	是否下载	布尔	false	否	支持下载二进制 nc 文件，true 表示下载，缺省为 false
filename	下载文件名称	字符串	无	否	支持用户自定义下载文件名称，缺省为无，如未输入，则返回默认文件名称：lon{lon}-lat{lat}-days{fcst_days}-hours{fcst_hours}-grid{grid}-{yyyymmddhhmm}.nc

注：总预报时长按照 tot_hrs = fcst_days*24+fcst_hours 计算。

3.支持要素编码列表

3.1 支持全球区域要素(经度范围[-180,180]或[0,360]，纬度范围[-90,90])

要素	描述	单位	支持天数
u10m	10 米纬向风	m/s	10/15/30/45
v10m	10 米经向风	m/s	10/15/30/45
ws10m	10 米风速	m/s	10/15/30/45
wd10m	10 米风向	°	10/15/30/45
u100m	100 米纬向风	m/s	10/15/30/45
v100m	100 米经向风	m/s	10/15/30/45
wd100m	100 米风向	°	10/15/30/45
ws100m	100 米风速	m/s	10/15/30/45
t2m	2 米温度	°C	10/15/30/45
cldt	总云量	1	10/15/30/45
cldh	高云量	1	10/15/30/45
cldm	中云量	1	10/15/30/45
cldl	低云量	1	10/15/30/45
psz	地表气压	Pa	10/15/30/45
rh2m	2 米相对湿度	%	10/15/30/45
tp	降水	mm/hr	10/15/30/45
pres	降雪量（累积值）	mm	10/15/30/45
prer	降雨量（累积值）	mm	10/15/30/45
dod	沙尘光学厚度		10/15/30
dust_conc	地表沙尘浓度	μg/m³	10/15/30
dust_ddep	累计沉降	mg/m²	10/15/30
TMPsfc	地表气温	K	10/15/30/45
DLWRFsfc	地表向下长波通量	W/㎡	10/15/30
ssrd	地表向下短波通量	W/㎡	10/15/30/45
ddsf_ave	散射辐射	W/㎡	10/15
bdsf_ave	直接辐射	W/㎡	10/15
SOILT1	0-10 厘米深度土壤温度	K	10
SOILT2	10-40 厘米深度土壤温度	K	10
SOILT3	40-100 厘米深度土壤温度	K	10
SOILT4	100-200 厘米深度土壤温度	K	10
prei	降冰量（累积量）	mm	10
preg	霰降水量（累积值）	mm	10
dpt2m	2 米露点温度	K	10/15/30/45
gust	阵风	m/s	10
cape	对流有效位能	J/kg	10
u1000	1000 百帕纬向风	m/s	10
u925	925 百帕纬向风	m/s	10
u850	850 百帕纬向风	m/s	10
u800	800 百帕纬向风	m/s	10
u700	700 百帕纬向风	m/s	10
u600	600 百帕纬向风	m/s	10
u500	500 百帕纬向风	m/s	10
u400	400 百帕纬向风	m/s	10
u300	300 百帕纬向风	m/s	10
u200	200 百帕纬向风	m/s	10
u100	100 百帕纬向风	m/s	10
v1000	1000 百帕经向风	m/s	10
v925	925 百帕经向风	m/s	10
v850	850 百帕经向风	m/s	10
v800	800 百帕经向风	m/s	10
v700	700 百帕经向风	m/s	10
v600	600 百帕经向风	m/s	10
v500	500 百帕经向风	m/s	10
v400	400 百帕经向风	m/s	10
v300	300 百帕经向风	m/s	10
v200	200 百帕经向风	m/s	10
v100	100 百帕经向风	m/s	10
t1000	1000 百帕温度	K	10
t925	925 百帕温度	K	10
t850	850 百帕温度	K	10
t800	800 百帕温度	K	10
t700	700 百帕温度	K	10
t600	600 百帕温度	K	10
t500	500 百帕温度	K	10
t400	400 百帕温度	K	10
t300	300 百帕温度	K	10
t200	200 百帕温度	K	10
t100	100 百帕温度	K	10
q1000	1000 百帕比湿	kg/kg	10
q925	925 百帕比湿	kg/kg	10
q850	850 百帕比湿	kg/kg	10
q800	800 百帕比湿	kg/kg	10
q700	700 百帕比湿	kg/kg	10
q600	600 百帕比湿	kg/kg	10
q500	500 百帕比湿	kg/kg	10
q400	400 百帕比湿	kg/kg	10
q300	300 百帕比湿	kg/kg	10
q200	200 百帕比湿	kg/kg	10
q100	100 百帕比湿	kg/kg	10
SPFH2m	2 米比湿	kg/kg	10/15/30/45
rh1000	1000 百帕相对湿度	%	10
rh925	925 百帕相对湿度	%	10
rh850	850 百帕相对湿度	%	10
rh800	800 百帕相对湿度	%	10
rh700	700 百帕相对湿度	%	10
rh600	600 百帕相对湿度	%	10
rh500	500 百帕相对湿度	%	10
rh400	400 百帕相对湿度	%	10
rh300	300 百帕相对湿度	%	10
rh200	200 百帕相对湿度	%	10
rh100	100 百帕相对湿度	%	10
h1000	1000 百帕位势高度	m	10
h925	925 百帕位势高度	m	10
h850	850 百帕位势高度	m	10
h800	800 百帕位势高度	m	10
h700	700 百帕位势高度	m	10
h600	600 百帕位势高度	m	10
h500	500 百帕位势高度	m	10
h400	400 百帕位势高度	m	10
h300	300 百帕位势高度	m	10
h200	200 百帕位势高度	m	10
h100	100 百帕位势高度	m	10
omg1000	1000 百帕垂直速度	Pa/s	10
omg925	925 百帕垂直速度	Pa/s	10
omg850	850 百帕垂直速度	Pa/s	10
omg800	800 百帕垂直速度	Pa/s	10
omg700	700 百帕垂直速度	Pa/s	10
omg600	600 百帕垂直速度	Pa/s	10
omg500	500 百帕垂直速度	Pa/s	10
omg400	400 百帕垂直速度	Pa/s	10
omg300	300 百帕垂直速度	Pa/s	10
omg200	200 百帕垂直速度	Pa/s	10
omg100	100 百帕垂直速度	Pa/s	10
dp1000	1000 百帕露点温度	K	10
dp925	925 百帕露点温度	K	10
dp850	850 百帕露点温度	K	10
dp800	800 百帕露点温度	K	10
dp700	700 百帕露点温度	K	10
dp600	600 百帕露点温度	K	10
dp500	500 百帕露点温度	K	10
dp400	400 百帕露点温度	K	10
dp300	300 百帕露点温度	K	10
dp200	200 百帕露点温度	K	10
dp100	100 百帕露点温度	K	10
slp	海平面气压	mb	10/15/30
base_reflectivity	基本反射率	dBz	10
max_reflectivity	最大反射率	dBz	10
SHTFLsfc	地表感热通量	W/m²	10
LHTFLsfc	地表潜热通量	W/m²	10
ZORLsfc	地表粗糙度	m	10
qnh	修正海平面气压	hPa	10
t70m	70 米温度	K	10
USWRFsfc	地表向上短波通量	W/㎡	10
ULWRFsfc	地表向上长波通量	W/㎡	10
ri_min	理查德森数		10

3.2 只支持中国区域要素(经度范围[50.5,149.95]，纬度范围[0.05,69.95])

要素	描述	单位	支持天数
u30m	30 米纬向风	m/s	10/15/30/45
u50m	50 米纬向风	m/s	10/15/30
u60m	60 米纬向风	m/s	10
u65m	65 米纬向风	m/s	10
u70m	70 米纬向风	m/s	10
u75m	75 米纬向风	m/s	10
u80m	80 米纬向风	m/s	10
u85m	85 米纬向风	m/s	10
u90m	90 米纬向风	m/s	10
u95m	95 米纬向风	m/s	10
u105m	105 米纬向风	m/s	10
u110m	110 米纬向风	m/s	10
u115m	115 米纬向风	m/s	10
u120m	120 米纬向风	m/s	10
u125m	125 米纬向风	m/s	10
u130m	130 米纬向风	m/s	10
u135m	135 米纬向风	m/s	10
u140m	140 米纬向风	m/s	10
u145m	145 米纬向风	m/s	10
u150m	150 米纬向风	m/s	10
u160m	160 米纬向风	m/s	10
u170m	170 米纬向风	m/s	10/15/30
v30m	30 米经向风	m/s	10/15/30/45
v50m	50 米经向风	m/s	10/15/30
v60m	60 米经向风	m/s	10
v65m	65 米经向风	m/s	10
v70m	70 米经向风	m/s	10
v75m	75 米经向风	m/s	10
v80m	80 米经向风	m/s	10
v85m	85 米经向风	m/s	10
v90m	90 米经向风	m/s	10
v95m	95 米经向风	m/s	10
v105m	105 米经向风	m/s	10
v110m	110 米经向风	m/s	10
v115m	115 米经向风	m/s	10
v120m	120 米经向风	m/s	10
v125m	125 米经向风	m/s	10
v130m	130 米经向风	m/s	10
v135m	135 米经向风	m/s	10
v140m	140 米经向风	m/s	10
v145m	145 米经向风	m/s	10
v150m	150 米经向风	m/s	10
v160m	160 米经向风	m/s	10
v170m	170 米经向风	m/s	10/15/30
ws30m	30 米风速	m/s	10/15/30/45
ws50m	50 米风速	m/s	10/15/30
ws60m	60 米风速	m/s	10
ws65m	65 米风速	m/s	10
ws70m	70 米风速	m/s	10
ws75m	75 米风速	m/s	10
ws80m	80 米风速	m/s	10
ws85m	85 米风速	m/s	10
ws90m	90 米风速	m/s	10
ws95m	95 米风速	m/s	10
ws105m	105 米风速	m/s	10
ws110m	110 米风速	m/s	10
ws115m	115 米风速	m/s	10
ws120m	120 米风速	m/s	10
ws125m	125 米风速	m/s	10
ws130m	130 米风速	m/s	10
ws135m	135 米风速	m/s	10
ws140m	140 米风速	m/s	10
ws145m	145 米风速	m/s	10
ws150m	150 米风速	m/s	10
ws160m	160 米风速	m/s	10
ws170m	170 米风速	m/s	10/15/30
wd30m	30 米风向	°	10/15/30/45
wd50m	50 米风向	°	10/15/30
wd60m	60 米风向	°	10
wd65m	65 米风向	°	10
wd70m	70 米风向	°	10
wd75m	75 米风向	°	10
wd80m	80 米风向	°	10
wd85m	85 米风向	°	10
wd90m	90 米风向	°	10
wd95m	95 米风向	°	10
wd105m	105 米风向	°	10
wd110m	110 米风向	°	10
wd115m	115 米风向	°	10
wd120m	120 米风向	°	10
wd125m	125 米风向	°	10
wd130m	130 米风向	°	10
wd135m	135 米风向	°	10
wd140m	140 米风向	°	10
wd145m	145 米风向	°	10
wd150m	150 米风向	°	10
wd160m	160 米风向	°	10
wd170m	170 米风向	°	10/15/30

4.请求示例

cURL 请求示例

bash

curl -l 'https://api.tjweather.com/nc/beta?key=APPxxxx&fields=ws100m&loc=99.58,36.44&fcst_days=0&fcst_hours=2&grid=7&download=true'

Java 请求示例

java

import okhttp3.*;

public class QueryClusterInfoDemo {

    public static final String URL = "https://api.tjweather.com/nc/beta?key=APPxxxx&fields=ws10m&loc=99.58,36.44&fcst_days=0&fcst_hours=2&grid=7&download=true";

    public static void main(String[] args) throws Exception {
        OkHttpClient client = new OkHttpClient().newBuilder()
                .build();
        Request request = new Request.Builder()
                .url(URL)
                .method("GET", null)
                .build();
        Response response = client.newCall(request).execute();
        System.out.println(response.body().string());
    }
}

支持重试示例
当客户端出现信号灯超时，服务器拒绝等异常情况请求失败时，可以通过重试提升成功率

java

import okhttp3.*;

public class QueryClusterInfoDemo {
    public static final String URL = "https://api.tjweather.com/nc/beta?key=APPxxxx&fields=ws10m&loc=99.58,36.44&fcst_days=0&fcst_hours=2&grid=1";

    public static Request buildOkHttpRequest(String url) {
        return new Request.Builder()
                .url(url)
                .method("GET", null)
                .build();
    }

    public static void main(String[] args) {
        OkHttpClient client = new OkHttpClient().newBuilder().build();
        Request request = buildOkHttpRequest(URL);
        int retryCount = 0;
        int maxRetries = 3;
        boolean success = false;
        while (retryCount < maxRetries && !success) {
            try {
                Response response = client.newCall(request).execute();
                success = true;
                System.out.println(response.body().string());
            } catch (Exception e) {
                retryCount++;
            }
        }
        if (!success) {
            System.out.println("Failed to complete the request after " + maxRetries + " retries.");
        }
    }
}

5.响应消息

返回示例： 二进制文件流

错误示例：

json

{
  "code": 10001,
  "message": "查询失败，请稍后再试！",
  "data": null
}

6.常见错误码

错误码	说明
500	服务器内部错误
10001	查询失败，请稍后再试
10004	接口不存在
10005	超过访问量上限(N 次/日)
10006	要素超出可查询有效期
10007	超过并发量上限(N 次/秒)
10011	请求链接与所用的 appKey 不对应，请确认链接地址是否正确
10012	非法 appKey！
10014	服务繁忙，请稍后再访问！
10016	nc 文件构建失败
10017	用户状态异常
20001	缺失必选参数
20002	要素暂未开放
20003	要素未订阅
20004	参数值非法，例如参数要求是数字，结果输入中文
20005	参数格式非法，例如坐标分隔符需要用逗号分隔，使用了其他非法字符进行分割
20006	参数长度非法，输入超过长度限制
20007	经度不在[-180,360]范围内
20008	纬度不在[90,-90]范围内
20009	当前请求预报数据最多查询 N 天！
20010	目前仅提供 15min/1h 时间分辨率预报数据！
20011	当前请求同时最多获取 N 个要素预报数据！
20012	格点数据非法，目前仅支持 1,3,5,7！
20014	用户 API 未启用
20015	API 未启用
20017	当前请求点位坐标 loc 未订阅！
20018	当前请求点位坐标 grid 未订阅！

NetCDF 格式返回 ​

​

1.接口说明 ​

2.请求参数 ​

3.支持要素编码列表 ​

3.1 支持全球区域要素(经度范围[-180,180]或[0,360]，纬度范围[-90,90]) ​

3.2 只支持中国区域要素(经度范围[50.5,149.95]，纬度范围[0.05,69.95]) ​

4.请求示例 ​

5.响应消息 ​

6.常见错误码 ​