{"id":15011710,"url":"https://github.com/danilolutz/corezipcode","last_synced_at":"2025-04-12T03:32:05.629Z","repository":{"id":33825567,"uuid":"162625582","full_name":"danilolutz/CoreZipCode","owner":"danilolutz","description":".Net Core Zip/Postal Code Services Handler","archived":false,"fork":false,"pushed_at":"2022-08-24T02:31:00.000Z","size":181,"stargazers_count":11,"open_issues_count":2,"forks_count":3,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-09T21:42:15.077Z","etag":null,"topics":["csharp","dotnetcore2","hacktoberfest","hacktoberfest2020","nuget-package","postalcode","services","zipcode"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/danilolutz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-12-20T19:57:27.000Z","updated_at":"2025-01-13T18:48:47.000Z","dependencies_parsed_at":"2022-08-26T21:41:52.616Z","dependency_job_id":null,"html_url":"https://github.com/danilolutz/CoreZipCode","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danilolutz%2FCoreZipCode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danilolutz%2FCoreZipCode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danilolutz%2FCoreZipCode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danilolutz%2FCoreZipCode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/danilolutz","download_url":"https://codeload.github.com/danilolutz/CoreZipCode/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248512835,"owners_count":21116688,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["csharp","dotnetcore2","hacktoberfest","hacktoberfest2020","nuget-package","postalcode","services","zipcode"],"created_at":"2024-09-24T19:41:29.081Z","updated_at":"2025-04-12T03:32:05.357Z","avatar_url":"https://github.com/danilolutz.png","language":"C#","readme":"# ![CoreZipCode](./corezipcode.png)\n\n[![Build](https://github.com/danilolutz/CoreZipCode/actions/workflows/main.yml/badge.svg)](https://github.com/danilolutz/CoreZipCode/actions/workflows/main.yml)\n[![Coverage Status](https://coveralls.io/repos/github/danilolutz/CoreZipCode/badge.svg?branch=master)](https://coveralls.io/github/danilolutz/CoreZipCode?branch=master)\n[![Codacy Badge](https://app.codacy.com/project/badge/Grade/4e055c8f8dfb4d88961f19a6318c8b52)](https://www.codacy.com/gh/danilolutz/CoreZipCode/dashboard?utm_source=github.com\u0026utm_medium=referral\u0026utm_content=danilolutz/CoreZipCode\u0026utm_campaign=Badge_Grade)\n[![Known Vulnerabilities](https://snyk.io/test/github/danilolutz/CoreZipCode/main/badge.svg)](https://snyk.io/test/github/danilolutz/CoreZipCode/main)\n[![CoreZipCode Nuget Package](https://img.shields.io/nuget/v/CoreZipCode.svg)](https://www.nuget.org/packages/CoreZipCode/) [![License: MIT](https://img.shields.io/badge/License-MIT-428f7e.svg)](https://opensource.org/licenses/MIT)\n\n## CoreZipCode Overview\n\nNormaly 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.\n\nAlso this package could be used for easily implements address services to yours [Microsoft .Net Core](https://dotnet.github.io/) based software.\n\nAnd 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.\n\nWe follow the [Semantic Versioning](https://semver.org), so check the package compatibility before use it.\n\n## :sunglasses: Get Started\n\nWell, 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/).\n\nJust in case if you doesn't want leave GitHub at this moment:\n\n```bash\ndotnet add package CoreZipCode\n```\n\nAfter you decide how you'll get the CoreZipCode, just inject (e.g.: [Simple Injector](https://simpleinjector.org/)) and use it.\n\n```CSharp\nusing CoreZipCode.Interfaces;\n\nnamespace YourProject\n{\n    public YourClass\n    {\n        private readonly ZipCodeBaseService _coreZipCode;\n\n        public YourClass(ZipCodeBaseService coreZipCode)\n        {\n            _coreZipCode = coreZipCode;\n        }\n\n        public void YourMethod()\n        {\n            var addressByZipCode = _coreZipCode.Execute(\"14810100\");\n            var zipCodeByAddress = _coreZipCode.Execute(\"sp\", \"araraquara\", \"barão do rio\");\n\n            // Generic type return was added in version 1.1.0\n            var addressByZipCodeObject = _coreZipCode.GetAddress\u003cViaCepAddress\u003e(\"14810100\");\n            var zipCodeByAddressObjectList = _coreZipCode.ListAddresses\u003cViaCepAddress\u003e(\"sp\", \"araraquara\", \"barão do rio\");\n        }\n\n        // Async methods introduced in 1.1.0\n        public async void YourMethodAsync()\n        {\n            var addressByZipCode = await _coreZipCode.ExecuteAsync(\"14810100\");\n            var zipCodeByAddress = await _coreZipCode.ExecuteAsync(\"sp\", \"araraquara\", \"barão do rio\");\n\n            // Generic type return.\n            var addressByZipCodeObject = await _coreZipCode.GetAddressAsync\u003cViaCepAddress\u003e(\"14810100\");\n            var zipCodeByAddressObjectList = await _coreZipCode.ListAddressesAsync\u003cViaCepAddress\u003e(\"sp\", \"araraquara\", \"barão do rio\");\n        }\n    }\n}\n```\n\nThe `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.\n\n### Extending CoreZipCode\n\nAlso you can extends `ZipCodeBaseService` abstract class and create your own implementation of your prefered address service. Like below:\n\n```CSharp\nusing CoreZipCode.Interfaces;\n\nnamespace CoreZipCode.Services.YourService\n{\n    public class YourService : ZipCodeBaseService\n    {\n        public override string SetZipCodeUrl(string zipcode)\n        {\n            // You can implement some validation method here.\n            return $\"https://yourservice.com/{zipcode}/json/\";\n        }\n\n        public override string SetZipCodeUrlBy(string state, string city, string street)\n        {\n            // You can implement some validation method here.\n            return $\"https://yourservice.com/{state}/{city}/{street}/json/\";\n        }\n    }\n}\n```\n\n\u003e **NOTE**: Same principles are used to extends postcode lookups (`PostCodeBaseService`).\n\n## :heavy_check_mark: Available Services\n\nBelow a list of available services out-of-the-box **address by zipcode** lookup services.\n\n| Service                                     | Country | Queries Limit     |\n| :------------------------------------------ | :------ | :---------------- |\n| [ViaCep](https://viacep.com.br)             | Brazil  | 300 by 15 minutes |\n| [Smarty](https://www.smarty.com/)           | USA     | 250 by month      |\n\nBelow a list of available services out-of-the-box **postcodes** lookup services.\n\n| Service                                    | Country        | Queries Limit |\n| :----------------------------------------- | :------------- | :------------ |\n| [Postcodes](https://postcodes.io)          | United Kingdom | Unknown       |\n| [Postal Pin Code](http://postalpincode.in) | India          | Unknown       |\n\n## :construction_worker: Contributing\n\nThank you for considering contributing to the CodeZipCore! Just see our [Contributing Guide](.github/CONTRIBUTING.md).\n\n### :innocent: Code of Conduct\n\nIn 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).\n\n## :rotating_light: Security Vulnerabilities\n\nIf 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.\n\n## :scroll: License\n\nThe CoreZipCode is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanilolutz%2Fcorezipcode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdanilolutz%2Fcorezipcode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanilolutz%2Fcorezipcode/lists"}