---
title: "Obtém o preço expandido de um veículo"
method: GET
path: "/v1/prices/expanded"
tags: ["Preços"]
---

# Obtém o preço expandido de um veículo

`GET /v1/prices/expanded`

## Request

- Base URL: `https://api.fipex.com.br`
- URL: `https://api.fipex.com.br/v1/prices/expanded`
- Auth: none declared

Obtém dados de preço abrangentes, incluindo análises, histórico e anos disponíveis.
Usa os mesmos parâmetros de `/v1/prices`, mas retorna informações expandidas.

Se o histórico de preços não for encontrado, retorna 404 (não 200-vazio).

## Query parameters

- `model_id` string, uuid
- `fuel_id` string, uuid
- `model_slug` string
- `fuel_acronym` string
- `year` union, required
  - integer
  - 'zero'
- `ref_id` string, uuid
- `ref_date` string

## Response `200`

Dados de preço expandidos obtidos com sucesso.

- ExpandedPriceResponse
  - `data` ExpandedPriceData, required
    - `price` VehicleDetailedPrice, required: Dados de preço detalhados de um veículo. Campo condicional (oneof): `model_year` ou `is_zero_km`. O campo `price_cents` é em centavos (uint32).
      - `price_cents` integer: Preço em centavos (uint32).
      - `formatted_price` string: Preço formatado para leitura humana.
      - `model_year` integer: Ano do modelo (oneof com is_zero_km).
      - `is_zero_km` boolean: Indica veículo zero km (oneof com model_year).
      - `query_date` string, date-time: Data da consulta do preço.
      - `make` Make: Marca (fabricante) de veículos.
        - `id` string, uuid, required
        - `name` string, required: Nome da marca (ex: "Honda").
        - `slug` string, required: Identificador em formato slug (ex: "honda").
      - `model` SimplifiedModel: Modelo de veículo em forma reduzida — sem relações aninhadas, apenas o `make_id`.
        - `id` string, uuid, required
        - `name` string, required: Nome do modelo.
        - `make_id` string, uuid, required: UUID da marca à qual o modelo pertence.
        - `slug` string, required: Identificador do modelo em formato slug.
      - `fuel` Fuel: Combustível. Não possui campo `slug` no proto.
        - `id` string, uuid, required
        - `acronym` string, required: Acrônimo do combustível (ex. "g", "e", "d").
        - `name` string, required
      - `type` VehicleType: Tipo de veículo (carro, motocicleta ou caminhão).
        - `id` string, uuid, required
        - `name` string, required: Nome legível (ex: "Carros").
        - `slug` string, required: Identificador em formato slug (ex: "carros").
      - `reference` ReferencePeriod: Período de referência mensal de uma tabela FIPE.
        - `id` string, uuid, required
        - `month` integer, required: Mês de referência (1-12).
        - `month_name` string, required: Nome do mês por extenso (ex: "Junho").
        - `year` integer, required: Ano de referência.
        - `price_count` integer, required: Quantidade de preços publicados nesta referência (estoque).
        - `added` integer, nullable: Combinações veículo/ano/combustível presentes nesta referência e ausentes na referência anterior (fluxo). Ausente (null) na referência mais antiga do dataset, que não tem antecessora — nesse caso o valor nunca é 0.
        - `removed` integer, nullable: Combinações veículo/ano/combustível presentes na referência anterior e ausentes nesta (fluxo). Ausente (null) na referência mais antiga do dataset, que não tem antecessora — nesse caso o valor nunca é 0.
        - `fipe_id` integer, required: Número de sequência de publicação da própria FIPE. Chave monotônica que ordena as referências (prefira-a a tuplas (year, month)).
      - `fipe_code` string: Código FIPE público, ex: "811049-7".
      - `body_type_id` string: ID da carroceria (vazio se não classificado).
      - `body_type_name` string: Nome da carroceria.
      - `body_type_slug` string: Slug da carroceria.
    - `analytics` VehicleAnalytics, required: Métricas analíticas de um veículo. Campos nullable usam wrapper JSON (null quando ausente).
      - `change_from_previous_month_pct` number, float, nullable: Variação percentual de preço em relação ao mês anterior. Ausente quando não há mês anterior (ex. veículo recém-adicionado à tabela FIPE).
      - `change_from_launch_pct` number, float, nullable: Variação percentual de preço desde o lançamento. Ausente quando indisponível.
      - `peak_to_now_pct_change` number, float, nullable: Variação percentual do pico histórico até o preço atual. Ausente quando indisponível.
      - `price_volatility` number, float, nullable: Índice de volatilidade de preço (não é uma porcentagem).
      - `price_rank` integer, nullable: Ranking de preço dentro da categoria.
      - `price_rank_total_in_category` integer, nullable: Total de itens na categoria de ranking de preço.
      - `value_retention_pct` number, float, nullable: Percentual do valor original retido.
      - `annual_depreciation_rate` number, float, nullable: Taxa média de depreciação anual.
      - `lifecycle_status` string: Status atual do mercado (ex. 'active', 'discontinued'). Ausente quando indisponível.
      - `anomaly_status` string, nullable: Status de anomalia de preço (ex. 'normal', 'moderate_outlier').
      - `anomaly_z_score` number, float, nullable: Z-score estatístico do preço atual. Valores > 2 ou < -2 são significativos.
    - `history` VehiclePriceSnapshot[], required
      - `year` integer, required
      - `month` integer, required
      - `market_price_cents` integer, required: Preço de mercado em centavos.
      - `formatted_price` string, required
      - `cohort_median_cents` integer, nullable: Mediana de preço da coorte de veículos comparáveis, em centavos. Definido apenas em `/v1/prices/expanded`; nulo quando indisponível.
    - `available_years` YearOption[], required
      - `value` string, required: Seletor canônico do ano. `"2020"` para um ano-modelo, `"zero"` para um veículo 0km/novo. Use este valor em `year=` nos endpoints de preço.
      - `is_zero_km` boolean, required: `true` quando a opção é o veículo 0km/novo (`value == "zero"`); `false` para um ano-modelo concreto. Discriminador para ordenar e rotular sem precisar interpretar `value`.
    - `name_history` VehicleNameHistoryEntry[], required: Histórico de nomes sob os quais o veículo foi publicado na FIPE ao longo do tempo.
      - `name` string, required: Nome de exibição como a FIPE o publicou neste período.
      - `fipe_code` string, required: Código FIPE sob o qual o veículo apareceu com este nome.
      - `first_ref` ReferencePeriod, required: Período de referência mensal de uma tabela FIPE.
        - `id` string, uuid, required
        - `month` integer, required: Mês de referência (1-12).
        - `month_name` string, required: Nome do mês por extenso (ex: "Junho").
        - `year` integer, required: Ano de referência.
        - `price_count` integer, required: Quantidade de preços publicados nesta referência (estoque).
        - `added` integer, nullable: Combinações veículo/ano/combustível presentes nesta referência e ausentes na referência anterior (fluxo). Ausente (null) na referência mais antiga do dataset, que não tem antecessora — nesse caso o valor nunca é 0.
        - `removed` integer, nullable: Combinações veículo/ano/combustível presentes na referência anterior e ausentes nesta (fluxo). Ausente (null) na referência mais antiga do dataset, que não tem antecessora — nesse caso o valor nunca é 0.
        - `fipe_id` integer, required: Número de sequência de publicação da própria FIPE. Chave monotônica que ordena as referências (prefira-a a tuplas (year, month)).
      - `last_ref` ReferencePeriod, required: Período de referência mensal de uma tabela FIPE.
        - `id` string, uuid, required
        - `month` integer, required: Mês de referência (1-12).
        - `month_name` string, required: Nome do mês por extenso (ex: "Junho").
        - `year` integer, required: Ano de referência.
        - `price_count` integer, required: Quantidade de preços publicados nesta referência (estoque).
        - `added` integer, nullable: Combinações veículo/ano/combustível presentes nesta referência e ausentes na referência anterior (fluxo). Ausente (null) na referência mais antiga do dataset, que não tem antecessora — nesse caso o valor nunca é 0.
        - `removed` integer, nullable: Combinações veículo/ano/combustível presentes na referência anterior e ausentes nesta (fluxo). Ausente (null) na referência mais antiga do dataset, que não tem antecessora — nesse caso o valor nunca é 0.
        - `fipe_id` integer, required: Número de sequência de publicação da própria FIPE. Chave monotônica que ordena as referências (prefira-a a tuplas (year, month)).
      - `is_current` boolean, required: `true` para o nome ainda vigente (o de `last_ref` mais recente).
      - `covers_viewed` boolean, required: `true` quando a variante ano/combustível consultada apareceu sob este nome.
    - `year_prices` YearPricePoint[], required: Preço mais recente por ano-modelo, com a variação mês a mês.
      - `year` YearOption, required: Representa um ano disponível para um modelo. Cada opção é auto-descritiva: `value` é o seletor canônico que pode ser enviado diretamente em `/v1/prices?year=<value>`.
        - `value` string, required: Seletor canônico do ano. `"2020"` para um ano-modelo, `"zero"` para um veículo 0km/novo. Use este valor em `year=` nos endpoints de preço.
        - `is_zero_km` boolean, required: `true` quando a opção é o veículo 0km/novo (`value == "zero"`); `false` para um ano-modelo concreto. Discriminador para ordenar e rotular sem precisar interpretar `value`.
      - `price_cents` integer, required: Preço mais recente do ano, em centavos.
      - `formatted_price` string, required
      - `change_from_previous_month_pct` number, float, nullable: Variação do último preço em relação ao mês anterior (fração, ex. `-0.012` = -1,2%). Nulo quando indisponível.
    - `brand_slug` string, required: Slug da marca de hub do veículo (`/v1/brands/{brand_slug}`), para breadcrumbs.
    - `brand_name` string, required
    - `family_slug` string, required: Slug da família de hub do veículo (`/v1/brands/{brand_slug}/families/{family_slug}`).
    - `family_name` string, required

## Other responses

- `400`: Erro de validação (400). Usado para TODOS os erros de validação — não há 422.
- `404`: Recurso não encontrado (404).
- `409`: Expectativa conflitante — múltiplas linhas retornadas onde era esperada apenas uma (409).
- `500`: Erro interno do servidor (500).

---

[API](https://skmtc.dev/fipex/apis/api-fipex.md) · [All operations](https://skmtc.dev/fipex/apis/api-fipex/llms.txt) · [OpenAPI document](https://skmtc.dev/fipex/apis/api-fipex/revisions/800eab7da73d?raw)