first commit

Author: deividfortuna

.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: stable
+
+      - name: Check formatting
+        run: test -z "$(gofmt -l .)" || (gofmt -l . && exit 1)
+
+      - name: Vet
+        run: go vet ./...
+
+      - name: Build
+        run: go build ./...
+
+      - name: Test
+        run: go test -race ./...

.gitignore

@@ -0,0 +1,14 @@
+# Binaries and build output
+*.exe
+*.dll
+*.so
+*.dylib
+*.test
+*.out
+
+# Coverage
+coverage.*
+
+# IDE
+.idea/
+.vscode/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Deivid Fortuna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,125 @@
+# FIPE Go SDK
+
+[![Go Reference](https://pkg.go.dev/badge/github.com/fipe-api/go-sdk.svg)](https://pkg.go.dev/github.com/fipe-api/go-sdk)
+[![Go Report Card](https://goreportcard.com/badge/github.com/fipe-api/go-sdk)](https://goreportcard.com/report/github.com/fipe-api/go-sdk)
+[![CI](https://github.com/fipe-api/go-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/fipe-api/go-sdk/actions/workflows/ci.yml)
+
+A zero-dependency Go client for the [FIPE API](https://fipe.api.br) (`/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
+
+```sh
+go get github.com/fipe-api/go-sdk
+```
+
+## Quick start
+
+```go
+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](https://fipe.api.parallelum.com.br), you can make more requests per minute:
+
+```go
+client := fipe.New(fipe.WithSubscriptionToken("your-token"))
+```
+
+Other client options: `fipe.WithHTTPClient(*http.Client)`, `fipe.WithBaseURL(string)`.
+
+## Endpoints
+
+Drill down brand → model → year → price:
+
+```go
+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:
+
+```go
+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:
+
+```go
+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:
+
+```go
+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:
+
+```go
+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:
+
+```sh
+go run ./examples
+```
+
+## License
+
+MIT

endpoints.go

@@ -0,0 +1,109 @@
+package fipe
+
+import (
+	"context"
+	"fmt"
+	"net/url"
+)
+
+// References lists the FIPE monthly reference tables, newest first.
+func (c *Client) References(ctx context.Context) ([]Reference, error) {
+	var out []Reference
+	if err := c.get(ctx, "/references", &out); err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+// Brands lists the brands available for a vehicle type.
+func (c *Client) Brands(ctx context.Context, vt VehicleType, opts ...RequestOption) ([]Brand, error) {
+	var out []Brand
+	path := fmt.Sprintf("/%s/brands", vt)
+	if err := c.get(ctx, path, &out, opts...); err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+// Models lists the models of a brand.
+func (c *Client) Models(ctx context.Context, vt VehicleType, brandID string, opts ...RequestOption) ([]Model, error) {
+	var out []Model
+	path := fmt.Sprintf("/%s/brands/%s/models", vt, url.PathEscape(brandID))
+	if err := c.get(ctx, path, &out, opts...); err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+// Years lists the model-year variants of a model.
+func (c *Client) Years(ctx context.Context, vt VehicleType, brandID, modelID string, opts ...RequestOption) ([]Year, error) {
+	var out []Year
+	path := fmt.Sprintf("/%s/brands/%s/models/%s/years", vt, url.PathEscape(brandID), url.PathEscape(modelID))
+	if err := c.get(ctx, path, &out, opts...); err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+// Vehicle returns the FIPE price details for a brand, model and year.
+func (c *Client) Vehicle(ctx context.Context, vt VehicleType, brandID, modelID, yearID string, opts ...RequestOption) (*Vehicle, error) {
+	var out Vehicle
+	path := fmt.Sprintf("/%s/brands/%s/models/%s/years/%s", vt, url.PathEscape(brandID), url.PathEscape(modelID), url.PathEscape(yearID))
+	if err := c.get(ctx, path, &out, opts...); err != nil {
+		return nil, err
+	}
+	return &out, nil
+}
+
+// YearsByBrand lists all model years available for a brand.
+func (c *Client) YearsByBrand(ctx context.Context, vt VehicleType, brandID string, opts ...RequestOption) ([]Year, error) {
+	var out []Year
+	path := fmt.Sprintf("/%s/brands/%s/years", vt, url.PathEscape(brandID))
+	if err := c.get(ctx, path, &out, opts...); err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+// ModelsByBrandYear lists the models of a brand available for a given year.
+func (c *Client) ModelsByBrandYear(ctx context.Context, vt VehicleType, brandID, yearID string, opts ...RequestOption) ([]Model, error) {
+	var out []Model
+	path := fmt.Sprintf("/%s/brands/%s/years/%s/models", vt, url.PathEscape(brandID), url.PathEscape(yearID))
+	if err := c.get(ctx, path, &out, opts...); err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+// YearsByFipeCode lists the model-year variants of a vehicle by its FIPE code
+// (e.g. "005340-6").
+func (c *Client) YearsByFipeCode(ctx context.Context, vt VehicleType, fipeCode string, opts ...RequestOption) ([]Year, error) {
+	var out []Year
+	path := fmt.Sprintf("/%s/%s/years", vt, url.PathEscape(fipeCode))
+	if err := c.get(ctx, path, &out, opts...); err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+// VehicleByFipeCode returns the FIPE price details for a vehicle by its FIPE
+// code and year.
+func (c *Client) VehicleByFipeCode(ctx context.Context, vt VehicleType, fipeCode, yearID string, opts ...RequestOption) (*Vehicle, error) {
+	var out Vehicle
+	path := fmt.Sprintf("/%s/%s/years/%s", vt, url.PathEscape(fipeCode), url.PathEscape(yearID))
+	if err := c.get(ctx, path, &out, opts...); err != nil {
+		return nil, err
+	}
+	return &out, nil
+}
+
+// HistoryByFipeCode returns the vehicle details including its price history
+// across reference months.
+func (c *Client) HistoryByFipeCode(ctx context.Context, vt VehicleType, fipeCode, yearID string, opts ...RequestOption) (*Vehicle, error) {
+	var out Vehicle
+	path := fmt.Sprintf("/%s/%s/years/%s/history", vt, url.PathEscape(fipeCode), url.PathEscape(yearID))
+	if err := c.get(ctx, path, &out, opts...); err != nil {
+		return nil, err
+	}
+	return &out, nil
+}

errors.go

@@ -0,0 +1,37 @@
+package fipe
+
+import (
+	"errors"
+	"fmt"
+	"net/http"
+)
+
+// Sentinel errors for common API failures. APIError unwraps to these, so
+// callers can match with errors.Is regardless of which form they prefer.
+var (
+	ErrNotFound        = errors.New("fipe: not found")
+	ErrTooManyRequests = errors.New("fipe: too many requests")
+)
+
+// APIError is returned when the API responds with a non-2xx status.
+type APIError struct {
+	StatusCode int
+	Body       string
+}
+
+func (e *APIError) Error() string {
+	if e.Body != "" {
+		return fmt.Sprintf("fipe: unexpected status %d: %s", e.StatusCode, e.Body)
+	}
+	return fmt.Sprintf("fipe: unexpected status %d", e.StatusCode)
+}
+
+func (e *APIError) Unwrap() error {
+	switch e.StatusCode {
+	case http.StatusNotFound:
+		return ErrNotFound
+	case http.StatusTooManyRequests:
+		return ErrTooManyRequests
+	}
+	return nil
+}