https://github.com/guibranco/viacep
🇧🇷 📍 ViaCEP client wrapper for .NET projects
https://github.com/guibranco/viacep
address api cep code correios fazenda gia hacktoberfest ibge mf postal postalcode viacep webservice ws zip zipcode
Last synced: 7 months ago
JSON representation
🇧🇷 📍 ViaCEP client wrapper for .NET projects
- Host: GitHub
- URL: https://github.com/guibranco/viacep
- Owner: guibranco
- License: mit
- Created: 2019-02-14T14:57:13.000Z (almost 7 years ago)
- Default Branch: main
- Last Pushed: 2025-02-10T23:41:55.000Z (9 months ago)
- Last Synced: 2025-03-27T23:32:56.714Z (8 months ago)
- Topics: address, api, cep, code, correios, fazenda, gia, hacktoberfest, ibge, mf, postal, postalcode, viacep, webservice, ws, zip, zipcode
- Language: C#
- Homepage: http://guilherme.stracini.com.br/ViaCEP/
- Size: 434 KB
- Stars: 35
- Watchers: 1
- Forks: 11
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ViaCEP SDK .NET
A .NET client wrapper for both .NET Core & .NET Framework projects of [Via CEP API](https://viacep.com.br)
[](https://github.com/guibranco/ViaCep)
[](https://wakatime.com/badge/github/guibranco/ViaCEP)
## CI/CD
| Build status | Last commit | Tests | Coverage | Code Smells | LOC |
|--------------|-------------|-------|----------|-------------|-----|
| [](https://ci.appveyor.com/project/guibranco/ViaCEP) | [](https://github.com/guibranco/ViaCEP) | [](https://ci.appveyor.com/project/guibranco/ViaCEP) | [](https://sonarcloud.io/dashboard?id=guibranco_ViaCEP) | [](https://sonarcloud.io/dashboard?id=guibranco_ViaCEP) | [](https://sonarcloud.io/dashboard?id=guibranco_ViaCEP)
## Code Quality
[](https://www.codacy.com/gh/guibranco/ViaCEP/dashboard?utm_source=github.com\&utm_medium=referral\&utm_content=guibranco/ViaCEP\&utm_campaign=Badge_Grade)
[](https://www.codacy.com/gh/guibranco/ViaCEP/dashboard?utm_source=github.com\&utm_medium=referral\&utm_content=guibranco/ViaCEP\&utm_campaign=Badge_Grade)
[](https://codecov.io/gh/guibranco/ViaCEP)
[](https://www.codefactor.io/repository/github/guibranco/ViaCEP)
[](https://codeclimate.com/github/guibranco/ViaCEP/maintainability)
[](https://codeclimate.com/github/guibranco/ViaCEP/test_coverage)
[](https://sonarcloud.io/dashboard?id=guibranco_ViaCEP)
[](https://sonarcloud.io/dashboard?id=guibranco_ViaCEP)
[](https://sonarcloud.io/dashboard?id=guibranco_ViaCEP)
[](https://sonarcloud.io/dashboard?id=guibranco_ViaCEP)
[](https://sonarcloud.io/dashboard?id=guibranco_ViaCEP)
[](https://sonarcloud.io/dashboard?id=guibranco_ViaCEP)
[](https://sonarcloud.io/dashboard?id=guibranco_ViaCEP)
[](https://sonarcloud.io/dashboard?id=guibranco_ViaCEP)
[](https://app.deepsource.com/gh/guibranco/ViaCEP/?ref=repository-badge)
---
## Installation
### Github Releases
[](https://github.com/guibranco/ViaCEP) [](https://github.com/guibranco/ViaCEP)
Download the latest zip file from the [Release](https://github.com/GuiBranco/ViaCEP/releases) page.
### Nuget package manager
| Package | Version | Downloads |
|------------------|:-------:|:-------:|
| **ViaCEP** | [](https://www.nuget.org/packages/ViaCEP/) | [](https://www.nuget.org/packages/ViaCEP/) |
---
## Usage
The package has two classes:
* [ViaCepClient](https://github.com/guibranco/ViaCEP/blob/main/ViaCEP/ViaCepClient.cs): The main class (methods).
* [ViaCepResult](https://github.com/guibranco/ViaCEP/blob/main/ViaCEP/ViaCepResult.cs): 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.
```cs
//your DI container
services.AddHttpClient(client => { client.BaseAddress = new Uri("https://viacep.com.br/"); });
//then use in your domain service, handler, controller...
var viaCepClient = container.GetService();
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)
```cs
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)
```cs
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 explicitly support to .NET 6.0 and .NET 8.0 [#154](https://github.com/guibranco/ViaCEP/issues/154) by [@guibranco](https://github.com/guibranco)
* 2023-07-28: Add integration tests [#71](https://github.com/guibranco/ViaCEP/issues/71) by [@Riju-bak](https://github.com/Riju-bak)
* 2023-03-03: Update dependencies, change branch name, update logo. [@guibranco](https://github.com/guibranco)
* 2021-06-21: Update dependencies version. [@guibranco](https://github.com/guibranco)
* 2020-10-23: Support .NET Standard 2.0 and .NET Framework v4.6.1 and above. [@guibranco](https://github.com/guibranco)