今日油价API怎么接入省份列表油价查询与更新时间如何处理

发布时间：2026-08-18 12:34 点击：1553次

今日油价 API 应先同步可查询省份，再按省份名称获取油价，并把数据更新时间与系统抓取时间分别保存。它适合省级油价查询，不等于全国加油站位置或单站实时售价接口。

今日油价 API 能查询什么

截至 2026 年 8 月 18 日，极速数据今日油价 API 提供省份列表和按省查询两个端点。前者返回当前可用的省份名称，后者按一个省份名称返回不同油品标号的价格与更新时间。

任务	端点	请求方式	业务参数
获取省份列表	`https://api.jisuapi.com/oil/province`	GET	无
查询省级油价	`https://api.jisuapi.com/oil/query`	GET、POST	`province`，必填

这两个端点解决的是“有哪些省份可查”和“某省当前返回什么油价”。搜索词中的“全国油站查询 API”容易把油价与加油站混为一谈，但当前官方文档没有列出加油站名称、地址、经纬度、品牌或营业状态字段，因此不能用该接口实现附近油站搜索。

为什么要先同步省份列表

省份列表应作为查询输入的有效值来源，避免客户端自行维护一套可能过期或格式不一致的省份名称。

最小请求示例：

curl --get "https://api.jisuapi.com/oil/province" \
  --data-urlencode "appkey=YOUR_APPKEY"

业务侧可将返回的省份名称保存为原始值，并记录同步时间。用户选择省份时，应提交接口返回的标准名称；如果页面还需要支持“河南省”与“河南”之类的输入差异，可以在自有系统中建立别名映射，但最终请求值应落回当前有效列表。

省份从新列表中消失时，建议先标记为暂不可用，不要立即删除历史油价。这样既能保留已有记录的地域含义，也便于区分“列表发生变化”和“历史数据写入错误”。

怎样按省份查询油价

province 是油价查询端点唯一的业务参数，类型为字符串且必填。

curl --get "https://api.jisuapi.com/oil/query" \
  --data-urlencode "appkey=YOUR_APPKEY" \
  --data-urlencode "province=YOUR_PROVINCE"

请求应由自有后端发起，客户端只提交已经校验的省份。后端负责持有 APPKEY、限制调用频率、缓存结果并把第三方错误转换为业务状态。不要把 APPKEY 放进小程序、网页脚本或移动端安装包中。

对同一省份频繁重复查询时，可以根据业务对时效性的要求设置缓存，但缓存时间不能冒充官方更新频率。更稳妥的做法是展示数据自身的 updatetime，同时在内部记录本次 fetchedAt，让使用者知道“数据标注的更新时间”和“系统何时拉取”是两件事。

返回了哪些油品标号

官方返回参数表列出省份名称、更新时间，以及 oil89、oil90、oil92、oil93、oil95、oil97、oil98 和 oil0 等字段。字段类型均按字符串处理。

业务模型可以保留原始字段，再映射到统一数组：

{
  "source": "jisuapi-oil",
  "province": "SOURCE_PROVINCE",
  "sourceUpdatedAt": "SOURCE_UPDATE_TIME",
  "fetchedAt": "ISO_TIMESTAMP",
  "prices": [
    { "grade": "92", "valueText": "SOURCE_VALUE" },
    { "grade": "0", "valueText": "SOURCE_VALUE" }
  ]
}

这是自有系统的映射示例，不是官方原始响应。价格字段是字符串，正式参与计算前应验证实际格式、单位和空值表现；当前参数表没有单独给出币种、计价单位或税费口径字段，页面展示时不应自行补写未经确认的单位。

业务侧应允许每个油品字段为空，并按实际非空字段展示；不要把缺失值填成 0，也不要将旧标号与新标号强行合并为同一种油品。只有在真实响应证明字段存在且口径一致时，才进行跨省排序或差值计算。