测试 Zyla API Hub 的油价定位器 API 和 Postman

您需要在本周发布一个功能，该功能显示 ZIP 代码附近的真实油价，并且如果用户点击一个加油站，则返回坐标、营业时间和便利设施等详细信息。在本指南结束时，您将在 Postman 中拥有一个针对 Zyla API Hub 上的油价定位器 API 的有效请求（和代码），以及从 MCP 兼容的 AI 代理调用相同 API 的路径。

油价定位器 API 提供的内容

油价定位器 API 返回给定 ZIP 代码和燃料类型的最新加油站价格。当您通过其 ID 查找加油站时，它还提供详细的加油站元数据（地址、坐标、电话、营业时间、便利设施、燃料等）。这对于路由应用程序、交付仪表板、车队仪表板以及任何帮助用户找到附近更便宜油价的消费者应用程序都是实用的选择。

所有调用都通过 Zyla API Hub 进行：一个帐户，一个密钥，一个订阅模型。您通过简单的 Bearer 令牌头进行身份验证。市场上托管着超过 10,000 个公共 API，您可以在 zylalabs.com 浏览。

在 Zyla API Hub 上开始

打开 Zyla 上的油价定位器 API 列表。单击订阅（或在可用时开始免费试用）以获取您的 API 密钥，然后使用下面显示的授权头格式调用端点。Zyla 订阅是基于配额的（不是按调用付费）。对于此 API，第一个订阅层提供 7 天试用或 50 次请求；没有免费计划。请查看 API 页面以获取当前访问选项和定价。

当您准备好测试时，登录并获取您的密钥。如果您还没有帐户，您可以在一分钟内注册。

身份验证

使用您的 Zyla 密钥和 Bearer 令牌头：

头：Authorization: Bearer YOUR_API_KEY

这里涵盖的端点没有请求体。查询参数在需要时使用（下面有文档）。

您将使用的端点

1) 获取价格

方法： GET
URL： https://zylalabs.com/api/4808/gas-price-locator-api/5997/get-prices
描述： 传递 ZIP 代码和燃料类型以检索该区域或附近最近加油站的油价。

所需查询参数：

zip（数字）：例如，90001
type（字符串）：例如，regular

Postman 设置

方法：GET
URL：https://zylalabs.com/api/4808/gas-price-locator-api/5997/get-prices
参数：zip=90001，type=regular
头：Authorization: Bearer YOUR_API_KEY
发送请求

官方 cURL 示例

curl -s -X GET "https://zylalabs.com/api/4808/gas-price-locator-api/5997/get-prices?zip=90001&type=regular" \
-H "Authorization: Bearer YOUR_API_KEY"

官方示例响应

{
"status": "success",
"zip": "77478",
"gas_type": "regular",
"currency": "USD",
"gas_prices": [
{
"average": "$2.60",
"lowest": "$2.07"
},
{
"station": "Shell",
"address": "2995 Dulles Ave Missouri City, TX",
"price": "$2.33"
},
{
"station": "Sam's Club",
"address": "351 SH-6 Sugar Land, TX",
"price": "$2.33"
},
{
"station": "Murphy Express",
"address": "7520 Highway 90 A. Sugar Land, TX",
"price": "$2.36"
},
{
"station": "WB Food Mart",
"address": "13003 W Bellfort Ave Sugar Land, TX",
"price": "$2.38"
},
{
"station": "Shell",
"address": "1750 Williams Trace Blvd Sugar Land, TX",
"price": "$2.39"
},
{
"station": "Valero & Circle K",
"address": "13445 W Airport Blvd Sugar Land, TX",
"price": "$2.59"
},
{
"station": "Chevron",
"address": "13811 SW Fwy Sugar Land, TX",
"price": "$2.69"
},
{
"station": "Texaco",
"address": "7800 US-90 A Sugar Land, TX",
"price": "$2.69"
},
{
"station": "Exxon",
"address": "1740 Dulles Ave Sugar Land, TX",
"price": "$2.79"
},
{
"station": "Shell",
"address": "13747 SW Fwy Sugar Land, TX",
"price": "$2.79"
}
]
}

您实际使用的字段

status：字符串以确认成功。
zip：查找中使用的 ZIP 代码。
gas_type：请求的燃料类型。
currency：价格的货币（示例中为 USD）。
gas_prices：可能以聚合对象（平均、最低）开头的数组，后跟具有加油站、地址、价格的加油站级条目。

实用说明：

价格是格式化的货币字符串（例如，“$2.33”），而不是原始数字。如果您需要数值，请在计算之前去掉货币符号。
当数据源指示时，单位为每加仑美元（请参见加油站数据以获取单位上下文）。
数组可能结合聚合统计和加油站行。您的解析器应优雅地处理这两种形状。

2) 加油站数据

