Integre a API de Preços de Gasolina em C# Usando o Zyla API Hub (Guia)

Você precisa enviar uma integração em C# que busque preços de combustíveis ao vivo por código postal, com unidades confiáveis e autenticação previsível. Ao final deste guia, você fará consultas à API de Preços de Gasolina no Zyla API Hub a partir de C#, analisará o JSON e estará pronto para integrar os dados ao seu checkout, painel de frota ou lógica de roteamento.

O que a API de Preços de Gasolina oferece

A API de Preços de Gasolina retorna informações sobre preços de combustíveis para postos de gasolina relevantes em um determinado código postal e suporta uma pesquisa de dados em nível de posto. É ideal para aplicações que precisam exibir ou comparar custos de combustíveis locais, calcular despesas de viagem ou manter orçamentos atualizados para logística e serviços em estrada.

Ilustração: Integre a API de Preços de Gasolina em C# Usando o Zyla API Hub (Guia)

O Zyla API Hub centraliza a autenticação (uma conta, uma chave de API) e a cobrança em mais de 10.000 APIs públicas. A API de Preços de Gasolina usa um token de Autorização: Bearer em cada solicitação e fornece acesso baseado em assinatura + cota (não pago por chamada). Para o primeiro uso, você recebe um teste de 7 dias ou 50 solicitações para validar sua integração. Não há Plano Gratuito; verifique a página da API para opções de acesso e preços atuais.

Começando no Zyla API Hub

Aqui está o processo mínimo para obter sua chave e chamar os endpoints:

Abra a lista de APIs: API de Preços de Gasolina.
Clique em Inscrever-se (ou Começar Teste Gratuito quando disponível) e complete o fluxo para obter sua chave de API.
Use a chave com um cabeçalho de Autorização: Bearer ao chamar os endpoints em https://zylalabs.com/api/…

Se você ainda não tem uma conta Zyla, pode criar uma rapidamente aqui: Registrar. Você também pode explorar outras categorias no Zyla API Hub a qualquer momento.

Endpoints que você usará

A API de Preços de Gasolina fornece dois endpoints documentados via Zyla API Hub:

1) Preços (GET)

URL da solicitação:

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

Descrição: Passe o código postal de sua escolha e o tipo de combustível que deseja verificar. A API retorna preços de postos de gasolina relevantes no código postal fornecido. Se não houver informações disponíveis para um posto, você pode usar seu ID no endpoint de Dados do Posto.

Parâmetros de consulta obrigatórios:

zip (string): exemplo 90001
type (string): exemplo regular

Autenticação: Autorização: Bearer SUA_CHAVE_API

Exemplo oficial de cURL (copiar/colar):

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

Resposta JSON oficial (verbatim):

{"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…

Notas de campo que você realmente usará:

success: booleano indicando o status da solicitação.
result: array de objetos de preço. Campos principais:
- name: nome da área (por exemplo, um estado ou rótulo de jurisdição nos dados retornados).
- currency: código da moeda (usd neste exemplo).
- gasoline, midGrade, premium, diesel: preços como strings. Trate como dólares por galão, a menos que seu uso especifique o contrário.

Unidades: Os dados usam USD e, para detalhes em nível de posto, price_unit relata dollars_per_gallon (veja a resposta de Dados do Posto abaixo). Trate valores como strings em JSON e converta para decimais quando necessário para cálculos.

2) Dados do Posto (GET)

URL da solicitação:

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

Descrição: Retorna detalhes para um posto específico. Você precisará de um ID de posto (obtido a partir dos dados do endpoint Obter Preços). Nenhum parâmetro de solicitação está documentado aqui; autentique-se com seu token Bearer.

Exemplo oficial de cURL (copiar/colar):

Resposta JSON oficial (verbatim):

Notas de campo que você realmente usará:

data.station_id, data.name: identificam o posto.
data.address, data.coordinates: úteis para mapas e links de navegação.
data.currency: USD.
data.price_unit: dollars_per_gallon, que esclarece a unidade usada nas listagens de preços.

Integração em C# com HttpClient

O seguinte exemplo em C# mostra como chamar Preços com os parâmetros obrigatórios, definir o cabeçalho de Autorização: Bearer e analisar o JSON para extrair alguns campos. Este é um exemplo de console que você pode inserir em um projeto .NET usando System.Net.Http e System.Text.Json.

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()
{
// Endpoint e parâmetros de consulta obrigatórios: zip e type
var url = "https://zylalabs.com/api/3927/gasoline-prices-api/4649/prices?zip=90001&type=regular";

// Auth: Bearer SUA_CHAVE_API
http.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", "SUA_CHAVE_API");

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

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

// Análise mínima: success + array de resultados com 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("A solicitação falhou.");
return;
}

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

// Exemplo: encontrar a entrada da Califórnia e imprimir gasolina regular e diesel
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($"Preços da Califórnia - Regular: {regular} {currency}, Diesel: {diesel} {currency}");
}
else
{
Console.WriteLine("Entrada da Califórnia não encontrada no resultado.");
}
}
}

Notas que economizam tempo:

