fipe

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 25, 2026 License: MIT Imports: 10 Imported by: 0

README

FIPE Go SDK

Go Reference Go Report Card CI

A zero-dependency Go client for the FIPE API (/api/v2), which provides average vehicle prices in the Brazilian market from Fundação Instituto de Pesquisas Econômicas (FIPE). Prices are updated monthly.

Install

go get github.com/fipe-api/go-sdk

Quick start

package main

import (
	"context"
	"fmt"
	"log"

	fipe "github.com/fipe-api/go-sdk"
)

func main() {
	client := fipe.New()
	ctx := context.Background()

	brands, err := client.Brands(ctx, fipe.Cars)
	if err != nil {
		log.Fatal(err)
	}
	for _, b := range brands {
		fmt.Println(b.Code, b.Name)
	}
}

Vehicle types: fipe.Cars, fipe.Motorcycles, fipe.Trucks.

Authentication

The free tier works without a token but is rate limited. With a subscription token, you can make more requests per minute:

client := fipe.New(fipe.WithSubscriptionToken("your-token"))

Other client options: fipe.WithHTTPClient(*http.Client), fipe.WithBaseURL(string).

Endpoints

Drill down brand → model → year → price:

brands, _ := client.Brands(ctx, fipe.Cars)                          // GET /cars/brands
models, _ := client.Models(ctx, fipe.Cars, "59")                    // GET /cars/brands/59/models
years, _  := client.Years(ctx, fipe.Cars, "59", "5940")             // GET /cars/brands/59/models/5940/years
vehicle, _ := client.Vehicle(ctx, fipe.Cars, "59", "5940", "2014-3") // GET /cars/brands/59/models/5940/years/2014-3

fmt.Println(vehicle.Model, vehicle.Price) // "AMAROK High.CD 2.0 16V TDI 4x4 Dies. Aut" "R$ 10.000,00"

Browse by year:

years, _  := client.YearsByBrand(ctx, fipe.Cars, "59")                    // GET /cars/brands/59/years
models, _ := client.ModelsByBrandYear(ctx, fipe.Cars, "59", "2014-3")     // GET /cars/brands/59/years/2014-3/models

Look up by FIPE code:

years, _   := client.YearsByFipeCode(ctx, fipe.Cars, "005340-6")                     // GET /cars/005340-6/years
vehicle, _ := client.VehicleByFipeCode(ctx, fipe.Cars, "005340-6", "2014-3")         // GET /cars/005340-6/years/2014-3
history, _ := client.HistoryByFipeCode(ctx, fipe.Cars, "005340-6", "2014-3")         // GET /cars/005340-6/years/2014-3/history

for _, h := range history.PriceHistory {
	fmt.Println(h.Month, h.Price)
}
Reference months

Prices are published per monthly reference table. Every endpoint accepts fipe.WithReference to query a past table:

refs, _ := client.References(ctx) // GET /references — e.g. {Code: "308", Month: "abril de 2024"}

brands, _ := client.Brands(ctx, fipe.Cars, fipe.WithReference(308))

Error handling

Non-2xx responses return an *fipe.APIError carrying the status code and body. 404 and 429 also match sentinel errors:

vehicle, err := client.Vehicle(ctx, fipe.Cars, "59", "5940", "1900-1")
switch {
case errors.Is(err, fipe.ErrNotFound):
	// unknown brand/model/year
case errors.Is(err, fipe.ErrTooManyRequests):
	// rate limited — back off or use a subscription token
case err != nil:
	var apiErr *fipe.APIError
	if errors.As(err, &apiErr) {
		log.Printf("API returned %d: %s", apiErr.StatusCode, apiErr.Body)
	}
}

Example program

A runnable example that lists brands and prints an Amarok price from the live API:

go run ./examples

License

MIT

Documentation

Overview