方法： GET
URL： https://zylalabs.com/api/4808/gas-price-locator-api/23308/station-data
描述： 返回加油站的详细数据。您必须指定一个加油站 ID。您可以从获取价格端点获得该 ID。

参数： 列表指示您指定一个加油站 ID，但未记录参数键。调用者应参考 API 页面以了解在调用此端点时如何提供加油站 ID。请勿发明参数名称；在您在帐户的控制台或文档中获得确切的文档参数格式之前，仅发送授权头。

官方 cURL 示例

官方示例响应

您实际使用的字段

data.station_id，data.name：识别加油站。
data.address.*：可渲染的行和城市/州/ZIP 以供 UI 和地理编码回退。
data.coordinates.lat/lng：精确的地图位置。
data.open_status，data.opening_hours：显示其是否开放和典型的营业时间。
data.rating.overall，data.rating.count：渲染星级和评论计数。
data.currency，data.price_unit：正确显示单位（dollars_per_gallon）。
data.fuels：过滤或标记支持的燃料类型。
data.amenities：展示有用的功能（例如，支付加油、ATM）。
data.nearby_station_ids：链式请求以建议替代方案。

复制粘贴代码：获取价格的 Python 示例

此示例使用文档查询参数调用获取价格端点，并解析聚合和加油站条目。在运行之前替换 YOUR_API_KEY。

import os
import requests

API_KEY = os.getenv("ZYLALABS_API_KEY", "YOUR_API_KEY")
url = "https://zylalabs.com/api/4808/gas-price-locator-api/5997/get-prices"
params = {
"zip": "90001",
"type": "regular"
}
headers = {
"Authorization": f"Bearer {API_KEY}"
}

resp = requests.get(url, params=params, headers=headers, timeout=20)
resp.raise_for_status()
data = resp.json()

if data.get("status") != "success":
raise SystemExit(f"API returned non-success: {data}")

print(f"ZIP: {data.get('zip')} | Fuel: {data.get('gas_type')} | Currency: {data.get('currency')}")
stations = []
for entry in data.get("gas_prices", []):
if "station" in entry:
stations.append({
"station": entry.get("station"),
"address": entry.get("address"),
"price": entry.get("price")
})
else:
# 聚合行（例如，平均/最低）
avg = entry.get("average")
low = entry.get("lowest")
if avg or low:
print(f"聚合：average={avg}, lowest={low}")

print("顶级加油站：")
for s in stations[:5]:
print(f"- {s['station']} | {s['price']} | {s['address']}")

快速使用 Postman 测试

如果您在探索时更喜欢使用 Postman 而不是 cURL，这里有一个快速路径可以实现绿色运行：

创建一个新的 GET 请求选项卡。
将 URL 设置为 https://zylalabs.com/api/4808/gas-price-locator-api/5997/get-prices。
打开参数选项卡并添加：
- zip = 90001
- type = regular
打开头选项卡并添加：
- Authorization = Bearer YOUR_API_KEY
发送请求并确认 200 OK 及上述 JSON 响应。

接下来，设置第二个 GET 选项卡，指向 https://zylalabs.com/api/4808/gas-price-locator-api/23308/station-data，并包括相同的授权头。列表说明您必须为此端点指定一个加油站 ID；在准备通过 ID 获取特定加油站时，请查阅您的 Zyla 控制台/文档以获取确切的参数格式。

现实世界实施说明

单位和货币：加油站数据端点明确报告货币和 price_unit 为 dollars_per_gallon。将获取价格的价格视为货币字符串；如果您在应用中混合数据源，请一致地格式化它们。
解析 gas_prices 列表：您的代码应预期前一或两个条目可能是聚合行（平均、最低），后面跟着每个加油站的行，包括加油站、地址、价格。
缓存策略：通过（zip，type）缓存成功响应以减少重复获取。对于燃料价格，短 TTL（例如，5-15 分钟）通常是合理的；根据您的用户体验需求进行调整。
优雅的回退：如果获取价格中没有加油站的详细信息，请使用加油站数据（带加油站 ID）来丰富坐标、营业时间、便利设施和附近建议。
配额：Zyla 计划是基于订阅 + 配额，而不是按调用付费。这里的第一个层级是 7 天试用或 50 次请求。请注意您的使用情况，并在可能的情况下批量调用。

通过 MCP 从 AI 代理调用 API

如果您使用的是 MCP 兼容客户端（Claude Code、Cursor、Windsurf 等），您可以通过 Zyla 的 MCP 端点路由调用。将您的代理工具指向：

MCP

在您的 MCP 客户端期望的位置提供您的 Zyla API 密钥（该端点接受 apikey 查询参数；请按照您的 MCP 客户端的配置进行秘密设置）。在代理中，按上述方式调用油价定位器 API 端点（包括 Authorization: Bearer YOUR_API_KEY 头和获取价格的文档查询参数）。保持相同的 Hub URL：