今日油价 prov 参数怎么传？查询油价与查询行情的必填差异
约 12 分钟 入门今日油价prov参数必填参数接入点对比
# 今日油价 prov 参数怎么传？查询油价与查询行情的必填差异
接口/接入点：今日油价（apiCode=138）· 查询油价（138-46）/ 查询行情（138-49） · 免费 · 适用人群：已接入或准备接入的开发者 · 阅读时间：约 4 分钟 · 最后实测核对：2026-09-18
同一个接口下的两个接入点，`prov` 一个选填一个必填。照着其中一个的写法去调另一个，请求会直接失败。下面把差异、省名写法、缺失时的返回逐条列清。
## 核心要点
- 查询油价（138-46）的 `prov` 是选填，不传时返回全国 31 个省份，计费次数为 1。
- 查询行情（138-49）的 `prov` 是必填，不传时平台层直接返回 `showapi_res_code=-1` 与 `showapi_res_error="must input prov field"`。
- 省名按精确匹配处理：`北京` 能查到，`北京市` 和 `广` 都会返回 `ret_code=-1`（2026-09-18 实测）。
## 两个接入点的必填规则
| 接入点 | 请求地址 | `prov` | 用途 |
|---|---|---|---|
| 查询油价（138-46） | `https://route.showapi.com/138-46` | 选填 | 查各标号具体价格 |
| 查询行情（138-49） | `https://route.showapi.com/138-49` | 必填 | 查涨跌幅与调价日 |
必填规则的出处是官方 OpenAPI 文档：`138-46` 的请求体 schema 里 `prov` 只声明了类型没有 `required`，`138-49` 的 schema 里 `required` 列表包含 `prov`。
## 不传 prov 时分别会怎样
这是两个接入点行为差别最大的地方，2026-09-18 各调一次的结果如下。
查询油价（138-46）不传 `prov`：
```json
{
"showapi_res_code": 0,
"showapi_fee_num": 1,
"showapi_res_body": { "ret_code": 0, "list": [ /* 31 个省份，共 31 条 */ ] }
}
```
返回成功，`list` 长度 31，覆盖全部 31 个省级行政区，计费次数为 1。
查询行情（138-49）不传 `prov`：
```json
{
"showapi_res_error": "must input prov field",
"showapi_res_code": -1,
"showapi_fee_num": 0,
"showapi_res_body": {}
}
```
平台层直接失败，`showapi_res_body` 是空对象，计费次数为 0。注意这里的失败层级与省名写错不同：缺必填参数在 `showapi_res_code` 就失败了，省名写错则是外层成功、内层 `ret_code=-1`。
## 省名怎么填
用产品文档示例里的标准省名：北京、天津、河北、山西、内蒙古、辽宁、吉林、黑龙江、上海、江苏、浙江、安徽、福建、江西、山东、河南、湖北、湖南、广东、广西、海南、重庆、四川、贵州、云南、西藏、陕西、甘肃、青海、宁夏、新疆。
2026-09-18 用查询油价（138-46）做的对照实测：
| 传入值 | 结果 |
|---|---|
| `prov=北京` | 成功，返回北京 1 条 |
| `prov=北京市` | `ret_code=-1`，`remark="参数错误，请输入所在省或直辖市的名称"`，不计费 |
| `prov=广` | 同上，返回参数错误 |
| `prov=广西` | 成功，返回广西 1 条 |
| `prov=广东` | 成功，返回广东 1 条 |
| `prov=" 北京 "` | 成功，省名前后空格被容错处理 |
不按前缀匹配这一点值得记住：想用模糊输入省时，接口不会帮你猜。
## 调用代码
两个接入点的调用方式完全一致，只换路径。
Python（requests）：
```python
import requests
def fetch(path, prov=None):
params = {"appKey": "YOUR_APPKEY"}
if prov:
params["prov"] = prov
resp = requests.post(f"https://route.showapi.com/{path}", data=params, timeout=5)
data = resp.json()
if data.get("showapi_res_code") != 0:
# 缺必填参数、AppKey 错误等平台层问题在这里暴露
raise RuntimeError(f"平台层失败: {data.get('showapi_res_error')}")
body = data["showapi_res_body"]
if body.get("ret_code") != 0:
# 省名写法不对等业务层问题在这里暴露
raise RuntimeError(f"业务层失败: {body.get('remark')}")
return body
print(fetch("138-46", "北京")["list"][0]["p92"])
print(fetch("138-49", "北京")["p0"]["change_percent"])
```
cURL：
```bash
# 查询油价（prov 选填）
curl -X POST "https://route.showapi.com/138-46?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" -d "prov=%E5%8C%97%E4%BA%AC"
# 查询行情（prov 必填）
curl -X POST "https://route.showapi.com/138-49?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" -d "prov=%E5%8C%97%E4%BA%AC"
```
Node.js（fetch）：
```javascript
async function fetchOil(path, prov) {
const body = new URLSearchParams({ appKey: "YOUR_APPKEY" });
if (prov) body.set("prov", prov);
const resp = await fetch(`https://route.showapi.com/${path}`, {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body,
signal: AbortSignal.timeout(5000),
});
const data = await resp.json();
if (data.showapi_res_code !== 0) throw new Error(data.showapi_res_error);
if (data.showapi_res_body.ret_code !== 0) throw new Error(data.showapi_res_body.remark);
return data.showapi_res_body;
}
console.log(await fetchOil("138-46", "北京"));
console.log(await fetchOil("138-49", "北京"));
```
## 适用条件与注意事项
- 查询油价（138-46）不传 `prov` 会一次返回 31 个省份，对做全国比价这类需求更省调用次数，用法见《今日油价：一次调用取回全国 31 省油价的做法》。
- 两个接入点返回的 `p0` 结构不同：`138-46` 的 `p0` 是价格字符串，`138-49` 的 `p0` 是含涨跌信息的对象。共用解析函数时按接入点分开处理，详见《今日油价返回字段对照：p89/p92/p0 与 ct 的含义与空值处理》。
- 省名要求标准写法，不接受前缀缩写，也不接受带「市」「省」后缀的写法。
- 平台层状态码与业务层状态码含义不同，建议分别判断并记录，便于定位问题。
## FAQ
**Q1：为什么照搬查询油价的代码去调查询行情会报错？**
查询行情（138-49）的 `prov` 是必填，不传会返回 `showapi_res_code=-1` 与 `showapi_res_error="must input prov field"`。查询油价（138-46）的 `prov` 是选填，不传也能返回全部 31 省。
**Q2：该用哪个接入点？**
要具体标号价格用查询油价（138-46），要涨跌幅和调价日用查询行情（138-49）。
**Q3：省名写「北京市」可以吗？**
不可以。2026-09-18 实测 `prov=北京市` 返回 `ret_code=-1` 与 `remark="参数错误，请输入所在省或直辖市的名称"`。用「北京」这样的标准省名。
**Q4：`prov=` 传空字符串算传了吗？**
实测与完全不传参数的结果一致，返回全国 31 个省份。
**Q5：查询行情不传 `prov` 会扣费吗？**
不会，实测 `showapi_fee_num=0`。
## 相关能力 / 下一步阅读
- [今日油价涨跌幅怎么查？查询行情接入点的调价日与涨跌率用法](https://www.showapi.com/guides/oilprice-trend-138)
- [今日油价：一次调用取回全国 31 省油价的做法](https://www.showapi.com/guides/oilprice-province-list-138)
- [今日油价返回字段对照：p89/p92/p0 与 ct 的含义与空值处理](https://www.showapi.com/guides/oilprice-fields-138)
- **本系列共 13 篇**：查看[今日油价指南总目录](https://www.showapi.com/guides/oilprice-guides-138)
