Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/danilolutz/corezipcode
.Net Core Zip/Postal Code Services Handler
https://github.com/danilolutz/corezipcode
csharp dotnetcore2 hacktoberfest hacktoberfest2020 nuget-package postalcode services zipcode
Last synced: 2 months ago
JSON representation
.Net Core Zip/Postal Code Services Handler
- Host: GitHub
- URL: https://github.com/danilolutz/corezipcode
- Owner: danilolutz
- License: mit
- Created: 2018-12-20T19:57:27.000Z (about 6 years ago)
- Default Branch: main
- Last Pushed: 2022-08-24T02:31:00.000Z (over 2 years ago)
- Last Synced: 2024-11-07T10:03:44.781Z (2 months ago)
- Topics: csharp, dotnetcore2, hacktoberfest, hacktoberfest2020, nuget-package, postalcode, services, zipcode
- Language: C#
- Homepage:
- Size: 177 KB
- Stars: 10
- Watchers: 5
- Forks: 3
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# 
[](https://github.com/danilolutz/CoreZipCode/actions/workflows/main.yml)
[](https://coveralls.io/github/danilolutz/CoreZipCode?branch=master)
[](https://www.codacy.com/gh/danilolutz/CoreZipCode/dashboard?utm_source=github.com&utm_medium=referral&utm_content=danilolutz/CoreZipCode&utm_campaign=Badge_Grade)
[](https://snyk.io/test/github/danilolutz/CoreZipCode/main)
[](https://www.nuget.org/packages/CoreZipCode/) [](https://opensource.org/licenses/MIT)
## CoreZipCode Overview
Normaly we must implement ZipCode or Postcode services every time in each new software we create. Well this package is for keep you [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) and eliminate the necessity to implement ZipCode or Postcode services over and over.
Also this package could be used for easily implements address services to yours [Microsoft .Net Core](https://dotnet.github.io/) based software.
And the **CoreZipCode** was designed to be easily extensible, and if you want, implement your own address services, you only must override the API calls methods.
We follow the [Semantic Versioning](https://semver.org), so check the package compatibility before use it.
## :sunglasses: Get Started
Well, you can download the code and build it by yourself or you can install by [Nuget](https://www.nuget.org) package in: [CoreZipCode Package](https://www.nuget.org/packages/CoreZipCode/).
Just in case if you doesn't want leave GitHub at this moment:
```bash
dotnet add package CoreZipCode
```
After you decide how you'll get the CoreZipCode, just inject (e.g.: [Simple Injector](https://simpleinjector.org/)) and use it.
```CSharp
using CoreZipCode.Interfaces;
namespace YourProject
{
public YourClass
{
private readonly ZipCodeBaseService _coreZipCode;
public YourClass(ZipCodeBaseService coreZipCode)
{
_coreZipCode = coreZipCode;
}
public void YourMethod()
{
var addressByZipCode = _coreZipCode.Execute("14810100");
var zipCodeByAddress = _coreZipCode.Execute("sp", "araraquara", "barão do rio");
// Generic type return was added in version 1.1.0
var addressByZipCodeObject = _coreZipCode.GetAddress("14810100");
var zipCodeByAddressObjectList = _coreZipCode.ListAddresses("sp", "araraquara", "barão do rio");
}
// Async methods introduced in 1.1.0
public async void YourMethodAsync()
{
var addressByZipCode = await _coreZipCode.ExecuteAsync("14810100");
var zipCodeByAddress = await _coreZipCode.ExecuteAsync("sp", "araraquara", "barão do rio");
// Generic type return.
var addressByZipCodeObject = await _coreZipCode.GetAddressAsync("14810100");
var zipCodeByAddressObjectList = await _coreZipCode.ListAddressesAsync("sp", "araraquara", "barão do rio");
}
}
}
```
The `ViaCepAddress` POCO class is the type for returned JSON from [ViaCep](https://viacep.com.br) brazilian service. So you will must to implement the POCO class for your new service.
### Extending CoreZipCode
Also you can extends `ZipCodeBaseService` abstract class and create your own implementation of your prefered address service. Like below:
```CSharp
using CoreZipCode.Interfaces;
namespace CoreZipCode.Services.YourService
{
public class YourService : ZipCodeBaseService
{
public override string SetZipCodeUrl(string zipcode)
{
// You can implement some validation method here.
return $"https://yourservice.com/{zipcode}/json/";
}
public override string SetZipCodeUrlBy(string state, string city, string street)
{
// You can implement some validation method here.
return $"https://yourservice.com/{state}/{city}/{street}/json/";
}
}
}
```
> **NOTE**: Same principles are used to extends postcode lookups (`PostCodeBaseService`).
## :heavy_check_mark: Available Services
Below a list of available services out-of-the-box **address by zipcode** lookup services.
| Service | Country | Queries Limit |
| :------------------------------------------ | :------ | :---------------- |
| [ViaCep](https://viacep.com.br) | Brazil | 300 by 15 minutes |
| [Smarty](https://www.smarty.com/) | USA | 250 by month |
Below a list of available services out-of-the-box **postcodes** lookup services.
| Service | Country | Queries Limit |
| :----------------------------------------- | :------------- | :------------ |
| [Postcodes](https://postcodes.io) | United Kingdom | Unknown |
| [Postal Pin Code](http://postalpincode.in) | India | Unknown |
## :construction_worker: Contributing
Thank you for considering contributing to the CodeZipCore! Just see our [Contributing Guide](.github/CONTRIBUTING.md).
### :innocent: Code of Conduct
In order to ensure that the CodeZipCore community is welcoming to all, please review and abide by the [Code of Conduct](.github/CODE_OF_CONDUCT.md).
## :rotating_light: Security Vulnerabilities
If you discover any security vulnerability within CoreZipCode, please [create a vulnerability issue](https://github.com/danilolutz/CoreZipCode/issues/new?labels=security%20vulnerabilities). All security vulnerabilities will be promptly addressed.
## :scroll: License
The CoreZipCode is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).