接口概述
一句话说明
oilprice.advance 按「当前时间 + 2 小时」所在的日期取生效批次。
若该批次生效日期晚于今天，说明查到的是即将生效的新价格（advance = true）；
否则返回当前生效的价格（advance = false）。
无论哪种情况，都会明确返回 effectiveDate，调用方无需猜测。
| 请求地址 | https://api.xujian.tech/openapi/oilprice/advance |
|---|---|
| 请求方式 | GET |
| 鉴权方式 | 请求头 X-API-Key（不做签名与加密） |
| 接口编码 | oilprice.advance |
| 收费类型 | YEARLY（按年付费，360.0000 元/年），需后台为该客户授权后才可调用 |
| 响应格式 | JSON，Content-Type: application/json;charset=UTF-8 |
| 是否需要授权 | 是（需后台为该客户授权，授权有效期内调用不额外扣费） |
| 提前量 | 固定 2 小时（不可配置） |
| 典型用途 | 加油站调价预置、物流报价提前测算、油价变动预警、调价日切换对账 |
快速开始
把 你的APIKey 换成控制台获取的 API Key（需先联系平台完成按年授权）：
curl -s "https://api.xujian.tech/openapi/oilprice/advance" \
-H "X-API-Key: 你的APIKey"只看某个省（可选）
curl -s "https://api.xujian.tech/openapi/oilprice/advance?province=%E9%87%8D%E5%BA%86%E5%B8%82" \
-H "X-API-Key: 你的APIKey"请求参数
| 参数名 | 必填 | 说明 |
|---|---|---|
X-API-Key |
是 | 控制台获取的 API Key；缺失返回「缺少请求头 X-API-Key」 |
| 参数名 | 必填 | 类型 | 说明 |
|---|---|---|---|
province |
否 | String | 省名称或 6 位 adcode；不传返回全部地区 |
city |
否 | String | 市名称或 6 位 adcode |
district |
否 | String | 区县名称或 6 位 adcode |
响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
effectiveDate |
String | 返回价格批次的生效开始时间 yyyy-MM-dd |
advance |
boolean | true 表示这是尚未生效的新价格；false 表示当前生效价格 |
total |
int | 返回条数 |
list |
Array | 价格明细，字段与 oilprice.all 的 list[] 完全一致 |
apiCode / apiName |
String | 接口编码与接口名称 |
chargeType |
String | 本次计费方式（YEARLY） |
balance |
BigDecimal | 账户余额（按年套餐内不扣费，交易前后一致） |
costMs |
long | 接口耗时（毫秒） |
响应示例
成功 —— 查到即将生效的新价格（advance = true）
{
"code": 0,
"msg": "success",
"data": {
"effectiveDate": "2026-09-25",
"advance": true,
"total": 1,
"list": [
{
"effectiveDate": "2026-09-25",
"provinceCode": "500000",
"province": "重庆市",
"cityCode": null,
"city": null,
"districtCode": null,
"district": null,
"priceDiesel0": 7.41,
"priceDiesel10": 7.86,
"priceDiesel35": 8.20,
"priceGas92": 8.02,
"priceGas95": 8.48,
"priceGas98": 9.55,
"dataUpdateTime": "2026-09-24 22:05:00"
}
],
"apiCode": "oilprice.advance",
"apiName": "提前查询发改委价格",
"chargeType": "YEARLY",
"balance": 100.0000,
"costMs": 8
}
}成功 —— 无更新价格，返回当前生效价格（advance = false）
{
"code": 0,
"msg": "success",
"data": {
"effectiveDate": "2026-09-11",
"advance": false,
"total": 1,
"list": [
{
"effectiveDate": "2026-09-11",
"provinceCode": "500000",
"province": "重庆市",
"cityCode": null,
"city": null,
"districtCode": null,
"district": null,
"priceDiesel0": 7.28,
"priceDiesel10": 7.72,
"priceDiesel35": 8.05,
"priceGas92": 7.86,
"priceGas95": 8.31,
"priceGas98": 9.36,
"dataUpdateTime": "2026-09-11 09:00:00"
}
],
"apiCode": "oilprice.advance",
"apiName": "提前查询发改委价格",
"chargeType": "YEARLY",
"balance": 100.0000,
"costMs": 7
}
}失败 —— 未授权或授权已过期
{
"code": 500,
"msg": "接口未授权或授权已过期",
"data": null
}错误码与常见失败原因
| code | msg（示例） | 处理建议 |
|---|---|---|
| 0 | success | 调用成功，用 advance 判断是否为提前价格 |
| 500 | 缺少请求头 X-API-Key | 在请求头中补充 X-API-Key |
| 500 | API Key 无效 / API Key 已停用 | 检查 Key 是否正确，或在控制台重新启用 |
| 500 | 客户不存在或已停用 | 联系平台运营确认账号状态（可联系微信xujian_cq） |
| 500 | 接口未授权或授权已过期 | 本接口为按年套餐，需后台为该客户授权；联系平台续费（可联系微信xujian_cq）后重试 |
| 500 | 接口不存在或已停用 | 确认接口编码 oilprice.advance 当前是否维护中 |
多语言调用示例
String body = HttpRequest.get("https://api.xujian.tech/openapi/oilprice/advance")
.header("X-API-Key", apiKey)
.timeout(10000)
.execute().body();import requests
resp = requests.get(
"https://api.xujian.tech/openapi/oilprice/advance",
headers={"X-API-Key": api_key},
timeout=10,
)
data = resp.json()["data"]
print(data["effectiveDate"], "advance=", data["advance"])const res = await fetch("https://api.xujian.tech/openapi/oilprice/advance", {
headers: {"X-API-Key": apiKey}
});
const json = await res.json();常见问题
这个接口怎么收费？
oilprice.advance 的收费类型为 YEARLY（按年付费），当前价格 360.0000 元/年，需后台为该客户授权后方可调用；授权有效期内调用不额外扣费，授权过期会返回「接口未授权或授权已过期」。
「提前 2 小时」具体怎么算？
服务端用「当前时间 + 2 小时」所在日期作为目标日期，再取不晚于该日期的最新生效批次。 9/24 22:00 调用 → 目标日期 9/25 → 可查到 9/25 0 点生效的新价格； 9/24 21:00 调用 → 目标日期仍是 9/24 → 只能查到 9/24 之前生效的价格。
没有新调价时会返回什么？
返回当前生效的全部价格，同时 advance 为 false、
effectiveDate 为当前批次生效日期，调用方据此判断「暂无调价」。
怎么判断返回的是不是新价格？
看 advance 字段，也可以自己比较 effectiveDate 与当天日期。
未授权会怎样？
返回 code=500、msg=接口未授权或授权已过期，不扣费。
请联系平台完成按年授权后再调用。
