API 功能
支持全球城市名称、LocationID 和经纬度查询天气预报；
返回天气状况、最高最低温、湿度和风力信息；
原 code 参数和响应字段继续兼容现有调用；
兼容接口支持查询 1 至 7 天天气预报；
全球天气预报接口支持查询 1 至 30 天数据；
全球天气预报接口返回日出日落、月相和昼夜天气；
全球天气预报接口返回降水、气压、紫外线、能见度和云量；
全国多节点部署，支持稳定的业务访问；
多台服务器构建接口负载均衡。
全接口通过 HTTPS 提供服务；
全面兼容 Apple ATS；
全国多节点 CDN 部署；
默认最大 QPS:5，可在开发者中心自助升级，月付年付订单接口调用次数不限；
接口调用状态与状态监控
API 文档
接口地址: https://api.gugudata.com/weather/weatherinfo
返回格式: application/json; charset=utf-8
请求方式: GET
请求协议: HTTPS
请求示例: https://api.gugudata.com/weather/weatherinfo?appkey=YOUR_APPKEY&code=101190401&days=1&location=%e8%8b%8f%e5%b7%9e&lang=zh
数据预览: https://www.gugudata.com/preview/weatherinfo
接口测试: https://api.gugudata.com/weather/weatherinfo/sz
OpenAPI: https://www.gugudata.com/openapi/gugudata.openapi.3.1.json
前置接口
前置接口说明: 查询地区编码，根据市或区的关键字进行查询，如北京、苏州、海淀、吴中等
前置接口地址: https://api.gugudata.com/weather/weatherinfo/region?appkey=APPKEY&keyword=查询编码的市或区关键字，如北京、海淀
前置接口参数说明: appkey=YOUR_APPKEY&keyword=查询编码的市或区关键字，如北京、海淀
前置接口返回格式: application/json; charset=utf-8
前置接口返回说明: 包含地区编码以及省、市、区相关信息
前置接口请求方式: GET
前置接口请求协议: HTTPS
请求参数（GET 请求方式可参见下方示例代码）
参数名
参数类型
是否必须
默认值
备注
appkey
string
是
YOUR_APPKEY
付费后获取的 APPKEY
code
string
否
101190401
兼容参数。地区编码或 [经度,纬度]，未传 location 时生效。
days
integer
否
1
获取天气预报的天数，默认为1，即为当天数据。最大值为7。
location
string
否
苏州
推荐参数。支持城市名称、LocationID 或 经度,纬度；与 code 同时传递时优先生效。
lang
string
否
zh
返回语言，默认 zh。
返回参数
参数名
参数类型
备注
DataStatus.StatusCode
integer
接口返回状态码
DataStatus.StatusDescription
string
接口返回状态说明
DataStatus.ResponseDateTime
string
接口数据返回时间
DataStatus.DataTotalCount
integer
此条件下的总数据量
Data.Code
string
地区编码
Data.WeatherDate
string
天气预报的日期
Data.WeatherRegion
object
当前天气预报的详细地区信息，数据格式与查询地区编码接口返回数据格式一致。
Data.WeatherRegion.ReginType
string
位置信息类型，2为市级别数据，3为区级别数据
Data.WeatherRegion.Code
string
地区完整编码
Data.WeatherRegion.ProvinceCode
string
省编码
Data.WeatherRegion.ProvinceName
string
省名称
Data.WeatherRegion.CityCode
string
市编码
Data.WeatherRegion.CityName
string
市名称
Data.WeatherRegion.RegionCode
string
区编码
Data.WeatherRegion.RegionName
string
区名称
Data.WeatherRegion.TownCode
string
镇编码
Data.WeatherRegion.TownName
string
镇名称
Data.WeatherInfo
string
天气情况
Data.TemperatureHigh
integer
最高温度
Data.TemperatureLow
integer
最低温度
Data.TodayHistoryHighestTemperature
integer
兼容字段。当前没有同口径历史均值时返回 null
Data.TodayHistoryLowestTemperature
integer
兼容字段。当前没有同口径历史均值时返回 null
Data.WeatherWindCondition1
string
风向1
Data.WeatherWindCondition2
string
风向2
Data.WeatherWindLevel
string
风级
Data.SunRiseTime
string
日出时间
Data.SunSetTime
string
日落时间
Data.WeatherPerHour
array
当日小时级天气预报数组，最多覆盖未来7天
Data.WeatherPerHour.WeatherTime
string
预报的小时时间，24小时制
Data.WeatherPerHour.WeatherInfo
string
天气情况，天气情况枚举值：晴|多云|阴|阵雨|雷阵雨|雷阵雨伴有冰雹|雨夹雪|小雨|中雨|大雨|暴雨|大暴雨|特大暴雨|阵雪|小雪|中雪|大雪|暴雪|雾|冻雨|沙尘暴|小雨-中雨|中雨-大雨|大雨-暴雨|暴雨-大暴雨|大暴雨-特大暴雨|小雪-中雪|中雪-大雪|大雪-暴雪|浮尘|扬沙|强沙尘暴|霾
Data.WeatherPerHour.Temperature
string
温度
Data.WeatherPerHour.Wet
integer
空气湿度
Data.WeatherPerHour.WeatherWindCondition
string
风向
Data.WeatherPerHour.WeatherWindLevel
string
风级
Data.LifeHelperUV
object
紫外线指数，最多覆盖未来3天
Data.LifeHelperWear
object
穿衣指数，最多覆盖未来3天
Data.LifeHelperWashCar
object
洗车指数，最多覆盖未来3天
Data.LifeHelperAir
object
空气污染扩散条件指数，最多覆盖未来3天
Data.LifeHelper.HelperName
string
指数名称
Data.LifeHelper.HelperStatus
string
指数状态
Data.LifeHelper.HelperLevel
integer
指数值。总分：紫外线5分，穿衣7分，洗车4分，空气5分
Data.LifeHelper.HelperContent
string
指数内容
Data.WeatherDataGenerateDateTime
string
天气预报内容数据生成时间
鉴权方式
接口支持以下 AppKey 传递方式，任选一种即可；已有请求示例、Postman 集合和历史代码仍可继续使用原来的 appkey 参数方式。
传输载体
参数
示例
说明
HTTP Header
X-GUGUDATA-APPKEY
X-GUGUDATA-APPKEY: YOUR_APPKEY
推荐方式，适合服务端接入和统一封装。
HTTP Header
X-API-Key
X-API-Key: YOUR_APPKEY
通用 API Key Header，便于和常见 API 客户端集成。
HTTP Header
Authorization
Authorization: Bearer YOUR_APPKEY
适合 OpenAI 兼容接口或 Bearer Token 风格客户端。
Query 参数
appkey
?appkey=YOUR_APPKEY
兼容现有示例、Postman 集合、浏览器调试和历史代码。
部分历史 POST 接口仍兼容表单或 JSON body 中的 appkey；新接入建议优先使用 Header 或 Query 参数。
接口常见 HTTP 响应状态码
以下为接口调用中常见的 HTTP 传输层状态码，不等同于响应体内的业务状态码；完整状态码注册表以 IANA HTTP Status Code Registry 为准。
状态码
状态码解释
备注
200
请求成功
HTTP 请求已成功处理；业务状态请结合响应体中的自定义业务码判断。
201
资源已创建
创建类接口请求成功，并已生成对应资源。
202
请求已接受
请求已被接受处理，结果可能异步完成。
204
无响应内容
请求成功但响应体为空，适用于无需返回数据的操作。
304
资源未变更
配合缓存或条件请求使用，表示可继续使用本地缓存。
400
请求参数错误
请求参数缺失、格式错误或参数组合不合法。
401
认证失败
缺少、无效或未通过认证的访问凭证（如 AppKey）。
403
无权限访问
订单到期、权限不足或接口额度不可用。
404
资源不存在
请求路径不存在。
405
请求方法不允许
当前路径不支持该 HTTP 方法。
408
请求超时
客户端请求在服务端等待时间内未完成，可稍后重试。
409
请求冲突
请求与当前资源状态冲突，调整参数或业务状态后重试。
413
请求内容过大
上传文件或请求体超过接口限制。
414
请求地址过长
请求 URL 超过服务端可处理长度，建议减少查询参数或改用 POST。
415
请求内容类型不支持
上传或请求体的内容类型不符合接口要求。
422
请求语义错误
请求格式正确，但参数取值、语义或业务约束无法处理。
429
请求频率受限
默认按来源 IP 限速，单 IP 最多 5 QPS，可满足常规业务调用。超出限制时接口会返回 429 请求频率受限；已购买接口订单可加购 10 QPS 扩展。
431
请求头过大
请求头字段过大或过多，建议精简 Header 后重试。
500
服务器内部错误
服务端处理异常，请稍后重试。
502
网关或上游错误
网关或代理从上游服务收到异常响应。
503
服务暂时不可用
服务维护、容量保护或依赖异常导致暂时不可用，请稍后重试。
504
网关超时
网关等待上游服务响应超时，可稍后重试或降低请求复杂度。
接口自定义业务状态码
业务状态码
业务状态码解释
备注
100
正常返回
101
参数错误
102
请求频率受限
每分钟请求不能超过 100 次
103
账号欠费
104
APPKEY 错误
请检查传递的 APPKEY 是否为开发者中心获取到的值
请求示例代码
cURL 请求示例
C 请求示例
C# 请求示例
Go 请求示例
Java 请求示例
jQuery 请求示例
Node.js 请求示例
Objective-C 请求示例
PHP 请求示例
Python 请求示例
Ruby 请求示例
Swift 请求示例
curl --location --request GET 'https://api.gugudata.com/weather/weatherinfo?appkey=YOUR_APPKEY&code=101190401&days=1&location=%e8%8b%8f%e5%b7%9e&lang=zh'
#include
int main(void) {
CURL *curl = curl_easy_init();
if (curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://api.gugudata.com/weather/weatherinfo?appkey=YOUR_APPKEY&code=101190401&days=1&location=%e8%8b%8f%e5%b7%9e&lang=zh");
curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
CURLcode res = curl_easy_perform(curl);
(void)res;
curl_easy_cleanup(curl);
}
return 0;
}
using System;
using System.Collections.Generic;
using System.IO;
using System.Net.Http;
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.gugudata.com/weather/weatherinfo?appkey=YOUR_APPKEY&code=101190401&days=1&location=%e8%8b%8f%e5%b7%9e&lang=zh");
var response = client.SendAsync(request).Result;
Console.WriteLine(response.Content.ReadAsStringAsync().Result);
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://api.gugudata.com/weather/weatherinfo?appkey=YOUR_APPKEY&code=101190401&days=1&location=%e8%8b%8f%e5%b7%9e&lang=zh"
req, err := http.NewRequest("GET", url, nil)
if err != nil {
fmt.Println(err)
return
}
res, err := http.DefaultClient.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()
body, err := io.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
OkHttpClient client = new OkHttpClient().newBuilder().build();
Request request = new Request.Builder()
.url("https://api.gugudata.com/weather/weatherinfo?appkey=YOUR_APPKEY&code=101190401&days=1&location=%e8%8b%8f%e5%b7%9e&lang=zh")
.method("GET", null)
.build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());
$.ajax({
url: "https://api.gugudata.com/weather/weatherinfo?appkey=YOUR_APPKEY&code=101190401&days=1&location=%e8%8b%8f%e5%b7%9e&lang=zh",
method: "GET",
}).done(function (response) {
console.log(response);
});
const https = require("node:https");
const url = "https://api.gugudata.com/weather/weatherinfo?appkey=YOUR_APPKEY&code=101190401&days=1&location=%e8%8b%8f%e5%b7%9e&lang=zh";
const request = https.request(url, { method: "GET", headers: { } }, handleResponse);
request.on("error", console.error);
request.end();
function handleResponse(response) {
const chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
response.on("end", function () {
console.log(Buffer.concat(chunks).toString("utf8"));
});
}
#import
NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://api.gugudata.com/weather/weatherinfo?appkey=YOUR_APPKEY&code=101190401&days=1&location=%e8%8b%8f%e5%b7%9e&lang=zh"]];
[request setHTTPMethod:@"GET"];
NSURLSessionDataTask *task = [[NSURLSession sharedSession] dataTaskWithRequest:request completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
if (error) {
NSLog(@"%@", error);
return;
}
NSLog(@"%@", [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding]);
}];
[task resume];
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.gugudata.com/weather/weatherinfo?appkey=YOUR_APPKEY&code=101190401&days=1&location=%e8%8b%8f%e5%b7%9e&lang=zh",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_CUSTOMREQUEST => "GET",
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
import requests
url = "https://api.gugudata.com/weather/weatherinfo?appkey=YOUR_APPKEY&code=101190401&days=1&location=%e8%8b%8f%e5%b7%9e&lang=zh"
response = requests.request("GET", url)
print(response.text)
require "uri"
require "net/http"
url = URI("https://api.gugudata.com/weather/weatherinfo?appkey=YOUR_APPKEY&code=101190401&days=1&location=%e8%8b%8f%e5%b7%9e&lang=zh")
https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true
request = Net::HTTP::Get.new(url)
response = https.request(request)
puts response.read_body
import Foundation
let semaphore = DispatchSemaphore(value: 0)
var request = URLRequest(url: URL(string: "https://api.gugudata.com/weather/weatherinfo?appkey=YOUR_APPKEY&code=101190401&days=1&location=%e8%8b%8f%e5%b7%9e&lang=zh")!, timeoutInterval: .infinity)
request.httpMethod = "GET"
let task = URLSession.shared.dataTask(with: request) { data, response, error in
defer { semaphore.signal() }
guard let data = data else {
print(String(describing: error))
return
}
print(String(data: data, encoding: .utf8)!)
}
task.resume()
semaphore.wait()
Swagger 文档
在 Postman 中测试运行
在 Apifox 中测试运行
打开 LLM 页面
复制 LLM.md
常见问题 Q&A
Q: 数据请求有缓存吗？
A: 接口默认以实时响应为目标。对于日更、月更等具备明确更新周期的数据，会在数据周期内采用缓存与预热策略，以提升响应速度和稳定性；实时查询类接口则以接口说明中的更新频率为准。建议业务侧结合数据时效要求设置本地缓存与重试策略，避免高频重复请求。
Q: 如何保证请求时 AppKey 的安全性？
A: 建议将 AppKey 保存在服务端环境中，由后端统一调用 API，再向前端或业务系统返回必要结果。不要把 AppKey 写入网页、App 客户端或公开仓库；生产环境建议按系统或业务线拆分 AppKey，并保留调用日志，便于权限控制、审计与问题排查。
Q: 接口可以用于哪些开发语言？
A: 只要支持 HTTPS 请求的语言和框架均可接入，包括 Java、Python、Node.js、PHP、Go、C#、Swift、Kotlin 等。推荐由后端统一封装调用逻辑，集中处理鉴权、缓存、限流、重试和错误码映射，让 Web、App、AI Agent、内部系统和自动化任务复用同一套数据能力。
Q: 接口的性能可以保证吗？
A: GuGuData API 按生产环境标准部署，持续关注接口稳定性、响应速度与可用性。实际响应时间会受接口类型、请求参数、数据源更新和网络环境影响；建议生产接入前进行联调与压测，并设置合理的超时、重试、降级和告警策略。批量处理或高并发场景可提前评估 QPS、白名单和专属容量方案。
服务协议与免责声明
购买或使用 GuGuData API 服务前，请充分阅读服务协议、免责声明与数据合规声明。相关页面均支持在浏览器中快速导出 PDF，便于内部归档、评审和合规留存。
服务协议
免责声明
数据合规
技术支持
技术支持邮箱: support@gugudata.com
微信客服: 客服链接
专业软件开发与系统工程服务
GuGuData 官方认证工程合作伙伴，专注企业级数据接口集成、AI 工程化与大规模数据处理。团队深度理解 GuGuData 数据接口体系，具备海量数据采集、治理、检索与高并发接口服务经验，可围绕业务场景构建 AI Agent、MCP 接入、智能工作流和生产级数据应用，让数据能力稳定进入现有流程、内部平台和核心业务系统。
了解工程服务