{"id":29908752,"url":"https://github.com/alanleal-econ/comextl","last_synced_at":"2025-08-17T10:04:11.522Z","repository":{"id":306263916,"uuid":"1025197309","full_name":"alanleal-econ/comexTL","owner":"alanleal-econ","description":"Dados do Comércio Exterior Brasileiro disponíveis diretamente no R","archived":false,"fork":false,"pushed_at":"2025-08-09T15:33:44.000Z","size":115,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-09T17:32:52.792Z","etag":null,"topics":["brasil","brazil","comex","data","r","trade"],"latest_commit_sha":null,"homepage":"https://alanleal-econ.com/index.php/codes/comextl/","language":"R","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/alanleal-econ.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-23T22:14:21.000Z","updated_at":"2025-08-09T15:33:47.000Z","dependencies_parsed_at":"2025-08-02T00:44:04.422Z","dependency_job_id":null,"html_url":"https://github.com/alanleal-econ/comexTL","commit_stats":null,"previous_names":["alanleal-econ/comextl"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/alanleal-econ/comexTL","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alanleal-econ%2FcomexTL","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alanleal-econ%2FcomexTL/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alanleal-econ%2FcomexTL/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alanleal-econ%2FcomexTL/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alanleal-econ","download_url":"https://codeload.github.com/alanleal-econ/comexTL/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alanleal-econ%2FcomexTL/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270831792,"owners_count":24653414,"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","status":"online","status_checked_at":"2025-08-17T02:00:09.016Z","response_time":129,"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":["brasil","brazil","comex","data","r","trade"],"created_at":"2025-08-02T00:43:55.850Z","updated_at":"2025-08-17T10:04:11.510Z","avatar_url":"https://github.com/alanleal-econ.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"# comexTL\n\n**Dados do Comércio Exterior Brasileiro no R por Theta Lab**\n\n[![GitHub](https://img.shields.io/badge/GitHub-Repository-blue?logo=github)](https://github.com/alanleal-econ/comexTL)\n[![R](https://img.shields.io/badge/R-4.0%2B-blue?logo=r)](https://www.r-project.org/)\n[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)\n\n**Dados Atualizados em 06/08/2025*\n\n`comexTL` é um pacote R avançado que facilita o acesso, análise e manipulação dos dados oficiais de comércio exterior brasileiro do ComexStat (MDIC). Com uma arquitetura moderna baseada em Apache Arrow e sistema de cache inteligente, o pacote oferece interface unificada para análises desde o nível geral (NCM detalhado) até municipal (SH4).\n\n---\n\n## 🚀 Características Principais\n\n### **📊 Múltiplos Níveis de Análise**\n- **Dados Gerais**: Exportações e importações detalhadas por NCM (8 dígitos)\n- **Dados Municipais**: Comércio exterior por município da empresa (SH4)\n- **Tabelas de Referência**: NCM, países, UFs, municípios com busca integrada\n\n### **⚡ Performance Otimizada**\n- **Arquivos Parquet**: Processamento rápido de grandes volumes via Apache Arrow\n- **Sistema de Cache**: Armazenamento local inteligente para consultas repetidas\n- **Downloads Paralelos**: Múltiplos anos processados simultaneamente\n\n### **🔍 Filtragem Avançada**\n- **Hierarquia de Produtos**: SH2 → SH4 → SH6 → NCM (8 dígitos)\n- **Dimensão Geográfica**: País, UF, município, URF\n- **Dimensão Temporal**: Multi-anual com agregações mensais\n- **Logística**: Vias de transporte, unidades de medida\n\n### **📈 Métricas Especializadas**\n- **Exportações**: Valor FOB, peso líquido, quantidade estatística\n- **Importações**: FOB + frete + seguro, com cálculo automático de CIF\n- **Derivadas**: Percentuais de frete/seguro, contagem de municípios\n\n---\n\n## 📦 Instalação\n\n### Instalação via GitHub\n```r\n# Instalar devtools se necessário\nif (!require(devtools)) {\n    install.packages(\"devtools\")\n}\n\n# Instalar comexTL\ndevtools::install_github(\"alanleal-econ/comexTL\")\n\n# Carregar o pacote\nlibrary(comexTL)\n```\n\n### Dependências\nO pacote requer:\n- `arrow` - Processamento de arquivos Parquet\n- `dplyr` - Manipulação de dados\n- `readr` - Leitura de CSV\n- `purrr` - Programação funcional\n- `rlang` - Metaprogramação\n\n---\n\n## 📋 Início Rápido\n\n### 1. Explorar Tabelas de Referência\n```r\n# Ver tabelas disponíveis\nshow_available_tables()\n\n# Carregar tabela de países\npaises \u003c- load_reference_tables(\"3\")\nhead(paises)\n\n# Buscar códigos NCM para soja\nsoja_ncm \u003c- search_in_table(\"1\", \"soja\")\nprint(soja_ncm)\n```\n\n### 2. Análise de Exportações\n```r\n# Exportações de soja (SH2=12) em 2024 por UF\nexp_soja_2024 \u003c- comex_stat_geral_exps(\n    anos = 2024,\n    sh2 = 12,\n    agregar_por = c(\"SG_UF_NCM\")\n)\nhead(exp_soja_2024)\n\n# Análise multi-anual para China e EUA\nexp_china_eua \u003c- comex_stat_geral_exps(\n  anos = c(2023, 2024),\n  sh6 = 120190,  # Soja específica\n  co_pais = c(160, 249),  # China e EUA\n  agregar_por = c(\"CO_ANO\", \"CO_PAIS\")\n)\n```\n\n### 3. Análise de Importações\n```r\n# Importações com análise de custos\nimp_maquinas \u003c- comex_stat_geral_imps(\n    anos = 2024,\n    sh2 = 85,  # Máquinas elétricas\n    co_pais = c(160, 249),  # China e EUA\n    agregar_por = c(\"CO_PAIS\"),\n    metricas = c(\"VL_FOB\", \"VL_FRETE\", \"VL_SEGURO\")\n)\n\n# Verificar métricas derivadas automáticas\nnames(imp_maquinas)  # Inclui VL_TOTAL_CIF, PERC_FRETE, PERC_SEGURO\n```\n\n### 4. Análise Municipal\n```r\n# Exportações municipais por UF\nexp_municipal \u003c- analise_comex_municipal(\n    tipo = \"exportacao\",\n    anos = 2024,\n    sh2 = 12,  # Soja\n    sg_uf_mun = c(\"MT\", \"RS\", \"GO\"),\n    agregar_por = c(\"SG_UF_MUN\")\n)\n# Inclui automaticamente N_MUNICIPIOS\n\n# Top municípios exportadores\ntop_municipios \u003c- analise_comex_municipal(\n    tipo = \"exportacao\",\n    anos = 2024,\n    sh4 = 1201,\n    agregar_por = c(\"CO_MUN\")\n) %\u003e%\n    arrange(desc(VL_FOB)) %\u003e%\n    slice_head(n = 10)\n```\n\n---\n\n## 📊 Exemplos Avançados\n\n### Dashboard de Balança Comercial\n```r\nlibrary(dplyr)\nlibrary(ggplot2)\n\n# Dados mensais de exportação e importação\nexp_mensal \u003c- comex_stat_geral_exps(\n    anos = 2024,\n    agregar_por = c(\"CO_MES\")\n)\n\nimp_mensal \u003c- comex_stat_geral_imps(\n    anos = 2024,\n    agregar_por = c(\"CO_MES\"),\n    metricas = c(\"VL_FOB\")\n)\n\n# Calcular balança comercial\nbalanca \u003c- exp_mensal %\u003e%\n    select(CO_MES, EXPORTACOES = VL_FOB) %\u003e%\n    left_join(\n        imp_mensal %\u003e% select(CO_MES, IMPORTACOES = VL_FOB),\n        by = \"CO_MES\"\n    ) %\u003e%\n    mutate(SALDO = EXPORTACOES - IMPORTACOES)\n\n# Gráfico\nggplot(balanca, aes(x = CO_MES)) +\n    geom_line(aes(y = EXPORTACOES/1e9, color = \"Exportações\")) +\n    geom_line(aes(y = IMPORTACOES/1e9, color = \"Importações\")) +\n    geom_line(aes(y = SALDO/1e9, color = \"Saldo\")) +\n    labs(title = \"Balança Comercial Brasileira - 2024\",\n         x = \"Mês\", y = \"US$ Bilhões\") +\n    theme_minimal()\n```\n\n### Análise Regional com Tabelas de Referência\n```r\n# Carregar tabela de UFs\nuf_table \u003c- load_reference_tables(\"4\")\n\n# Exportações por região\nexp_regional \u003c- comex_stat_geral_exps(\n    anos = 2024,\n    sh2 = 12,  # Soja\n    agregar_por = c(\"SG_UF_NCM\")\n) %\u003e%\n    mutate(\n        REGIAO = case_when(\n            SG_UF_NCM %in% c(\"MT\", \"MS\", \"GO\", \"DF\") ~ \"Centro-Oeste\",\n            SG_UF_NCM %in% c(\"RS\", \"SC\", \"PR\") ~ \"Sul\",\n            SG_UF_NCM %in% c(\"SP\", \"RJ\", \"MG\", \"ES\") ~ \"Sudeste\",\n            TRUE ~ \"Outras\"\n        )\n    ) %\u003e%\n    group_by(REGIAO) %\u003e%\n    summarise(VL_FOB_TOTAL = sum(VL_FOB), .groups = \"drop\")\n\nprint(exp_regional)\n```\n\n---\n\n## 📚 Estrutura dos Dados\n\n### Dados Gerais (NCM detalhado)\n| Variável | Descrição | Tipo |\n|----------|-----------|------|\n| CO_ANO | Ano | Numérico |\n| CO_MES | Mês | Numérico |\n| CO_NCM | Código NCM (8 dígitos) | Numérico |\n| CO_PAIS | Código do país | Numérico |\n| SG_UF_NCM | UF de origem/produção | Caractere |\n| VL_FOB | Valor FOB (US$) | Numérico |\n| KG_LIQUIDO | Peso líquido (kg) | Numérico |\n\n### Dados Municipais (SH4)\n| Variável | Descrição | Tipo |\n|----------|-----------|------|\n| CO_ANO | Ano | Numérico |\n| SH4 | Código SH4 | Numérico |\n| CO_PAIS | Código do país | Numérico |\n| SG_UF_MUN | UF da empresa | Caractere |\n| CO_MUN | Código do município da empresa | Numérico |\n| VL_FOB | Valor FOB (US$) | Numérico |\n\n### Métricas Específicas de Importação\n- **VL_FRETE**: Valor do frete (US$)\n- **VL_SEGURO**: Valor do seguro (US$)\n- **VL_TOTAL_CIF**: FOB + Frete + Seguro (calculado automaticamente)\n- **PERC_FRETE**: Percentual do frete sobre FOB\n- **PERC_SEGURO**: Percentual do seguro sobre FOB\n\n---\n\n## 🔧 Funções Principais\n\n### Tabelas de Referência\n| Função | Descrição |\n|--------|-----------|\n| `show_available_tables()` | Lista tabelas disponíveis |\n| `load_reference_tables(codes)` | Carrega tabelas por código |\n| `search_in_table(code, term)` | Busca termo em tabela |\n\n### Análise de Dados\n| Função | Descrição |\n|--------|-----------|\n| `comex_stat_geral_exps()` | Exportações gerais (NCM) |\n| `comex_stat_geral_imps()` | Importações gerais (NCM) |\n| `analise_comex_municipal()` | Dados municipais (SH4) |\n\n### Códigos de Tabelas\n- **\"1\"**: NCM (Nomenclatura Comum do Mercosul)\n- **\"2\"**: NCM com códigos SH\n- **\"3\"**: Países\n- **\"4\"**: Unidades Federativas\n- **\"5\"**: UF e Municípios\n\n---\n\n## 🎯 Casos de Uso\n\n### 🌾 **Agronegócio**\n- Análise de exportações de commodities por região\n- Monitoramento de preços e volumes por destino\n- Identificação de novos mercados\n\n### 🏭 **Indústria**\n- Análise de importação de insumos e máquinas\n- Cálculo de custos logísticos (frete/seguro)\n- Competitividade por setor\n\n### 🏛️ **Política Pública**\n- Impacto regional do comércio exterior\n- Análise de balança comercial setorial\n- Monitoramento de acordos comerciais\n\n### 📊 **Pesquisa Acadêmica**\n- Estudos de economia internacional\n- Análise de competitividade\n- Séries temporais de comércio exterior\n\n---\n\n## ⚡ Dicas de Performance\n\n### ✅ **Boas Práticas**\n```r\n# Use filtros específicos\nresultado \u003c- comex_stat_geral_exps(\n    anos = 2024,\n    sh4 = c(1201, 1202),  # Específico\n    co_pais = c(160)      # China apenas\n)\n\n# Aproveite o cache\ndados_2024 \u003c- comex_stat_geral_exps(anos = 2024)  # Primeira vez: download\ndados_2024_novo \u003c- comex_stat_geral_exps(anos = 2024)  # Segunda vez: cache\n```\n\n### ❌ **Evitar**\n```r\n# Muito amplo - pode consumir muita memória\ndados_tudo \u003c- comex_stat_geral_exps(anos = c(2020:2024))  # Evitar\n\n# Sempre force_download = TRUE desnecessário\ndados \u003c- comex_stat_geral_exps(anos = 2024, force_download = TRUE)  # Evitar\n```\n\n---\n\n## 🐛 Solução de Problemas\n\n### Erro: \"Nenhum registro encontrado\"\n```r\n# Verificar códigos válidos\nsearch_in_table(\"1\", \"produto_desejado\")  # Para NCM\nsearch_in_table(\"3\", \"pais_desejado\")     # Para países\n```\n\n### Problemas de Conectividade\n```r\n# Testar conectividade\ntryCatch({\n    test_data \u003c- load_reference_tables(\"3\")\n    cat(\"Conexão OK\\n\")\n}, error = function(e) {\n    cat(\"Erro de conexão:\", e$message, \"\\n\")\n})\n```\n\n### Limpar Cache (se necessário)\n```r\n# Use force_download apenas se necessário\ndados_fresh \u003c- comex_stat_geral_exps(anos = 2024, force_download = TRUE)\n```\n\n---\n\n## 📖 Documentação Completa\n\n- **📄 Documentação Técnica e Detalhes do Pacote**: [comexTL](https://alanleal-econ.com/index.php/codes/comextl/)\n- **❓ Ajuda Integrada**: Use `?nome_da_funcao` no R\n- **🐛 Issues**: [GitHub Issues](https://github.com/alanleal-econ/comexTL/issues)\n\n---\n\n## 🤝 Contribuindo\n\nContribuições são bem-vindas! \n\n### Como Contribuir\n1. **Fork** do repositório\n2. **Clone** para sua máquina\n3. Crie uma **branch** para sua feature\n4. Faça suas modificações com **testes**\n5. **Commit** com mensagens descritivas\n6. **Push** para sua branch\n7. Abra um **Pull Request**\n\n### Tipos de Contribuições\n- 🐛 **Bug reports** via GitHub Issues\n- 💡 **Sugestões** de funcionalidades\n- 📝 **Melhorias** na documentação\n- 🧪 **Testes** adicionais\n- 🚀 **Novas funcionalidades**\n\n---\n\n## 📄 Licença\n\nEste projeto está licenciado sob a Licença MIT - veja o arquivo [LICENSE](LICENSE) para detalhes.\n\n---\n\n## 👨‍💻 Autor\n\n**Alan Leal** - Economista especializado em comércio, meio ambiente e clima.\n\n- 🐙 **GitHub**: [@alanleal-econ](https://github.com/alanleal-econ)\n- 📧 **Email**: prof@alanleal-econ.com\n- 🏢 **Homepage Alan Leal**: [alanleal-econ.com](https://alanleal-econ.com)\n\n---\n\n## 🙏 Agradecimentos\n\n- **SECEX/MDIC** pela disponibilização dos dados abertos\n- **Apache Arrow** pela tecnologia de processamento eficiente\n- **Cloudflare** pela infraestrutura de distribuição\n\n---\n\n## 📊 Status do Projeto\n\n![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)\n![GitHub last commit](https://img.shields.io/github/last-commit/alanleal-econ/comexTL)\n![GitHub issues](https://img.shields.io/github/issues/alanleal-econ/comexTL)\n\n**Status**: 🚧 Em desenvolvimento ativo\n**Versão**: Pré-release\n**Compatibilidade**: R 4.0+\n\n---\n\n*Transforme dados de comércio exterior em insights poderosos com comexTL! 🚀*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falanleal-econ%2Fcomextl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falanleal-econ%2Fcomextl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falanleal-econ%2Fcomextl/lists"}