👁 Image
ViaCep 5.0.1

ViaCEP SDK .NET

A .NET client wrapper for both .NET Core & .NET Framework projects of Via CEP API

👁 GitHub license
👁 time tracker

👁 Via CEP

CI/CD

Code Quality

👁 Codacy Badge
👁 Codacy Badge

👁 codecov
👁 CodeFactor

👁 Maintainability
👁 Test Coverage

👁 Quality Gate Status
👁 Maintainability Rating

👁 Technical Debt
👁 Duplicated Lines (%)

👁 Reliability Rating
👁 Security Rating

👁 Bugs
👁 Vulnerabilities

👁 DeepSource

Installation

Github Releases

👁 GitHub last release
👁 GitHub All Releases

Download the latest zip file from the Release page.

Nuget package manager

Usage

The package has two classes:

• ViaCepClient: The main class (methods).
• ViaCepResult: The result class (data).

This package is fully compatible with Dependency Injection. Use the interface IViaCepClient and the constructor with an HttpClient parameter and an IHttpClientFactory instance.

//your DI container
services.AddHttpClient<IViaCepClient, ViaCepClient>(client => { client.BaseAddress = new Uri("https://viacep.com.br/"); });

//then use in your domain service, handler, controller...
var viaCepClient = container.GetService<IViaCepClient>();
var result = await viaCepClient.SearchAsync("01001000", cancellationToken);

You can search using the zip code/postal code (AKA CEP) or the address data (state initials - UF, city name, and location name - street, avenue, park, square). Both methods support async and sync!

Querying by zip code / postal code (single result)

var result = new ViaCepClient().Search("01001000"); //searches for the postal code 01001-000
var address = result.Address; //Praça da Sé
var city = reuslt.City; //São Paulo
//do what you need with 'result' instance of ViaCEPResult.

Querying by address (list result)

var results = new ViaCepClient().Search("SP", "São Paulo", "Avenida Paulista"); //search for the Avenida Paulista in São Paulo / SP
foreach(var result in results){
 var address = result.Address;
 var neighborhood = result.Neighborhood;
 var zipCode = result.ZipCode;
 //do what you need with 'result' instance of ViaCEPResult.
}

Changelog

• 2024-09-02: Add explicit support to .NET 6.0 and .NET 8.0 #154 by @guibranco
• 2023-07-28: Add integration tests #71 by @Riju-bak
• 2023-03-03: Update dependencies, change branch name, update logo. @guibranco
• 2021-06-21: Update dependencies version. @guibranco
• 2020-10-23: Support .NET Standard 2.0 and .NET Framework v4.6.1 and above. @guibranco