PHPackages                             andmarruda/laravel-ibge - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. andmarruda/laravel-ibge

ActiveLibrary[API Development](/categories/api)

andmarruda/laravel-ibge
=======================

Cliente Laravel para a API de Metadados do IBGE

0.1.0(1mo ago)01MITPHPPHP ^8.2

Since Jun 12Pushed 1mo agoCompare

[ Source](https://github.com/andmarruda/laravel-ibge)[ Packagist](https://packagist.org/packages/andmarruda/laravel-ibge)[ RSS](/packages/andmarruda-laravel-ibge/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (9)Versions (2)Used By (0)

Laravel IBGE
============

[](#laravel-ibge)

Package Laravel para consumir e sincronizar dados da [API de Metadados do IBGE](https://apimetadados.ibge.gov.br/).

Inclui cache configurável, persistência em banco de dados, migrations publicáveis, modelos Eloquent e jobs para atualização mensal.

Instalação via Composer
-----------------------

[](#instalação-via-composer)

Instale o package diretamente pelo Composer:

```
composer require andmarruda/laravel-ibge
```

O Laravel descobre automaticamente o service provider e a facade do package.

Para publicar a configuração:

```
php artisan vendor:publish --tag=ibge-config
```

As migrations são carregadas automaticamente. Para publicá-las no projeto e poder customizá-las:

```
php artisan vendor:publish --tag=ibge-migrations
php artisan migrate
```

Caso não queira customizar as migrations, basta executar:

```
php artisan migrate
```

Início rápido
-------------

[](#início-rápido)

Consulte a API usando a facade:

```
use Andmarruda\LaravelIbge\Facades\Ibge;

$pesquisas = Ibge::pesquisas();
$ocorrencias = Ibge::ocorrencias('CD');
$censo2010 = Ibge::ocorrencia('CD', 2010);
$metas = Ibge::metas(6);
$ficha = Ibge::fichaMetodologica('6-1-1');
```

Uso
---

[](#uso)

```
use Andmarruda\LaravelIbge\Ibge;
use Andmarruda\LaravelIbge\Facades\Ibge as IbgeFacade;

$ibge = app(Ibge::class);

$pesquisas = $ibge->pesquisas();
$ocorrencias = $ibge->ocorrencias('CD');
$censo2010 = $ibge->ocorrencia('CD', 2010);
$metas = $ibge->metas(6);
$ficha = $ibge->fichaMetodologica('6-1-1');

$pesquisas = IbgeFacade::pesquisas();
```

Os resultados são arrays iguais aos retornados pelo IBGE. Assim, novos campos adicionados pela API ficam imediatamente disponíveis sem exigir uma nova versão do package.

Endpoints mapeados
------------------

[](#endpoints-mapeados)

Método do packageEndpoint IBGE`pesquisas()``GET /api/Pesquisa``ocorrencias($codigo)``GET /api/ocorrenciaPesquisa/{codigo}``ocorrencia($codigo, $ano, $mes, $ordem)``GET /api/ocorrenciaPesquisa/{codigo}/{ano}/{mes}/{ordem}``metas($objetivo)``GET /api/ODS/Metas/{objetivo}``fichaMetodologica($indicador)``GET /api/ODS/FichaMetodologica/{indicador}`Cache
-----

[](#cache)

O cache é aplicado pelo decorator `CachedMetadataGateway`, sem acoplar essa responsabilidade ao cliente HTTP.

Formato das chaves:

```
{prefix}:{schema_version}:{resource}:{sha256_dos_parametros}

```

Exemplos:

```
ibge:metadata:v1:pesquisas:all
ibge:metadata:v1:ocorrencias:2f...
ibge:metadata:v1:ods_metas:9a...

```

O `schema_version` permite invalidar todo o formato anterior quando a estrutura interna do cache mudar. Os TTLs são separados por recurso em `config/ibge.php`, pois catálogos e ocorrências podem ter ritmos de atualização diferentes.

Variáveis disponíveis:

```
IBGE_METADATA_BASE_URL=https://apimetadados.ibge.gov.br/api
IBGE_METADATA_CACHE_ENABLED=true
IBGE_METADATA_CACHE_STORE=redis
IBGE_METADATA_CACHE_PREFIX=ibge:metadata
IBGE_METADATA_CACHE_TTL_PESQUISAS=7776000
IBGE_METADATA_CACHE_TTL_OCORRENCIAS=7776000
IBGE_METADATA_CACHE_TTL_OCORRENCIA=7776000
IBGE_METADATA_CACHE_TTL_ODS_METAS=7776000
IBGE_METADATA_CACHE_TTL_ODS_FICHA=7776000
```

O padrão é de `7.776.000` segundos, equivalente a 90 dias. A sincronização mensal força a substituição dos valores mesmo quando o cache ainda está válido.

Sincronização mensal
--------------------

[](#sincronização-mensal)

O comando abaixo enfileira a atualização completa:

```
php artisan ibge:sync
```

Fluxo dos jobs:

```
SyncIbgeMetadata
    -> SyncPesquisaMetadata (uma por pesquisa)
        -> SyncPesquisaOccurrence (uma por ocorrência)
    -> SyncOdsObjective (objetivos 1 a 17)
        -> SyncOdsIndicator (um por indicador)

```

Configure um worker de filas e agende o comando mensalmente:

```
php artisan queue:work --queue=ibge,default
```

```
use Illuminate\Support\Facades\Schedule;

Schedule::command('ibge:sync')
    ->monthly()
    ->withoutOverlapping();
```

Fila e conexão podem ser configuradas:

```
IBGE_METADATA_SYNC_CONNECTION=redis
IBGE_METADATA_SYNC_QUEUE=ibge
IBGE_METADATA_DATABASE_ENABLED=true
IBGE_METADATA_DATABASE_CONNECTION=mysql
```

Banco de dados
--------------

[](#banco-de-dados)

A sincronização salva os dados em quatro tabelas:

TabelaConteúdo`ibge_pesquisas`Catálogo de pesquisas`ibge_pesquisa_ocorrencias`Lista e detalhes das ocorrências`ibge_ods_metas`Metas dos objetivos ODS`ibge_ods_indicadores`Indicadores e fichas metodológicasCada tabela mantém campos úteis para consulta e um `payload` JSON com a resposta completa da API.

Modelos Eloquent disponíveis:

```
use Andmarruda\LaravelIbge\Models\OdsIndicador;
use Andmarruda\LaravelIbge\Models\OdsMeta;
use Andmarruda\LaravelIbge\Models\Pesquisa;
use Andmarruda\LaravelIbge\Models\PesquisaOcorrencia;

$pesquisas = Pesquisa::with('ocorrencias')->get();
$indicadores = OdsIndicador::with('meta')->get();
```

Arquitetura evolutiva
---------------------

[](#arquitetura-evolutiva)

```
Aplicação Laravel
    -> Ibge (API pública estável)
        -> MetadataGateway (contrato)
            -> CachedMetadataGateway (decorator opcional)
                -> HttpMetadataGateway (API externa)

```

- `Ibge` mantém a API pública do package pequena e estável.
- `MetadataGateway` é o ponto de substituição para uma API v2, fixtures ou outra fonte.
- `HttpMetadataGateway` concentra rotas, retry, timeout e tradução de erros.
- `CachedMetadataGateway` pode evoluir independentemente para stale-while-revalidate ou locks.
- `CacheKeyFactory` versiona o schema e pode ser substituído por aplicações consumidoras.
- Respostas brutas evitam perda de dados quando o IBGE acrescentar campos. DTOs tipados podem ser adicionados no futuro como uma API opt-in.

As etapas de evolução, decisões e o schema completo estão em [docs/architecture.md](docs/architecture.md).

Para substituir a fonte de dados, registre outra implementação no container:

```
$this->app->singleton(
    \Andmarruda\LaravelIbge\Contracts\MetadataGateway::class,
    MinhaFonteDeMetadados::class,
);
```

Testes
------

[](#testes)

```
composer test
```

[![Buy Me a Coffee](https://camo.githubusercontent.com/e9f620d2e66a42c2710bb476e61c2167259d285730e4601ac73e12f104ec08d9/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4275792532304d6525323061253230436f666665652d737570706f72742d79656c6c6f773f6c6f676f3d6275792d6d652d612d636f66666565266c6f676f436f6c6f723d7768697465)](https://buymeacoffee.com/andmarruda)

###  Health Score

35

—

LowBetter than 77% of packages

Maintenance90

Actively maintained with recent releases

Popularity1

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity36

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

46d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/fad9d7cc83409d7c7896bc4d1977165fb14125e7accd1429d8e4e3ab462e5e2d?d=identicon)[andmarruda](/maintainers/andmarruda)

---

Top Contributors

[![andmarruda](https://avatars.githubusercontent.com/u/29872593?v=4)](https://github.com/andmarruda "andmarruda (4 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/andmarruda-laravel-ibge/health.svg)

```
[![Health](https://phpackages.com/badges/andmarruda-laravel-ibge/health.svg)](https://phpackages.com/packages/andmarruda-laravel-ibge)
```

###  Alternatives

[laravel/pulse

Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application.

1.7k15.1M137](/packages/laravel-pulse)[mike-bronner/laravel-model-caching

Automatic caching for Eloquent models.

2.4k96.5k1](/packages/mike-bronner-laravel-model-caching)[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9762.4M134](/packages/roots-acorn)[psalm/plugin-laravel

Psalm plugin for Laravel

3345.3M348](/packages/psalm-plugin-laravel)[flarum/core

Delightfully simple forum software.

211.4M2.4k](/packages/flarum-core)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

255.2k](/packages/aedart-athenaeum)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)