Package fipe is a client for the FIPE API (https://fipe.api.br), which provides average vehicle prices from Brazil's Tabela FIPE.

Index

Examples

Constants

View Source 
const DefaultBaseURL = "https://fipe.api.br/api/v2"

DefaultBaseURL is the production endpoint of the FIPE API.

Variables

View Source 
var (
	ErrNotFound        = errors.New("fipe: not found")
	ErrTooManyRequests = errors.New("fipe: too many requests")
)

Sentinel errors for common API failures. APIError unwraps to these, so callers can match with errors.Is regardless of which form they prefer.

Functions

This section is empty.

Types

type APIError 

type APIError struct {
	StatusCode int
	Body       string
}

APIError is returned when the API responds with a non-2xx status.

func (*APIError) Error 

func (e *APIError) Error() string

func (*APIError) Unwrap 

func (e *APIError) Unwrap() error

type Brand 

type Brand struct {
	Code string `json:"code"`
	Name string `json:"name"`
}

Brand is a vehicle manufacturer, e.g. "VW - VolksWagen".

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is a FIPE API client. Create one with New; the zero value is not usable.

func New 

func New(opts ...Option) *Client

New returns a Client configured with the given options.

Example 
package main

import (
	"context"
	"fmt"
	"log"

	fipe "github.com/fipe-api/go-sdk"
)

func main() {
	// The free tier needs no token; pass one for higher rate limits.
	client := fipe.New(fipe.WithSubscriptionToken("your-token"))

	brands, err := client.Brands(context.Background(), fipe.Cars)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(brands[0].Name)
}

func (*Client) Brands 

func (c *Client) Brands(ctx context.Context, vt VehicleType, opts ...RequestOption) ([]Brand, error)

Brands lists the brands available for a vehicle type.

Example 
package main

import (
	"context"
	"fmt"
	"log"

	fipe "github.com/fipe-api/go-sdk"
)

func main() {
	client := fipe.New()

	brands, err := client.Brands(context.Background(), fipe.Cars)
	if err != nil {
		log.Fatal(err)
	}
	for _, b := range brands {
		fmt.Println(b.Code, b.Name)
	}
}

func (*Client) HistoryByFipeCode 

func (c *Client) HistoryByFipeCode(ctx context.Context, vt VehicleType, fipeCode, yearID string, opts ...RequestOption) (*Vehicle, error)

HistoryByFipeCode returns the vehicle details including its price history across reference months.

Example 
package main

import (
	"context"
	"fmt"
	"log"

	fipe "github.com/fipe-api/go-sdk"
)

func main() {
	client := fipe.New()

	vehicle, err := client.HistoryByFipeCode(context.Background(), fipe.Cars, "005340-6", "2014-3")
	if err != nil {
		log.Fatal(err)
	}
	for _, h := range vehicle.PriceHistory {
		fmt.Println(h.Month, h.Price)
	}
}

func (*Client) Models 

func (c *Client) Models(ctx context.Context, vt VehicleType, brandID string, opts ...RequestOption) ([]Model, error)

Models lists the models of a brand.

func (*Client) ModelsByBrandYear 

func (c *Client) ModelsByBrandYear(ctx context.Context, vt VehicleType, brandID, yearID string, opts ...RequestOption) ([]Model, error)

ModelsByBrandYear lists the models of a brand available for a given year.

func (*Client) References 

func (c *Client) References(ctx context.Context) ([]Reference, error)

References lists the FIPE monthly reference tables, newest first.

func (*Client) Vehicle 

func (c *Client) Vehicle(ctx context.Context, vt VehicleType, brandID, modelID, yearID string, opts ...RequestOption) (*Vehicle, error)

Vehicle returns the FIPE price details for a brand, model and year.

Example 
package main

import (
	"context"
	"fmt"
	"log"

	fipe "github.com/fipe-api/go-sdk"
)

func main() {
	client := fipe.New()
	ctx := context.Background()

	// Drill down brand -> model -> year -> price.
	models, err := client.Models(ctx, fipe.Cars, "59")
	if err != nil {
		log.Fatal(err)
	}
	years, err := client.Years(ctx, fipe.Cars, "59", models[0].Code)
	if err != nil {
		log.Fatal(err)
	}
	vehicle, err := client.Vehicle(ctx, fipe.Cars, "59", models[0].Code, years[0].Code)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(vehicle.Model, vehicle.Price)
}

func (*Client) VehicleByFipeCode 

func (c *Client) VehicleByFipeCode(ctx context.Context, vt VehicleType, fipeCode, yearID string, opts ...RequestOption) (*Vehicle, error)

VehicleByFipeCode returns the FIPE price details for a vehicle by its FIPE code and year.

Example 
package main

import (
	"context"
	"errors"
	"fmt"
	"log"

	fipe "github.com/fipe-api/go-sdk"
)

func main() {
	client := fipe.New()

	vehicle, err := client.VehicleByFipeCode(context.Background(), fipe.Cars, "005340-6", "2014-3")
	if errors.Is(err, fipe.ErrNotFound) {
		log.Fatal("unknown FIPE code or year")
	} else if err != nil {
		log.Fatal(err)
	}
	fmt.Println(vehicle.Price, vehicle.ReferenceMonth)
}

func (*Client) Years 

func (c *Client) Years(ctx context.Context, vt VehicleType, brandID, modelID string, opts ...RequestOption) ([]Year, error)

Years lists the model-year variants of a model.

func (*Client) YearsByBrand 

func (c *Client) YearsByBrand(ctx context.Context, vt VehicleType, brandID string, opts ...RequestOption) ([]Year, error)

YearsByBrand lists all model years available for a brand.

func (*Client) YearsByFipeCode 

func (c *Client) YearsByFipeCode(ctx context.Context, vt VehicleType, fipeCode string, opts ...RequestOption) ([]Year, error)

YearsByFipeCode lists the model-year variants of a vehicle by its FIPE code (e.g. "005340-6").

type Model 

type Model struct {
	Code string `json:"code"`
	Name string `json:"name"`
}

Model is a vehicle model within a brand.

type Option 

type Option func(*Client)

Option configures a Client.

func WithBaseURL 

func WithBaseURL(u string) Option

WithBaseURL overrides the API base URL (e.g. for testing).

func WithHTTPClient 

func WithHTTPClient(hc *http.Client) Option

WithHTTPClient sets the *http.Client used for requests.

func WithSubscriptionToken 

func WithSubscriptionToken(token string) Option

WithSubscriptionToken sets the X-Subscription-Token header on every request. The free tier works without a token but has stricter rate limits.

type PriceHistory 

type PriceHistory struct {
	Month     string `json:"month"`
	Price     string `json:"price"`
	Reference string `json:"reference"`
}

PriceHistory is one entry of a vehicle's price across reference months.

type Reference 

type Reference struct {
	Code  string `json:"code"`
	Month string `json:"month"`
}

Reference is a FIPE monthly reference table. Prices are published per reference month; pass a Reference code via WithReference to query historical tables.

type RequestOption 

type RequestOption func(url.Values)

RequestOption configures a single API request.

func WithReference 

func WithReference(code int) RequestOption

WithReference queries a specific FIPE monthly reference table instead of the current one. Codes come from Client.References.

Example 
package main

import (
	"context"
	"fmt"
	"log"

	fipe "github.com/fipe-api/go-sdk"
)

func main() {
	client := fipe.New()
	ctx := context.Background()

	// Query prices from a past monthly reference table.
	refs, err := client.References(ctx)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("latest table:", refs[0].Month)

	brands, err := client.Brands(ctx, fipe.Cars, fipe.WithReference(308))
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(len(brands))
}

type Vehicle 

type Vehicle struct {
	Brand          string         `json:"brand"`
	CodeFipe       string         `json:"codeFipe"`
	Fuel           string         `json:"fuel"`
	FuelAcronym    string         `json:"fuelAcronym"`
	Model          string         `json:"model"`
	ModelYear      int            `json:"modelYear"`
	Price          string         `json:"price"`
	PriceHistory   []PriceHistory `json:"priceHistory,omitempty"`
	ReferenceMonth string         `json:"referenceMonth"`
	VehicleType    int            `json:"vehicleType"`
}

Vehicle holds the FIPE price details for a specific model year.

type VehicleType 

type VehicleType string

VehicleType identifies the category of vehicle being queried. 

const (
	Cars        VehicleType = "cars"
	Motorcycles VehicleType = "motorcycles"
	Trucks      VehicleType = "trucks"
)

type Year 

type Year struct {
	Code string `json:"code"`
	Name string `json:"name"`
}

Year is a model year variant. Code combines year and fuel, e.g. "2022-3".

Source Files

View all Source files

Directories

Path Synopsis
Command examples demonstrates the FIPE SDK against the live API: it lists car brands, drills into VW Amarok models and years, and prints the current FIPE price.
 Command examples demonstrates the FIPE SDK against the live API: it lists car brands, drills into VW Amarok models and years, and prints the current FIPE price.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.