{"id":39633546,"url":"https://github.com/cauethenorio/simplecep","last_synced_at":"2026-01-18T08:49:24.332Z","repository":{"id":57467305,"uuid":"350939834","full_name":"cauethenorio/simplecep","owner":"cauethenorio","description":"Reliably resolve Brazilian CEP addresses using multiple sources","archived":false,"fork":false,"pushed_at":"2021-03-29T04:45:43.000Z","size":55,"stargazers_count":2,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-04T03:17:56.763Z","etag":null,"topics":["address-retrieval","cep","cep-address","cep-apis","correios","correios-api","party-api","python"],"latest_commit_sha":null,"homepage":"","language":"Python","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/cauethenorio.png","metadata":{"files":{"readme":"README.md","changelog":"HISTORY.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-03-24T03:56:33.000Z","updated_at":"2023-10-03T14:46:09.000Z","dependencies_parsed_at":"2022-09-19T08:41:43.836Z","dependency_job_id":null,"html_url":"https://github.com/cauethenorio/simplecep","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/cauethenorio/simplecep","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cauethenorio%2Fsimplecep","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cauethenorio%2Fsimplecep/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cauethenorio%2Fsimplecep/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cauethenorio%2Fsimplecep/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cauethenorio","download_url":"https://codeload.github.com/cauethenorio/simplecep/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cauethenorio%2Fsimplecep/sbom","scorecard":{"id":268113,"data":{"date":"2025-08-11","repo":{"name":"github.com/cauethenorio/simplecep","commit":"ce1edd62f11141ea440e29aa9bd0b79516a8c12d"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":3.1,"checks":[{"name":"Code-Review","score":0,"reason":"Found 0/22 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"SAST","score":0,"reason":"no SAST tool detected","details":["Warn: no pull requests merged into dev branch"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/coverage-report.yml:1","Warn: no topLevel permission defined: .github/workflows/publish.yml:1","Warn: no topLevel permission defined: .github/workflows/tests.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Pinned-Dependencies","score":1,"reason":"dependency not pinned by hash detected -- score normalized to 1","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/coverage-report.yml:12: update your workflow using https://app.stepsecurity.io/secureworkflow/cauethenorio/simplecep/coverage-report.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/coverage-report.yml:15: update your workflow using https://app.stepsecurity.io/secureworkflow/cauethenorio/simplecep/coverage-report.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/publish.yml:16: update your workflow using https://app.stepsecurity.io/secureworkflow/cauethenorio/simplecep/publish.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/publish.yml:19: update your workflow using https://app.stepsecurity.io/secureworkflow/cauethenorio/simplecep/publish.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/tests.yml:16: update your workflow using https://app.stepsecurity.io/secureworkflow/cauethenorio/simplecep/tests.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/tests.yml:19: update your workflow using https://app.stepsecurity.io/secureworkflow/cauethenorio/simplecep/tests.yml/main?enable=pin","Warn: pipCommand not pinned by hash: .github/workflows/coverage-report.yml:21","Warn: pipCommand not pinned by hash: .github/workflows/coverage-report.yml:22","Warn: pipCommand not pinned by hash: .github/workflows/coverage-report.yml:23","Warn: pipCommand not pinned by hash: .github/workflows/publish.yml:25","Warn: pipCommand not pinned by hash: .github/workflows/publish.yml:26","Warn: pipCommand not pinned by hash: .github/workflows/tests.yml:25","Warn: pipCommand not pinned by hash: .github/workflows/tests.yml:26","Info:   0 out of   6 GitHub-owned GitHubAction dependencies pinned","Info:   2 out of   2 third-party GitHubAction dependencies pinned","Info:   0 out of   7 pipCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'main'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Vulnerabilities","score":6,"reason":"4 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: PYSEC-2024-48 / GHSA-fj7x-q9j7-g6q6","Warn: Project is vulnerable to: PYSEC-2021-437 / GHSA-5xp3-jfq3-5q8x","Warn: Project is vulnerable to: PYSEC-2023-228 / GHSA-mq26-g339-26xf","Warn: Project is vulnerable to: PYSEC-2022-43017 / GHSA-qwmp-2cf2-g9g6"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-17T12:41:09.898Z","repository_id":57467305,"created_at":"2025-08-17T12:41:09.898Z","updated_at":"2025-08-17T12:41:09.898Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28534151,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["address-retrieval","cep","cep-address","cep-apis","correios","correios-api","party-api","python"],"created_at":"2026-01-18T08:49:23.988Z","updated_at":"2026-01-18T08:49:24.317Z","avatar_url":"https://github.com/cauethenorio.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# simpleCEP\n\n[![PyPI version](https://badge.fury.io/py/simplecep.svg)](https://pypi.org/project/simplecep/)\n[![Tests Status](https://github.com/cauethenorio/simplecep/actions/workflows/tests.yml/badge.svg)](https://github.com/cauethenorio/simplecep/actions/workflows/tests.yml)\n[![Coverage Status](https://coveralls.io/repos/github/cauethenorio/simplecep/badge.svg?branch=main)](https://coveralls.io/github/cauethenorio/simplecep?branch=main)\n[![Compatible Python Versions](https://img.shields.io/pypi/pyversions/simplecep.svg)](https://pypi.python.org/pypi/simplecep)\n\nReliably resolve Brazilian CEP addresses using multiple APIs.\n\n\n## Why\n\nECT (Correios Company) doesn't open their CEP (Brazilian Zip Codes) data, requiring\nsystems to fetch CEP data individually through their API or buying the full\ndatabase from their website.\n\nCorreios API (SIGEPWeb) is known for its outages, which impacts systems which\nrelies on resolving CEPs as addresses, as e-commerces.\n\nThis library addresses the problem using alternative CEP data APIs as fallbacks\nwhen Correios API doesn't respond in time and caching all received results.\n\n\n## How it works\n\nThe library uses the configured CEP data providers to fetch the CEP address.\nEach installed provider is used until the data is successfully fetched.\n\nIt will try to get the CEP address using Correios official API and if\nit fails it will use third-party API as fallbacks.\n\nBy default, it uses the following CEP APIs:\n- https://www.republicavirtual.com.br\n- https://viacep.com.br/\n\nBoth APIs are queried concurrently using threads, and the first received result is used.\n\nAfter fetched, the retrieved address data is cached so any address-retrieval\nattempt for the same CEP is resolved immediately and won't use external\nproviders.\n\nThe used providers, their order, and the cache mechanism can be fully\ncustomized.\n\nIf the CEP data isn't cached and all providers fail to retrieve it,\nthe `CouldNotResolveCepError` exception is raised.\n\n## Usage\n\n\n### Installation\n\nInstall from PyPI\n\n```\npip install simplecep\n```\n\n\n### Using the default config\n\nThe package provides a ready-to-use `resolve_cep` function which will\ntry to, in order:\n\n1. Get the CEP address from the internal cache\n2. Get the CEP address from the official Correios API\n3. Get the CEP address, in parallel, from third-party CEP APIs:\n    - https://www.republicavirtual.com.br\n    - https://viacep.com.br/\n\nIt will stop on success, and the subsequent steps won't be executed.\nBy default, it will wait 2 seconds for each provider.\n\nExample:\n\n```python\n\u003e\u003e from simplecep import resolve_cep\n\u003e\u003e address = resolve_cep('59615350')\n\n\u003e\u003e address\n\u003cCEPAddress 59615-350\u003e\n\n\u003e\u003e address.to_dict()\n{\n    'cep': '59615-350',\n    'street': 'Rua João Simão do Nascimento',\n    'district': 'Santa Delmira',\n    'city': 'Mossoró',\n    'state': 'RN'\n}\n```\n\nThe `CEPAddress` class provides the address fields in both English and\nBrazilian Portuguese names:\n\n```python\n\u003e\u003e address\n\u003cCEPAddress 59615-350\u003e\n\n\u003e\u003e address.street\n'Rua João Simão do Nascimento'\n\n\u003e\u003e address.rua\n'Rua João Simão do Nascimento'\n\n\u003e\u003e address.city == address.cidade\nTrue\n\n\u003e\u003e address.to_dict(br_names=True)\n{\n    'cep': '59615-350',\n    'rua': 'Rua João Simão do Nascimento',\n    'bairro': 'Santa Delmira',\n    'cidade': 'Mossoró',\n    'estado': 'RN'\n}\n```\n\n\n### Customization\n\nIf you need to use the providers in a different order, a custom\nprovider, a different cache mechanism or change the timeout, a new\nresolver instance can be created using the `CEPResolver` class.\n\nHere's how the default `resolve_cep` function is created:\n\n```python\nfrom simplecep import (\n    CEPResolver,\n    correios_sigep_cep_provider,\n    republicavirtual_cep_provider,\n    viacep_cep_provider\n)\n\nresolve_cep = CEPResolver(\n    providers=[\n        # this resolver will first try to use the Correios API,\n        {correios_sigep_cep_provider},\n        # if it fails it will fall back to the RepublicaVirtual and ViaCEP APIs\n        # it will spawn two threads and will query both APIs at the same time\n        # the result from the first one to reply will be used\n        {republicavirtual_cep_provider, viacep_cep_provider},\n    ],\n    # by default it will wait for each provider for 1 second\n    timeout=2,\n    # all fetched CEP data will be stored in the\n    # cache object which is a dict but can be any dict-like object\n    cache={}\n)\n```\n\n\n#### Providers Order\n\nThe `providers` argument should be a list of sets specifying which\nproviders should be used, and the order they should be called.\n\nWhen called, the resolver iterate over the list calling all providers in\neach set concurrently using threads.\n\nWhen the CEP is successfully resolved by a provider, the iteration stops\nand the following provider sets are not executed.\n\nHere's an example of `providers` param which will query all APIs\nconcurrently and use the first received result:\n\n```python\nbrute_resolver = CEPResolver(\n    providers=[\n        {\n            correios_sigep_cep_provider,\n            republicavirtual_cep_provider,\n            viacep_cep_provider\n        }\n    ]\n)\n```\n\n\n#### Custom providers\n\nCustom providers can be used to fetch CEP data from different sources.\n\nThe provider should be a callable which accepts `cep` and `timeout` as\nparameters and returns a `CEPAddress` object when a CEP is found and\n`None` when the CEP doesn't exist:\n\n```python\ndef my_custom_provder(cep: str, timeout: float) -\u003e Optional[CEPAdress]:\n    pass # my implementation here\n```\n\nCustom providers should raise the `CEPProviderUnavailableError` error\nwhen they fail to contact their data source or if the data source\ndoesn't reply before the specified `timeout` interval.\n\nProvider-auxiliary functions are available in the\n`simplecep.providers.commons` module.\n\n\n#### Custom cache\n\nBy default, a dict object is used as cache, it's good enough to avoid\nquerying for the same CEP twice in the same process, but it has limitations as:\n- Different processes can't share the cache (i.e. web-workers)\n- The cache is destroyed when the process is killed\n\nSo a custom object can be used as cache, it needs to be a dict-like object\n(i.e. implements `__getitem__` and `__setitem__`).\n\nA good example is the `redis-dict` project which creates a dict-like object\nwhich stores the values on Redis: https://pypi.org/project/redis-dict/\n\n\n# Testing\n\nTests are found in the ```tests``` folder. Install the requirements in\nthe `dev_requirements.txt` file and run `make test` to run the tests.\n\n# License\n\nSee [License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcauethenorio%2Fsimplecep","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcauethenorio%2Fsimplecep","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcauethenorio%2Fsimplecep/lists"}