在 C# 中使用 Zyla API Hub 集成汽油价格 API（指南）

您需要交付一个 C# 集成，通过邮政编码获取实时燃料价格，具有可靠的单位和可预测的身份验证。在本指南结束时，您将能够从 C# 查询 Zyla API Hub 上的汽油价格 API，解析 JSON，并准备将数据插入到您的结账、车队仪表板或路由逻辑中。

汽油价格 API 提供的内容

汽油价格 API 返回给定邮政编码内相关加油站的燃料价格信息，并支持按站点级别查找数据。它非常适合需要显示或比较当地燃料成本、计算旅行费用或保持物流和道路服务预算最新的应用程序。

Zyla API Hub 集中管理超过 10,000 个公共 API 的身份验证（一个帐户，一个 API 密钥）和计费。汽油价格 API 在每个请求中使用 Authorization: Bearer 令牌，并提供基于订阅 + 配额的访问（不是按调用计费）。首次使用时，您可以获得 7 天的试用或 50 次请求以验证您的集成。没有免费计划；请查看 API 页面以获取当前访问选项和定价。

在 Zyla API Hub 上开始

以下是获取您的密钥并调用端点的最小流程：

打开 API 列表：汽油价格 API。
点击订阅（或在可用时开始免费试用），并完成流程以获取您的 API 密钥。
在调用 https://zylalabs.com/api/ 下的端点时使用带有 Authorization: Bearer 头的密钥。

如果您还没有 Zyla 帐户，可以在此快速创建一个：注册。您还可以随时在 Zyla API Hub 上探索其他类别。

您将使用的端点

汽油价格 API 通过 Zyla API Hub 提供两个文档化的端点：

1) 价格（GET）

请求 URL：

https://zylalabs.com/api/3927/gasoline-prices-api/4649/prices

描述：传递您选择的邮政编码和您想要检查的燃料类型。API 返回给定邮政编码内相关加油站的价格。如果某个站点没有可用信息，您可以在站点数据端点中使用其 ID。

所需查询参数：

zip (string): 示例 90001
type (string): 示例 regular

身份验证：Authorization: Bearer YOUR_API_KEY

官方 cURL 示例（复制/粘贴）：

curl -s -X GET "https://zylalabs.com/api/3927/gasoline-prices-api/4649/prices?zip=90001&type=regular" \
-H "Authorization: Bearer YOUR_API_KEY"

官方 JSON 响应（逐字）：

