README.md

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 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 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, so check the package compatibility before use it.

😎 Get Started

Well, you can download the code and build it by yourself or you can install by Nuget package in: CoreZipCode Package.

Just in case if you doesn't want leave GitHub at this moment:

dotnet add package CoreZipCode

After you decide how you'll get the CoreZipCode, just inject (e.g.: Simple Injector) and use it.

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<ViaCepAddress>("14810100");
            var zipCodeByAddressObjectList = _coreZipCode.ListAddresses<ViaCepAddress>("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<ViaCepAddress>("14810100");
            var zipCodeByAddressObjectList = await _coreZipCode.ListAddressesAsync<ViaCepAddress>("sp", "araraquara", "barão do rio");
        }
    }
}

The ViaCepAddress POCO class is the type for returned JSON from ViaCep 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:

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).

✔️ Available Services

Below a list of available services out-of-the-box address by zipcode lookup services.

Service	Country	Queries Limit
ViaCep	Brazil	300 by 15 minutes
Smarty	USA	250 by month

Below a list of available services out-of-the-box postcodes lookup services.

Service	Country	Queries Limit
Postcodes	United Kingdom	Unknown
Postal Pin Code	India	Unknown

👷 Contributing

Thank you for considering contributing to the CodeZipCore! Just see our Contributing Guide.

😇 Code of Conduct

In order to ensure that the CodeZipCore community is welcoming to all, please review and abide by the Code of Conduct.

🚨 Security Vulnerabilities

If you discover any security vulnerability within CoreZipCode, please create a vulnerability issue. All security vulnerabilities will be promptly addressed.

📜 License

The CoreZipCode is open-sourced software licensed under the MIT license.