API › Location › Gateway Agregador # Gateway Agregador de Localização Consulta única que combina múltiplas famílias de enriquecimento geográfico — favelas, presídios, fronteira, renda, aglomerações, tipologia e setor censitário — a partir de uma coordenada ou de um endereço. Categoria Location Enriquecimentos 8 famílias em uma única chamada Entrada Coordenada ou Endereço Batch Disponível Nesta página Aplicações Conceito Convenção de sinais Entradas Exemplos Atributos retornados Detalhes técnicos Limitações Para que serve ## Aplicações O Gateway Agregador foi desenhado para casos em que uma decisão precisa combinar múltiplos sinais geográficos de uma mesma coordenada — evitando N chamadas paralelas às APIs individuais e reduzindo a latência total do fluxo de decisão. #### Onboarding com múltiplos sinais Em uma única chamada, obtenha proximidade a favelas, presídios, fronteira, renda da região e setor censitário para decisões de KYC. #### Antifraude documental Combine geocoder + presídio + favela + tipologia para validar coerência entre endereço declarado e características territoriais. #### Enriquecimento de carteira Enriqueça uma base grande de clientes em batch com múltiplas famílias de atributos geográficos, sem orquestrar chamadas separadas. #### Score composto Alimente modelos preditivos com features de várias famílias em uma única resposta — ideal para pipelines de scoring online. Entendendo o produto ## Conceito O Gateway Agregador é um **meta-produto** : ele não gera dados próprios, mas expõe uma camada de composição que dispara — em paralelo, no backend — as APIs individuais da família Location e devolve o resultado consolidado em um único payload. Cada família é habilitada por uma flag booleana no request; famílias não habilitadas não são consultadas e não geram custo. Em vez de sua aplicação orquestrar N chamadas HTTP às APIs de favelas, presídios, fronteira, renda estática, renda dinâmica (PDF), aglomerações comerciais, setor censitário (InfoSC) e tipologia, você faz **uma única requisição** ao Gateway. A resposta traz todos os campos das famílias habilitadas com prefixo `prismadata____*`, evitando colisões de nomes entre APIs. Interpretação ## Convenção de Sinais Cada flag habilitada equivale a **uma consulta adicional** à API correspondente. Flags não habilitadas (default `false`) não geram chamada nem cobrança. Os campos retornados são sempre prefixados por família, permitindo identificar a origem de cada atributo no payload consolidado. ● **flag = true** A família correspondente é consultada e seus campos `prismadata____*` aparecem na resposta. ○ **flag = false (default)** A família não é consultada. Nenhum campo daquela família aparece na resposta e não há cobrança para aquela família. Request ## Parâmetros de Entrada O Gateway expõe três operações: `GET /location/aggregator` (por coordenada), `POST /location/batch/aggregator` (múltiplos pontos) e `GET /location/geocoder/aggregator` (por endereço, com geocodificação embutida). ### Coordenada (`/aggregator` e `/batch/aggregator`) `lat` float Latitude WGS84 do ponto de consulta. Faixa: (-90, 90). `lng` float Longitude WGS84 do ponto de consulta. Faixa: (-180, 180). ### Endereço (`/geocoder/aggregator`) `endereco_completo` string Endereço completo em texto livre para geocodificação. Máx. 100 caracteres. `cep` string CEP do endereço. Máx. 9 caracteres. `numero` string Número do endereço. `tipo_logradouro` string Tipo do logradouro (ex.: Rua, Avenida). `titulo_logradouro` string Título do logradouro (ex.: Coronel, Professor). `logradouro` string Nome do logradouro. `localidade` string Localidade (bairro) do endereço. `municipio` string Município do endereço. `estado` string Estado do endereço. ### Flags de habilitação (comuns a todos os endpoints) `slum` boolean Habilita retorno de informações de favelas (`prismadata__slum__*`). `prison` boolean Habilita retorno de informações de presídios (`prismadata__prison__*`). `border` boolean Habilita retorno de informações de fronteiras (`prismadata__border__*`). `infosc` boolean Habilita retorno de informações do setor censitário (`prismadata__infosc__*`). `personal_income_static` boolean Habilita retorno de renda estática (`prismadata__personal_income_static__*`). `personal_income_pdf` boolean Habilita retorno de renda dinâmica via PDF (`prismadata__personal_income_pdf__*`). Aceita filtros demográficos opcionais: `date_income`, `gender`, `age`, `is_responsible`, `income_compared`. `commercial_cluster` boolean Habilita retorno de aglomerações comerciais (`prismadata__commercial_cluster__*`). `tipologia` boolean Habilita retorno de tipologia (`prismadata__tipologia__*`). Na prática ## Exemplos Dois cenários ilustram a diferença entre a chamada por coordenada com múltiplas famílias habilitadas e a chamada por endereço, que executa geocodificação e agregação em uma única operação. /aggregator — coordenada com 3 flags ligadas (slum, infosc, personal_income_static) -19.932378368680315, -43.9351245162891 favela setor censitário ponto + 3 famílias habilitadas { "prismadata__slum__favela_distancia_m": 132.96, "prismadata__slum__favela_municipio": "Belo Horizonte", "prismadata__infosc__municipio": "Belo Horizonte", "prismadata__infosc__situacao": "Urbana", "prismadata__personal_income_static__faixa_sm_min": 5.0, "prismadata__personal_income_static__faixa_sm_max": 10.0, "prismadata__personal_income_static__percentil_br": 98 } A resposta contém apenas os campos das três famílias habilitadas — cada bloco vem com o prefixo `prismadata__slum__`, `prismadata__infosc__` e `prismadata__personal_income_static__`. Nenhuma outra família foi consultada. /geocoder/aggregator — endereço + agregação em uma chamada cep=30130-165 (Belo Horizonte, MG) aglomeração comercial endereço geocodificado geocoder + agregação em 1 chamada { "prismadata__geocoder__latitude": -19.93292236328125, "prismadata__geocoder__longitude": -43.935611724853516, "prismadata__geocoder__municipio": "BELO HORIZONTE", "prismadata__slum__favela_distancia_m": 132.96, "prismadata__infosc__municipio": "Belo Horizonte", "prismadata__commercial_cluster__aglomeracao_hash": "5e28444d2cee", "prismadata__commercial_cluster__nome_aglomeracao": "Rua Bittencourt" } A resposta traz sempre o bloco `prismadata__geocoder__*` com as coordenadas obtidas pela geocodificação e, em seguida, os campos das famílias habilitadas (aqui: `slum`, `infosc` e `commercial_cluster`) — tudo em um único round-trip. Response ## Atributos Retornados O Gateway apenas repassa os campos das APIs individuais, prefixados por família. Para a lista completa de atributos de cada família, consulte a documentação dedicada — as tabelas de cada produto são a fonte de verdade para nomes, tipos e semântica dos campos. Prefixos por família prismadata__slum__* Campos de proximidade a favelas, complexos e ilhas. Ver [favelas.html](). prismadata__prison__* Campos de proximidade e características de unidades prisionais. Ver [presidio.html](). prismadata__border__* Campos de proximidade a fronteiras nacionais. Ver [border.html](). prismadata__infosc__* Campos de setor censitário (município, situação urbana/rural, etc.). Ver [infosc.html](). prismadata__tipologia__* Campos de tipologia (finalidade, espécie, indicador de estabelecimento). Ver [tipologia.html](). prismadata__personal_income_static__* Campos de renda estática (faixas em salários mínimos, percentis). Ver [renda_estatica.html](). prismadata__personal_income_pdf__* Campos de renda dinâmica via PDF (mean, median, comparações demográficas). Ver [renda_dinamica.html](). prismadata__commercial_cluster__* Campos de aglomerações comerciais (hash, nome, indicador de contido). Ver [aglomeracoes_comerciais.html](). prismadata__geocoder__* Apenas em `/geocoder/aggregator`: campos de geocodificação (latitude, longitude, município resolvido). Ver [geocoder.html](). Referência ## Detalhes Técnicos #### Fontes Cada família preserva sua própria origem de dados. O Gateway não introduz novas fontes — ele compõe respostas das APIs individuais de favelas, presídios, fronteira, InfoSC, tipologia, renda (estática e PDF) e aglomerações comerciais. #### Metodologia Agregação single-round-trip: uma requisição HTTP dispara, no backend, chamadas paralelas às APIs habilitadas e devolve o resultado consolidado. Cada campo é prefixado por `prismadata____` para evitar colisões. #### Frequência de Atualização Herda a frequência de cada família consultada — não há defasagem adicional introduzida pelo Gateway. Consulte a documentação de cada produto para a cadência específica. #### Cobertura Território nacional. Cada família tem sua própria cobertura (raios máximos, disponibilidade urbana/rural). Campos podem retornar `null` em áreas fora da cobertura da família específica. Atenção ## Limitações #### Considere ao utilizar * Coordenadas inválidas (fora das faixas (-90, 90) para latitude e (-180, 180) para longitude) fazem a requisição falhar antes de qualquer enriquecimento ser executado. * O campo `prismadata__tipologia__*` pode não retornar dados quando a região consultada não tem cobertura — verifique `prismadata__tipologia__cobertura` e `prismadata__tipologia__motivo_sem_cobertura`. * Em `/geocoder/aggregator`, se a geocodificação falhar (endereço não reconhecido), nenhuma das famílias de enriquecimento é executada — todos os campos retornam ausentes ou nulos. * Cada flag habilitada equivale a uma consulta cobrada separadamente. Habilite apenas as famílias necessárias ao caso de uso para otimizar custo. * A latência do Gateway é limitada pela API mais lenta entre as habilitadas — considere isso ao definir timeouts na sua aplicação. ## Pronto para testar? Experimente o Gateway Agregador no playground de Inteligência de Localização e monte a combinação de famílias ideal para o seu caso de uso. [ Abrir playground ](<../api-playground/inteligencia-de-localizacao/>)