{"id":37079784,"url":"https://github.com/cauethenorio/edne-correios-loader","last_synced_at":"2026-01-14T09:39:15.044Z","repository":{"id":8174094,"uuid":"9597402","full_name":"cauethenorio/edne-correios-loader","owner":"cauethenorio","description":"Importe os arquivos de texto do e-DNE Básico dos Correios do Brasil em seu banco de dados para habilitar a busca por CEP","archived":false,"fork":false,"pushed_at":"2025-02-23T03:39:16.000Z","size":101,"stargazers_count":44,"open_issues_count":5,"forks_count":13,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-09-17T06:08:13.171Z","etag":null,"topics":["cep","cep-search","correios","correios-cep","correios-edne","database","dne","e-dne","endereco","zipcode"],"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-en.md","changelog":"HISTORY.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2013-04-22T11:27:59.000Z","updated_at":"2025-08-22T22:47:23.000Z","dependencies_parsed_at":"2023-10-11T18:44:04.155Z","dependency_job_id":null,"html_url":"https://github.com/cauethenorio/edne-correios-loader","commit_stats":null,"previous_names":["cauethenorio/edne-correios-loader"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/cauethenorio/edne-correios-loader","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cauethenorio%2Fedne-correios-loader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cauethenorio%2Fedne-correios-loader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cauethenorio%2Fedne-correios-loader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cauethenorio%2Fedne-correios-loader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cauethenorio","download_url":"https://codeload.github.com/cauethenorio/edne-correios-loader/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cauethenorio%2Fedne-correios-loader/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28416120,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T08:38:59.149Z","status":"ssl_error","status_checked_at":"2026-01-14T08:38:43.588Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["cep","cep-search","correios","correios-cep","correios-edne","database","dne","e-dne","endereco","zipcode"],"created_at":"2026-01-14T09:39:14.319Z","updated_at":"2026-01-14T09:39:15.037Z","avatar_url":"https://github.com/cauethenorio.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# e-DNE Correios Loader\n\n[![PyPI - Version](https://img.shields.io/pypi/v/edne-correios-loader.svg)](https://pypi.org/project/edne-correios-loader)\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/edne-correios-loader.svg)](https://pypi.org/project/edne-correios-loader\n[![codecov](https://codecov.io/gh/cauethenorio/edne-correios-loader/graph/badge.svg?token=HP9C86U1LX)](https://codecov.io/gh/cauethenorio/edne-correios-loader)\n\nCLI to load e-DNE Basico files from Correios (Brazilian postal service) into a database\n(PostgreSQL, MySQL, SQLite, and others) and create a single table for querying postal codes (CEPs).\n\n---\n\n### [Versão em português 🇧🇷](README.md)\n\n## Features\n\n- Import Correios' e-DNE Basico files into a database\n- Creates a unified table for querying postal codes (CEPs)\n- Supports databases like PostgreSQL, MySQL, SQLite, and others\n- Allows for data updates without service interruption\n \n\n## Purpose\n\nThe DNE (National Address Directory) is an official and exclusive database of Correios\n(Brazilian postal service), containing over 900 thousand postal codes from all over Brazil.\nIt consists of addressing elements (description of streets, neighborhoods, municipalities,\nvillages, hamlets) and Postal Address Codes - CEP.\n\nThis database is available in two versions, the __e-DNE Basic__ and the __e-DNE Master__.\nBoth contain all the postal codes in Brazil, with addressing elements down to the street section level,\nbut they differ in format. The e-DNE Basic is composed of several text files (`.txt`) that need\nto be processed and transferred to a database in order to be queried. On the other hand, the\ne-DNE Master is a database in MS-Access format (`.mdb`) ready for use.\n\nThe DNE is owned by Correios and can be purchased through their e-commerce platform. Currently,\n(October 2023), the Master version costs R$ 3,187.65 and the Basic version costs R$ 1,402.5.\nBoth versions guarantee one year of updates after the purchase date.\n\n[__For clients with a contract with Correios, the e-DNE Basic can be acquired for free.__](https://www.correios.com.br/enviar/marketing-direto/saiba-mais-nacional)\n\nThis project facilitates the use of the e-DNE Basic, which is cheaper and easier to acquire,\nby processing the text files and transferring them to a database. It also creates a\nsingle table for querying postal codes (not included in the DNE, where different types of\npostal codes are stored in different tables) and allows your database to be updated with\nnew versions of the e-DNE, released biweekly by Correios.\n\n\n## Installation\n\nThe `edne-correios-loader` can be installed via `pip`:\n\n```shell\npip install edne-correios-loader\n```\n\nYou will also need to install the database driver that will be used. Here are some\ninstructions on how to install drivers for the most common databases:\n\n### PostgreSQL\n\nFor PostgreSQL, the `psycopg2-binary` driver can be installed using an\n[extra](https://peps.python.org/pep-0508/#extras):\n```shell\npip install edne-correios-loader[postgresql]\n```\n\nIf there are no pre-compiled version of `psycopg2` for your operating system and Python version,\nyou may need to install some libraries to be able to compile the driver. Another option is to install the\n`pg8000` driver for PostgreSQL, which is written entirely in Python and does not need to be compiled.\n\n### MySQL\n\nFor MySQL, the `mysqlclient` driver can be installed using an\n[extra](https://peps.python.org/pep-0508/#extras):\n```shell\npip install edne-correios-loader[mysql]\n```\n\n### SQLite\n\nPython already provides the `sqlite3` library for communication with SQLite, so no\nadditional instructions are needed.\n\n### Others\n\nThe `sqlalchemy` library is used for communication with the database, so any database\nsupported by it can be used, such as Microsoft SQL Server and Oracle. To install\nthe driver for a database not listed here, refer to the SQLAlchemy documentation:\nhttps://docs.sqlalchemy.org/en/20/dialects/index.html\n\n\n\n## Usage\n\n### Command Line\n\nThe data import can be executed via the command line using the `edne-correios-loader load` command.\n\n```shell\n$ edne-correios-loader load --help\n\nUsage: edne-correios-loader load [OPTIONS]\n\n  Load DNE data into a database.\n\nOptions:\n  -s, --dne-source \u003cpath/zip-file/url\u003e\n                                  Path or URL with the DNE file/dir to be\n                                  imported\n  -db, --database-url \u003curl\u003e       Database URL where the DNE data will be\n                                  imported to  [required]\n  --tables [unified-cep-only|cep-tables|all]\n                                  Which tables to keep in the database after\n                                  the import\n  -v, --verbose                   Enables verbose mode.\n  -h, --help                      Show this message and exit.\n```\n\n#### Options\n\nThe following options are available:\n- __`--dne-source`__ **(optional)**\n\n  Source of the e-DNE to be imported. It can be:\n    - A URL to a ZIP file with the e-DNE\n    - The local path to a ZIP file with the e-DNE\n    - The local path to a directory containing the e-DNE files\n    \n  If this option is not provided, the latest available e-DNE Basic on the Correios website\n  will be downloaded and used as the source. **Use this option only if you have a contract\n  with Correios**.\n \n\n- __`--database-url`__ **(required)**\n\n  Database URL where the e-DNE data will be imported. The URL should follow the format\n  `dialect+driver://username:password@host:port/database`, where:\n    - `dialect` is the name of the database, such as `postgresql`, `mysql`, `sqlite`, etc.\n    - `driver` is the name of the database driver, such as `psycopg2`, `mysqlclient`,\n      `pg8000`, etc. If not specified, the most popular driver is automatically used.\n    - `username` is the database user's name\n    - `password` is the database user's password\n    - `host` is the database server's address\n    - `port` is the database server's port\n    - `database` is the name of the database\n\n  More information about the URL format can be found in the\n    [SQLAlchemy documentation](https://docs.sqlalchemy.org/en/20/core/engines.html#database-urls)\n \n\n- __`--tables`__ **(optional)**\n\n  Defines which tables will be kept in the database after the import. It can be:\n    - `unified-cep-only`: Keeps only the unified CEP table\n    - `cep-tables`: Keeps only the tables with CEPs, separated by type\n    - `all`: Keeps all DNE tables\n\n  When not specified, the `unified-cep-only` option is used by default, keeping\n  only the unified CEP table.\n\n\n- __`--verbose`__ **(optional)**\n\n  Enables verbose mode, which displays DEBUG information useful for troubleshooting\n  during command execution.\n\n#### Usage Examples\n\nImports the e-DNE Basic directly from the Correios website to a local SQLite database,\nkeeping only the unified table:\n```shell\nedne-correios-loader load --database-url sqlite:///dne.db\n```\n\nImports the e-DNE Basic from a ZIP file to a local PostgreSQL database, keeping all\ntables with CEPs:\n```shell\nedne-correios-loader load \\\n  --dne-source /path/to/dne.zip \\\n  --database-url postgresql://user:pass@localhost:5432/mydb \\\n  --tables cep-tables\n```\n\nImports the e-DNE Basic from a directory to a local MySQL database, keeping all tables:\n```shell\nedne-correios-loader load \\\n  --dne-source /path/to/dne/dir \\\n  --database-url mysql+mysqlclient://user:pass@localhost:3306/mydb \\\n  --tables all\n```\n\nThe command output may vary depending on the options used, but it should be\nsimilar to the following:\n```\nStarting DNE Correios Loader v0.1.1\n\nConnecting to database...\n\nResolving DNE source...\n\nNo DNE source provided, the latest DNE will be downloaded from Correios website\nDownloading DNE file  [####################################]  100%\n\nCreating tables:\n- cep_unificado\n- log_localidade\n- log_bairro\n- log_cpc\n- log_logradouro\n- log_grande_usuario\n- log_unid_oper\n\nCleaning tables\n\nPopulating table log_localidade\n  Reading LOG_LOCALIDADE.TXT\n  Inserted 11219 rows into table \"log_localidade\"\n\nPopulating table log_bairro\n  Reading LOG_BAIRRO.TXT\n  Inserted 64456 rows into table \"log_bairro\"\n\nPopulating table log_cpc\n  Reading LOG_CPC.TXT\n  Inserted 2133 rows into table \"log_cpc\"\n\nPopulating table log_logradouro\n  Reading LOG_LOGRADOURO_RS.TXT\n  Reading LOG_LOGRADOURO_RR.TXT\n  Reading LOG_LOGRADOURO_SC.TXT\n  Reading LOG_LOGRADOURO_SP.TXT\n  Reading LOG_LOGRADOURO_SE.TXT\n  Reading LOG_LOGRADOURO_PI.TXT\n  Reading LOG_LOGRADOURO_MS.TXT\n  Reading LOG_LOGRADOURO_AP.TXT\n  Reading LOG_LOGRADOURO_MG.TXT\n  Reading LOG_LOGRADOURO_MT.TXT\n  Reading LOG_LOGRADOURO_AC.TXT\n  Reading LOG_LOGRADOURO_MA.TXT\n  Reading LOG_LOGRADOURO_TO.TXT\n  Reading LOG_LOGRADOURO_AL.TXT\n  Reading LOG_LOGRADOURO_CE.TXT\n  Reading LOG_LOGRADOURO_BA.TXT\n  Reading LOG_LOGRADOURO_AM.TXT\n  Reading LOG_LOGRADOURO_ES.TXT\n  Reading LOG_LOGRADOURO_PR.TXT\n  Reading LOG_LOGRADOURO_PE.TXT\n  Reading LOG_LOGRADOURO_GO.TXT\n  Reading LOG_LOGRADOURO_RN.TXT\n  Reading LOG_LOGRADOURO_RO.TXT\n  Reading LOG_LOGRADOURO_DF.TXT\n  Reading LOG_LOGRADOURO_RJ.TXT\n  Reading LOG_LOGRADOURO_PB.TXT\n  Reading LOG_LOGRADOURO_PA.TXT\n  Inserted 1236944 rows into table \"log_logradouro\"\n\nPopulating table log_grande_usuario\n  Reading LOG_GRANDE_USUARIO.TXT\n  Inserted 18967 rows into table \"log_grande_usuario\"\n\nPopulating table log_unid_oper\n  Reading LOG_UNID_OPER.TXT\n  Inserted 12534 rows into table \"log_unid_oper\"\n\nPopulating unified CEP table\n  Populating unified CEP table with logradouros data\n    Inserted 1236944 CEPs from logradouros into table cep_unificado\n  Populating unified CEP table with localidades data\n    Inserted 4974 CEPs from localidades into table cep_unificado\n  Populating unified CEP table with localidades subordinadas data\n    Inserted 5311 CEPs from localidades subordinadas into table cep_unificado\n  Populating unified CEP table with normalized CPC data\n    Inserted 2133 CEPs from CPC into table cep_unificado\n  Populating unified CEP table with normalized grandes usuários data\n    Inserted 18967 CEPs from grandes usuários into table cep_unificado\n  Populating unified CEP table with normalized unidades operacionais data\n    Inserted 12534 CEPs from unidades operacionais into table cep_unificado\n  Inserted 1280863 rows into table \"cep_unificado\"\n\nDropping tables\n  Dropping table log_faixa_uop\n  Dropping table log_var_log\n  Dropping table log_unid_oper\n  Dropping table log_num_sec\n  Dropping table log_grande_usuario\n  Dropping table log_var_bai\n  Dropping table log_logradouro\n  Dropping table log_faixa_cpc\n  Dropping table log_faixa_bairro\n  Dropping table log_var_loc\n  Dropping table log_faixa_localidade\n  Dropping table log_cpc\n  Dropping table log_bairro\n  Dropping table log_localidade\n  Dropping table log_faixa_uf\n  Dropping table ect_pais\n```\n\n#### CEP Query\n\nAfter the import, it's possible to check if the data was imported correctly by querying\nCEPs in the unified table using the command `edne-correios-loader query-cep`. Example:\n\n```shell\n$ edne-correios-loader query-cep --database-url mysql+mysqlclient://user:pass@localhost:3306/mydb 01001000\n{\n  \"cep\": \"01001000\",\n  \"logradouro\": \"Praça da Sé\",\n  \"complemento\": null,\n  \"bairro\": \"Sé\",\n  \"municipio\": \"São Paulo\",\n  \"municipio_cod_ibge\": 3550308,\n  \"uf\": \"SP\",\n  \"nome\": null\n}\n```\n\n\n### Python API\n\nThe `edne-correios-loader` can also be used as a Python library, through\nthe `edne_correios_loader` module. Example:\n\n```python\nfrom edne_correios_loader import DneLoader, TableSetEnum\n\nDneLoader(\n  # Database connection URL (required)\n  'postgresql://user:pass@localhost:5432/mydb',\n  # Path or URL to the ZIP file or directory with e-DNE files (optional) \n  dne_source=\"/path/to/dne.zip\",\n).load(\n  # define the tables to keep in the database after the import (optional)\n  # When omitted, only the unified table is kept\n  # Other options are TableSetEnum.CEP_TABLES and TableSetEnum.ALL\n  table_set=TableSetEnum.CEP_TABLES\n)\n```\n\nAfter the import, CEPs can be queried in the unified table using the `CepQuerier` class:\n```python\nfrom edne_correios_loader import CepQuerier\n\ncep_querier = CepQuerier('postgresql://user:pass@localhost:5432/mydb')\ncep = cep_querier.query('01319010')\n\nassert cep == {\n  'cep': '79290000',\n  'logradouro': None,\n  'complemento': None,\n  'bairro': None,\n  'municipio': 'Bonito',\n  'municipio_cod_ibge': 5002209,\n  'uf': 'MS',\n  'nome': None\n}\n```\n\n## Updating CEPs data\n\nBi-weekly, Correios update the e-DNE with new postal codes. To update your database,\nrun the `loader` command using the updated e-DNE file as the source.\n\nThe command will delete the data from all e-DNE tables and import the data from the new e-DNE.\nAfter the import, the unified table is repopulated with the new data.\n\nThe whole process is executed inside a transaction, so other clients connected to the database\nwill continue to have access to the old data while the update is being executed.\n\nIf something goes wrong during the update, the transaction will be rolled back and the old data will be preserved.\n\n\n## Tests\n\nTo run the tests, you need to have [Docker](https://www.docker.com/) and\n[Python project manager Hatch](https://github.com/pypa/hatch) installed. After installation:\n1. Clone the project:\n  ```shell\n  git clone https://github.com/cauethenorio/edne-correios-loader\n  ```` \n2. Run the Docker containers with MySQL and PostgreSQL:\n  ```shell\n  cd edne-correios-loader/tests\n  docker compose up -d\n  ```\n3. Execute the tests using `hatch`:\n  ```shell\n  hatch run test\n  ``` \n\n## License\n\nThis project is distributed under the terms of the [MIT license](https://spdx.org/licenses/MIT.html).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcauethenorio%2Fedne-correios-loader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcauethenorio%2Fedne-correios-loader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcauethenorio%2Fedne-correios-loader/lists"}