{"id":16241937,"url":"https://github.com/douglascamata/cep","last_synced_at":"2025-03-19T17:30:52.672Z","repository":{"id":57482534,"uuid":"54437171","full_name":"douglascamata/cep","owner":"douglascamata","description":"Brazilian CEP (zip) code queries in Elixir made easy, fast and resilient. ","archived":false,"fork":false,"pushed_at":"2020-07-20T10:28:51.000Z","size":46,"stargazers_count":12,"open_issues_count":4,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-28T20:02:55.982Z","etag":null,"topics":["cep","elixir","elixir-lang"],"latest_commit_sha":null,"homepage":"","language":"Elixir","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/douglascamata.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2016-03-22T01:55:43.000Z","updated_at":"2023-09-01T10:48:57.000Z","dependencies_parsed_at":"2022-09-02T04:21:18.672Z","dependency_job_id":null,"html_url":"https://github.com/douglascamata/cep","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/douglascamata%2Fcep","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/douglascamata%2Fcep/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/douglascamata%2Fcep/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/douglascamata%2Fcep/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/douglascamata","download_url":"https://codeload.github.com/douglascamata/cep/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244006290,"owners_count":20382443,"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":["cep","elixir","elixir-lang"],"created_at":"2024-10-10T14:09:02.278Z","updated_at":"2025-03-19T17:30:52.420Z","avatar_url":"https://github.com/douglascamata.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cep\n\n[![Build Status](https://travis-ci.org/douglascamata/cep.svg?branch=master)](https://travis-ci.org/douglascamata/cep)\n\nA package to query Brazilian zip (CEP) codes.\n\nHas support for multiple source APIs (Correios, ViaCep, Postmon, etc).\nIt can query one specific source or query until one source returns a valid\nresult.\n\n## Table of Contents\n- [Table of Contents](#table-of-contents)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Configuration](#configuration)\n  - [Sources](#sources)\n- [Future](#future)\n\n## Installation\n\nIt's is available as an [Hex](https://hex.pm) package and thus can be installed\nas:\n\n1. Add cep to your list of dependencies in `mix.exs`:\n\n```elixir\ndef deps do\n  [{:cep, \"~\u003e 0.0.2\"}]\nend\n```\n\n## Usage\n\nTo query for the address of any given Brazilian CEP code:\n\n```elixir\n{:ok, address} = Cep.Client.get_address(\"29375-000\")\nIO.inspect address\n```\n\nThe default `Cep.Client.get_address` will first try to access the official Brazilian\nPost Office web service to get the information. If the web service is down,\ntimeout or doesn't have information about one specific CEP the next source will\nbe automatically and transparently used. If none of the sources give good reply\nit will return a proper error, as in the following example:\n\n```elixir\n{status, reason} = Cep.Client.get_address(\"00000-000\")\nIO.inspect status\nIO.inspect reason\n```\n\nYou can modify the sources that a query will use by using the `sources` keyword\nargument and sending as its value any combination of the element from\n`Cep.sources` as follows:\n\n```elixir\navailable_sources = Keyword.delete(Cep.sources, :correios)\n{:ok, address} = Cep.Client.get_address(\"28016-811\", sources: available_sources)\n```\n\nTo query just one specific source there is a sugar: just send the `source` with\nthe desired source:\n\n```elixir\nCep.Client.get_address(\"28016-811\", source: :viacep)\n```\n\n## Configuration\n\n### Sources\n\nYou can change the default sources used when no `source` or `sources` keywords\nare sent to `Cep.Client.get_address` by modifying your config file like this:\n\n```elixir\nconfig :cep, sources: [:correios, :viacep]\n```\n\n**IMPORTANT**: even if you add the default sources in config file, the `source`\nand `sources` keywords can override this configuration.\n\n#### Add a custom source\n\n```elixir\ndefmodule Cep.Sources.Custom.YourNewGreateSource do\n  import Cep.Sources.Base\n\n  @behaviour Cep.Source\n\n  def get_address(cep) do\n    # implement your source returning:\n    # { :ok, %Cep.Address{...} }\n    # or\n    # { :error, \"reason\" }\n    # or\n    # { :not_found, _ }\n  end\nend\n```\n\nand then pass it as the default sources in config file or as `sources` keywords.\n\n```elixir\nconfig :cep, sources: [:correios, Cep.Sources.Custom.YourNewGreateSource]\n# or\nclient.get_address(\"00010-100\", sources: [:correios, Cep.Sources.Custom.YourNewGreateSource])\n```\n\n## Future\n\nFuture features that are planned:\n\n1. Use the circuit breaker pattern to avoid querying sources that return\n   unexpected errors too often.\n\n2. Use [Mox](https://github.com/plataformatec/mox) in the specs\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdouglascamata%2Fcep","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdouglascamata%2Fcep","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdouglascamata%2Fcep/lists"}