|
| 1 | +# FIPE C# SDK |
| 2 | + |
| 3 | +[](https://github.com/fipe-api/csharp-sdk/actions/workflows/ci.yml) |
| 4 | + |
| 5 | +A .NET 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. |
| 6 | + |
| 7 | +Targets `netstandard2.0` — works on .NET Core, .NET 5+, and .NET Framework 4.6.2+. |
| 8 | + |
| 9 | +## Install |
| 10 | + |
| 11 | +```sh |
| 12 | +dotnet add package Fipe.Api.Br |
| 13 | +``` |
| 14 | + |
| 15 | +## Quick start |
| 16 | + |
| 17 | +```csharp |
| 18 | +using Fipe.Api.Br; |
| 19 | + |
| 20 | +var client = new FipeClient(); |
| 21 | + |
| 22 | +var brands = await client.GetBrandsAsync(VehicleType.Cars); |
| 23 | +foreach (var brand in brands) |
| 24 | +{ |
| 25 | + Console.WriteLine($"{brand.Code} {brand.Name}"); |
| 26 | +} |
| 27 | +``` |
| 28 | + |
| 29 | +Vehicle types: `VehicleType.Cars`, `VehicleType.Motorcycles`, `VehicleType.Trucks`. |
| 30 | + |
| 31 | +## Authentication |
| 32 | + |
| 33 | +The free tier works without a token but is rate limited. With a subscription token: |
| 34 | + |
| 35 | +```csharp |
| 36 | +var client = new FipeClient(subscriptionToken: "your-token"); |
| 37 | +``` |
| 38 | + |
| 39 | +In DI scenarios, pass an `HttpClient` from `IHttpClientFactory`: |
| 40 | + |
| 41 | +```csharp |
| 42 | +services.AddHttpClient<FipeClient>(); |
| 43 | +// or |
| 44 | +var client = new FipeClient(httpClientFactory.CreateClient(), subscriptionToken: "your-token"); |
| 45 | +``` |
| 46 | + |
| 47 | +## Endpoints |
| 48 | + |
| 49 | +Drill down brand → model → year → price: |
| 50 | + |
| 51 | +```csharp |
| 52 | +var brands = await client.GetBrandsAsync(VehicleType.Cars); // GET /cars/brands |
| 53 | +var models = await client.GetModelsAsync(VehicleType.Cars, "59"); // GET /cars/brands/59/models |
| 54 | +var years = await client.GetYearsAsync(VehicleType.Cars, "59", "5940"); // GET /cars/brands/59/models/5940/years |
| 55 | +var vehicle = await client.GetVehicleAsync(VehicleType.Cars, "59", "5940", "2014-3"); // GET /cars/brands/59/models/5940/years/2014-3 |
| 56 | +
|
| 57 | +Console.WriteLine($"{vehicle.Model}: {vehicle.Price}"); |
| 58 | +``` |
| 59 | + |
| 60 | +Browse by year: |
| 61 | + |
| 62 | +```csharp |
| 63 | +var years = await client.GetYearsByBrandAsync(VehicleType.Cars, "59"); // GET /cars/brands/59/years |
| 64 | +var models = await client.GetModelsByBrandYearAsync(VehicleType.Cars, "59", "2014-3"); // GET /cars/brands/59/years/2014-3/models |
| 65 | +``` |
| 66 | + |
| 67 | +Look up by FIPE code: |
| 68 | + |
| 69 | +```csharp |
| 70 | +var years = await client.GetYearsByFipeCodeAsync(VehicleType.Cars, "005340-6"); // GET /cars/005340-6/years |
| 71 | +var vehicle = await client.GetVehicleByFipeCodeAsync(VehicleType.Cars, "005340-6", "2014-3"); // GET /cars/005340-6/years/2014-3 |
| 72 | +var history = await client.GetHistoryByFipeCodeAsync(VehicleType.Cars, "005340-6", "2014-3"); // GET /cars/005340-6/years/2014-3/history |
| 73 | +
|
| 74 | +foreach (var entry in history.PriceHistory) |
| 75 | +{ |
| 76 | + Console.WriteLine($"{entry.Month}: {entry.Price}"); |
| 77 | +} |
| 78 | +``` |
| 79 | + |
| 80 | +### Reference months |
| 81 | + |
| 82 | +Prices are published per monthly reference table. Every endpoint accepts an optional `reference` to query a past table: |
| 83 | + |
| 84 | +```csharp |
| 85 | +var references = await client.GetReferencesAsync(); // GET /references — e.g. Code "308", Month "abril de 2024" |
| 86 | +
|
| 87 | +var brands = await client.GetBrandsAsync(VehicleType.Cars, reference: 308); |
| 88 | +``` |
| 89 | + |
| 90 | +## Error handling |
| 91 | + |
| 92 | +Non-success responses throw `FipeApiException` with the status code and body: |
| 93 | + |
| 94 | +```csharp |
| 95 | +try |
| 96 | +{ |
| 97 | + var vehicle = await client.GetVehicleAsync(VehicleType.Cars, "59", "5940", "1900-1"); |
| 98 | +} |
| 99 | +catch (FipeApiException ex) when (ex.IsNotFound) |
| 100 | +{ |
| 101 | + // unknown brand/model/year |
| 102 | +} |
| 103 | +catch (FipeApiException ex) when (ex.IsRateLimited) |
| 104 | +{ |
| 105 | + // rate limited — back off or use a subscription token |
| 106 | +} |
| 107 | +catch (FipeApiException ex) |
| 108 | +{ |
| 109 | + Console.WriteLine($"API returned {(int)ex.StatusCode}: {ex.Body}"); |
| 110 | +} |
| 111 | +``` |
| 112 | + |
| 113 | +## Example program |
| 114 | + |
| 115 | +A runnable example that lists brands and prints an Amarok price from the live API: |
| 116 | + |
| 117 | +```sh |
| 118 | +dotnet run --project examples/Fipe.Examples |
| 119 | +``` |
| 120 | + |
| 121 | +## License |
| 122 | + |
| 123 | +MIT |
0 commit comments