{"success":true,"result":[{"currency":"usd","name":"Alaska","gasoline":"3.312","midGrade":"3.549","premium":"3.776","diesel":"3.541"},{"currency":"usd","name":"Alabama","gasoline":"2.804","midGrade":"3.242","premium":"3.640","diesel":"3.471"},{"currency":"usd","name":"Arkansas","gasoline":"2.779","midGrade":"3.192","premium":"3.570","diesel":"3.323"},{"currency":"usd","name":"Arizona","gasoline":"3.155","midGrade":"3.485","premium":"3.803","diesel":"3.643"},{"currency":"usd","name":"California","gasoline":"4.449","midGrade":"4.679","premium":"4.852","diesel":"4.996"},{"currency":"usd","name":"Colorado","gasoline":"2.984","midGrade":"3.367","premium":"3.688","diesel":"3.417"},{"currency":"usd","name":"Connecticut","gasoline":"3.097","midGrade":"3.718","premium":"4.063","diesel":"3.845"},{"currency":"usd","name":"District of Columbia","gasoline":"3.279","midGrade":"3.866","premium":"4.254","diesel":"3.918"},{"currency":"usd","name":"Delaware","gasoline":"3.203","midGrade":"3.718","premium":"4.016","diesel":"3.772"},{"currency":"usd","name":"Florida","gasoline":"3.217","midGrade":"3.655","premium":"3.970","diesel":"3.676"},{"currency":"usd","name":"Georgia","gasoline":"2.966","midGrade":"3.404","premium":"3.801","diesel":"3.663"},{"currency":"usd","name":"Hawaii","gasoline":"4.555","midGrade":"4.794","premium":"5.040","diesel":"5.307"},{"currency":"usd","name":"Iowa","gasoline":"2.911","midGrade":"3.230","premium":"3.667","diesel":"3.434"},{"currency":"usd","name":"Idaho","gasoline":"3.046","midGrade":"3.306","premium":"3.552","diesel":"3.435"},{"currency":"usd","name":"Illinois","gasoline":"3.280","midGrade":"3.837","premium":"4.286","diesel":"3.650"},{"currency":"usd","name":"Indiana","gasoline":"3.029","midGrade":"3.562","premium":"4.053","diesel":"3.687"},{"currency":"usd","name":"Kansas","gasoline":"2.811","midGrade":"3.139","premium":"3.440","diesel":"3.316"},{"currency":"usd","name":"Kentucky","gasoline":"2.770","midGrade":"3.273","premium":"3.696","diesel":"3.350"},{"currency":"usd","name":"Louisiana","gasoline":"2.777","midGrade":"3.187","premium":"3.557","diesel":"3.377"},{"currency":"usd","name":"Massachusetts","gasoline":"3.043","midGrade":"3.637","premium":"4.000","diesel":"3.799"},{"currency":"usd","name":"Maryland","gasoline":"3.310","midGrade":"3.857","premium":"4.148","diesel":"3.851"},{"currency":"usd","name":"Maine","gasoline":"3.082","midGrade":"3.620","premium":"4.063","diesel":"3.939"},{"currency":"usd","name":"Michigan","gasoline":"3.10…

您将实际使用的字段说明：

success: 表示请求状态的布尔值。
result: 价格对象数组。关键字段：
- name: 区域名称（例如，返回数据中的州或管辖区标签）。
- currency: 货币代码（此示例中的 usd）。
- gasoline, midGrade, premium, diesel: 价格作为字符串。除非您的使用另有说明，否则视为每加仑美元。

单位：数据使用美元，对于站点级别的详细信息，price_unit 报告为 dollars_per_gallon（请参见下面的站点数据响应）。在 JSON 中将值视为字符串，并在需要进行计算时转换为十进制。

2) 站点数据（GET）

请求 URL：

https://zylalabs.com/api/3927/gasoline-prices-api/24541/station-data

描述：返回特定站点的详细信息。您需要一个站点 ID（可以从获取价格端点数据中获得）。此处没有文档化的请求参数；使用您的 Bearer 令牌进行身份验证。

官方 cURL 示例（复制/粘贴）：

官方 JSON 响应（逐字）：

您将实际使用的字段说明：

data.station_id, data.name: 识别站点。
data.address, data.coordinates: 对于地图和逐步链接很有用。
data.currency: 美元。
data.price_unit: dollars_per_gallon，明确了价格列表中使用的单位。

使用 HttpClient 的 C# 集成

以下 C# 示例展示了如何使用所需参数调用价格，设置 Authorization: Bearer 头，并解析 JSON 以提取一些字段。这是一个控制台示例，您可以将其放入使用 System.Net.Http 和 System.Text.Json 的 .NET 项目中。

using System;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text.Json;
using System.Threading.Tasks;

class Program
{
private static readonly HttpClient http = new HttpClient();

static async Task Main()
{
// 端点和所需查询参数：zip 和 type
var url = "https://zylalabs.com/api/3927/gasoline-prices-api/4649/prices?zip=90001&type=regular";

// 身份验证：Bearer YOUR_API_KEY
http.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", "YOUR_API_KEY");

using var resp = await http.GetAsync(url);
resp.EnsureSuccessStatusCode();

var json = await resp.Content.ReadAsStringAsync();

// 最小解析：success + result 数组，包含 name/currency/gasoline/midGrade/premium/diesel
using var doc = JsonDocument.Parse(json);
var root = doc.RootElement;

bool success = root.GetProperty("success").GetBoolean();
if (!success)
{
Console.WriteLine("请求失败。");
return;
}

var results = root.GetProperty("result").EnumerateArray().ToList();

// 示例：查找加利福尼亚条目并打印常规汽油和柴油
var california = results.FirstOrDefault(e =>
e.TryGetProperty("name", out var n) && n.GetString() == "California");

if (california.ValueKind != JsonValueKind.Undefined)
{
string currency = california.GetProperty("currency").GetString();
string regular = california.GetProperty("gasoline").GetString();
string diesel = california.GetProperty("diesel").GetString();

Console.WriteLine($"加利福尼亚价格 - 常规：{regular} {currency}，柴油：{diesel} {currency}");
}
else
{
Console.WriteLine("未在结果中找到加利福尼亚条目。");
}
}
}

节省时间的说明：

每个 HttpClient 实例仅设置一次 Authorization 头。通过仅替换头值来轮换密钥。
示例 JSON 中的价格是字符串。转换为十进制以进行数学运算（例如，使用不变文化的 Decimal.Parse）以避免区域设置问题。
如果您重复显示相同的瓷砖，请按邮政编码和燃料类型缓存；API 提供的位置数据不会每秒更改。决定您自己的新鲜度策略。
配额是基于订阅的。如果您进行高流量的邮政编码扫描，请在应用逻辑中跟踪剩余调用。有关详细信息，请参见 API 页面。

快速 JavaScript 获取示例

对于测试或轻量级集成，这里有一个最小的 JS 代码片段调用相同的价格端点。保持相同的 Authorization 头和所需的查询参数。

async function getPrices() {
const url = "https://zylalabs.com/api/3927/gasoline-prices-api/4649/prices?zip=90001&type=regular";
const resp = await fetch(url, {
method: "GET",
headers: {
"Authorization": "Bearer YOUR_API_KEY"
}
});

if (!resp.ok) {
throw new Error(`HTTP ${resp.status}`);
}

const data = await resp.json();
if (!data.success) {
throw new Error("API 报告失败");
}

// 示例：列出名称 + 汽油以快速显示
data.result.forEach(item => {
console.log(`${item.name}: 常规 ${item.gasoline} ${item.currency}`);
});
}

getPrices().catch(console.error);

实际使用模式

基于邮政编码的价格查找以进行结账：通过按邮政编码提取常规或柴油价格并应用您的每英里模型来估算本地交付的燃料附加费。
路线规划 UI：通过邮政编码向用户显示靠近路标的价格快照。存储价格单位（dollars_per_gallon）以防止在多单位 UI 中显示错误。
预算仪表板：从结果数组中计算每个管辖区的平均值或最小/最大值以构建趋势卡。在聚合之前将价格字符串转换为数值类型。
站点详细信息：如果特定站点需要额外的上下文（地址/坐标），请调用站点数据以丰富卡片的位置信息和单位信息。

如何通过 AI 代理使用 MCP 调用

您可以通过将 AI 编码代理或 MCP 兼容客户端指向 Zyla 的 MCP 端点来调用相同的 Hub 端点：

MCP

在配置 MCP 客户端时，通过 apikey 查询参数提供您的 Zyla API 密钥：https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY。代理发出的调用在后台使用相同的 Authorization: Bearer 模型，因此相同的 URL 和所需的查询参数适用（例如，价格端点需要 zip 和 type）。这适用于支持 MCP 的工具，例如 Claude Code、Cursor 和 Windsurf。

错误处理、单位和配额

HTTP 错误：仅在适当时处理非 2xx 的重试。不要在不更改输入或身份验证的情况下重试 4xx。
API 状态标志：在解引用字段之前检查价格中的成功和站点数据中的状态以验证有效响应。
单位和货币：使用货币字段（usd/USD）和 price_unit（dollars_per_gallon）进行标记和转换。保持所有数学运算为数值类型，而不是字符串。
缓存：如果您的用户体验容忍轻微的陈旧性，请按（zip，type）键缓存以最小化调用并保持在您的订阅配额内。
访问模型：订阅 + 配额。首次体验通常提供 7 天的试用或 50 次请求以验证您的集成。没有免费计划。有关当前选项，请参见 API 列表页面。