Defina o cabeçalho de Autorização uma vez por instância do HttpClient. Rode a chave substituindo apenas o valor do cabeçalho.
Os preços no JSON de exemplo são strings. Converta para decimal para cálculos (por exemplo, Decimal.Parse com cultura invariável) para evitar problemas de localidade.
Cache por ZIP e tipo de combustível se você mostrar os mesmos blocos repetidamente; a API fornece dados baseados em localização que não mudam a cada segundo. Decida sua própria política de frescor.
As cotas são baseadas em assinatura. Acompanhe as chamadas restantes na lógica do seu aplicativo se você realizar varreduras de ZIP de alto tráfego. Veja a página da API para detalhes.

Exemplo rápido de fetch em JavaScript

Para testes ou integrações leves, aqui está um snippet mínimo de JS chamando o mesmo endpoint de Preços. Mantenha o mesmo cabeçalho de Autorização e os parâmetros de consulta obrigatórios.

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 SUA_CHAVE_API"
}
});

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

const data = await resp.json();
if (!data.success) {
throw new Error("A API relatou falha");
}

// Exemplo: listar nome + gasolina para exibição rápida
data.result.forEach(item => {
console.log(`${item.name}: Regular ${item.gasoline} ${item.currency}`);
});
}

getPrices().catch(console.error);

Padrões de uso práticos

Consulta de preço baseada em ZIP para checkout: Estime sobretaxas de combustível para entrega local puxando preços regulares ou diesel por ZIP e aplicando seu modelo por milha.
UI de planejamento de rotas: Mostre aos usuários uma captura de preço perto de pontos de passagem por ZIP. Armazene a unidade de preço (dollars_per_gallon) para evitar erros de exibição em UIs de múltiplas unidades.
Painéis orçamentários: Média ou min/max por jurisdição a partir do array de resultados para construir cartões de tendência. Converta strings de preço para tipos numéricos antes das agregações.
Detalhes do posto: Se um posto específico requer contexto extra (endereço/coordenadas), chame Dados do Posto para enriquecer o cartão com informações de localização e unidade.

Como chamar via agentes de IA usando MCP

Você pode invocar os mesmos endpoints do Hub a partir de agentes de codificação de IA ou clientes compatíveis com MCP, apontando-os para o endpoint MCP do Zyla:

MCP

Forneça sua chave de API Zyla com o parâmetro de consulta apikey ao configurar o cliente MCP: https://mcp.zylalabs.com/mcp?apikey=SUA_CHAVE_API. Chamadas feitas pelo agente usam o mesmo modelo de Autorização: Bearer nos bastidores, então as mesmas URLs e parâmetros de consulta obrigatórios se aplicam (por exemplo, o endpoint Preços requer zip e type). Isso funciona com ferramentas habilitadas para MCP, como Claude Code, Cursor e Windsurf.

Tratamento de erros, unidades e cotas

Erros HTTP: Trate não-2xx com tentativas apenas quando apropriado. Não tente novamente 4xx sem alterar entradas ou autenticação.
Flags de status da API: Verifique o sucesso em Preços e o status em Dados do Posto para verificar uma resposta válida antes de desreferenciar campos.
Unidades e moeda: Use o campo de moeda (usd/USD) e price_unit (dollars_per_gallon) para rotulagem e conversões. Mantenha toda a matemática em tipos numéricos, não strings.
Cache: Se sua UX tolera leve desatualização, faça cache por chaves (zip, type) para minimizar chamadas e manter dentro da sua cota de assinatura.
Modelo de acesso: Assinatura + cota. A experiência de primeira vez geralmente oferece um teste de 7 dias ou 50 solicitações para validar sua integração. Não há Plano Gratuito. Para opções atuais, veja a página de listagem da API.

Referência completa dos dois endpoints documentados

Preços

Método: GET
URL: https://zylalabs.com/api/3927/gasoline-prices-api/4649/prices
Parâmetros de consulta obrigatórios:
- zip: e.g., 90001
- type: e.g., regular
Auth: Autorização: Bearer SUA_CHAVE_API

Dados do Posto

Método: GET
URL: https://zylalabs.com/api/3927/gasoline-prices-api/24541/station-data
Parâmetros: Nenhum documentado aqui; este endpoint espera um contexto de ID de posto derivado dos dados de Preços.
Auth: Autorização: Bearer SUA_CHAVE_API

Perguntas Frequentes

Q1: Que autenticação é necessária?
A: Inclua Autorização: Bearer SUA_CHAVE_API em cada solicitação para as URLs do Zyla Hub.

Q2: Quais parâmetros são obrigatórios para o endpoint Preços?
A: zip e type são obrigatórios (exemplo: zip=90001 e type=regular).

Q3: Como obtenho detalhes do posto?
A: Use o endpoint Dados do Posto após identificar um ID de posto a partir dos dados de Preços. A chamada de Dados do Posto em si não documenta parâmetros de consulta; autentique-se com seu token Bearer.

Q4: Quais são as unidades e a moeda?
A: Os preços são reportados em USD; metadados em nível de posto especificam price_unit como dollars_per_gallon.

Q5: Como é tratado o faturamento?
A: Assinatura + cota no Zyla API Hub (não pago por chamada). Para o primeiro uso, você geralmente tem um teste de 7 dias ou 50 solicitações. Não há Plano Gratuito; verifique a página da API para opções atuais.

Pronto para implementar? Crie sua conta, obtenha sua chave e envie a integração esta semana. Comece aqui: Registrar. Você também pode navegar por mais APIs a qualquer momento no Zyla API Hub ou ir diretamente para a listagem da API de Preços de Gasolina.