referência da api · v1

Documentação

Uma API REST sobre a Tabela FIPE. Respostas em JSON, identificadores idênticos aos da própria FIPE e histórico mensal contínuo desde 2001.

Comece aqui

A URL base é https://fipedata.varella.ovh/api/v1. Todos os endpoints respondem GET e devolvem JSON com content-type: application/json.

curl -s "https://fipedata.varella.ovh/api/v1/cars/brands" | head -c 200
# [{"code":"1","name":"Acura"},{"code":"2","name":"Agrale"}, ...

Sem chave você já consegue chamar a API — o limite é de 500 requisições por dia por IP. Com uma conta gratuita o limite passa a 1.000 por dia.

Autenticação

Envie a chave no header Authorization. Também aceitamos o header x-api-key e o parâmetro ?token= para facilitar testes no navegador.

Authorization: Bearer fpd_live_xxxxxxxxxxxxxxxxxxxx

Chaves são criadas e revogadas no painel. Guardamos apenas o hash — se você perder a chave, gere outra.

Limites

Anônimo: 500 req/dia por IP, 60 req/min.
Free: 1.000 req/dia, 60 req/min, 3 referências mais recentes.
Pro (R$ 49,90/mês): sem cota diária, 300 req/min, histórico completo e downloads.

Toda resposta traz os headers de cota:

x-ratelimit-limit-minute: 60
x-ratelimit-remaining-minute: 58
x-ratelimit-limit-day: 1000
x-ratelimit-remaining-day: 991

Endpoints

{type} é cars (1), motorcycles (2) ou trucks (3). O parâmetro opcional ?reference= escolhe a referência mensal; sem ele, você recebe a mais recente.

GET/v1/references

Referências mensais disponíveis

Lista as tabelas mensais já carregadas, da mais nova para a mais antiga. Contas Free enxergam apenas as mais recentes.

[
  { "code": 305, "month": "maio de 2026", "year": 2026, "monthNumber": 5 },
  { "code": 304, "month": "abril de 2026", "year": 2026, "monthNumber": 4 }
]

GET/v1/{type}/brands

Marcas por tipo de veículo

Todas as marcas do segmento, ordenadas por nome. O campo code é o identificador oficial da FIPE.

[{ "code": "56", "name": "Toyota" }]

GET/v1/{type}/brands/{brandId}/models

Modelos de uma marca

Modelos da marca, com o código FIPE de cada um já incluído.

[{ "code": 9984, "name": "Corolla Altis 1.8 16V Aut. (Híbrido)", "codeFipe": "002182-2" }]

GET/v1/{type}/brands/{brandId}/models/{modelId}/years

Anos e combustíveis de um modelo

Combinações ano-combustível com preço na referência escolhida. O código segue o formato ano-combustível.

reference

Código da referência mensal (opcional).

[{ "code": "2025-6", "name": "2025 Híbrido" }]

GET/v1/{type}/brands/{brandId}/models/{modelId}/years/{yearId}

Preço de um veículo

O registro completo: preço formatado, preço numérico, código FIPE, combustível e a referência lida.

reference

Código da referência mensal (opcional).

{
  "price": "R$ 179.353,00",
  "priceNumeric": 179353,
  "brand": "Toyota",
  "model": "Corolla Altis 1.8 16V Aut. (Híbrido)",
  "modelYear": 2025,
  "fuel": "Híbrido",
  "fuelAcronym": "H",
  "codeFipe": "002182-2",
  "referenceMonth": "maio de 2026",
  "referenceCode": 305,
  "vehicleType": 1,
  "brandCode": 56,
  "modelCode": 9984
}

GET/v1/{type}/code/{codigoFipe}/years

Anos por código FIPE

Mesma lista de anos, mas partindo do código FIPE impresso no documento do veículo. Aceita 002182-2 ou 0021822.

GET/v1/{type}/code/{codigoFipe}/years/{yearId}

Preço por código FIPE

Atalho de uma chamada só quando você já tem o código FIPE — não precisa descobrir marca e modelo antes.

Histórico

GET/v1/{type}/code/{codigoFipe}/historypro

Série histórica de preços

Um ponto por referência mensal, com a variação percentual contra o mês anterior já calculada. Contas Free recebem as referências mais recentes; o Pro recebe a série inteira.

year	Obrigatório. Formato ano-combustível, ex.: 2025-6.

{
  "codeFipe": "002182-2",
  "year": 2025,
  "fuel": 6,
  "points": [
    { "referenceMonth": "maio de 2026", "priceNumeric": 179353, "variation": -0.34 },
    { "referenceMonth": "abril de 2026", "priceNumeric": 179960, "variation": 0.12 }
  ],
  "summary": { "months": 16, "totalVariation": -4.81 },
  "truncated": false,
  "availableMonths": 305
}

GET/v1/search

Busca por texto

Procura modelos por nome ou código FIPE. Útil para caixas de autocomplete.

q	Termo de busca, mínimo 2 caracteres.
type	cars \| motorcycles \| trucks (opcional).
limit	Máximo de resultados. 25 no Free, 100 no Pro.

Downloads

Além da API, cada referência mensal vira um pacote pronto para download nos formatos CSV, JSON Lines, SQLite, Parquet, Excel. Os arquivos são gerados no servidor logo após cada importação e publicam tamanho, número de linhas e SHA-256.

GET/v1/downloads

Catálogo de exportações

Lista todos os arquivos disponíveis. O catálogo é público; o download exige plano Pro.

GET/v1/downloads/{filename}pro

Baixar um arquivo

Retorna o arquivo com content-disposition de anexo e o hash SHA-256 no header x-fipedata-sha256.

Erros

Erros seguem sempre a mesma forma:

{ "error": { "code": "daily_quota_exceeded", "message": "...", "status": 429 } }

400 invalid_*	Parâmetro malformado — o campo problemático vem na mensagem.
402 history_locked	A referência pedida está fora da janela do plano Free.
402 plan_required	Recurso exclusivo do plano Pro (downloads).
404 *_not_found	Marca, modelo, ano, código FIPE ou referência inexistente.
429 rate_limited	Limite por minuto estourado. Respeite o header retry-after.
429 daily_quota_exceeded	Cota diária esgotada. Reinicia à meia-noite UTC.
503 no_data	Nenhuma tabela carregada — situação temporária de manutenção.

Migrar de outra API

Usamos os identificadores originais da FIPE, então marca 56 continua sendo Toyota e modelo 9984 continua sendo o Corolla Altis Híbrido. Os códigos de ano seguem o mesmo formato 2025-6, e o código FIPE é o mesmo 002182-2.

Na prática a migração é trocar a URL base e passar a enviar o header de autenticação:

- https://outra-api.com/api/v2/cars/brands/56/models
+ https://fipedata.varella.ovh/api/v1/cars/brands/56/models      # + Authorization: Bearer fpd_live_...

O objeto de preço mantém os campos brand, model, modelYear, fuel, codeFipe, referenceMonth e vehicleType, e acrescenta priceNumeric, referenceCode, brandCode e modelCode.