Documentação > Gateway Agregador de Localização

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
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__<familia>__*, 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__<familia>__* 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 
{
  "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) 
{
  "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__<familia>__ 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