API › Location › Análise de Histórico de Localização # Análise de Histórico de Localização A partir de uma série temporal de coordenadas (lat, lng, timestamp), identificamos os locais recorrentes e classificamos cada cluster como **moradia** , **trabalho** , **visita frequente** ou **visita eventual**. Compartilha backend com o [Validador de Endereço](), mas é produto distinto — foco em rotina, não em confirmação de endereço declarado. Categoria Location Método Clusterização espacial + classificação temporal Endpoint POST /location/addr_validation/cluster_location_historic Entrada Lista de [lat, lng, timestamp] Nesta página Aplicações Conceito Convenção de sinais Formas de consulta Exemplos Atributos retornados Detalhes técnicos Limitações Para que serve ## Aplicações Um dispositivo móvel deixa rastro. Ele passa a noite em um endereço, o dia em outro, aparece semanalmente em um terceiro e vai a um quarto uma vez no mês. Ao passar essa série ao endpoint, obtemos os locais recorrentes e uma pergunta clara para cada um: _o que é este cluster para a pessoa?_ #### Confirmação de moradia Compare o endereço com maior score de `moradia` ao endereço declarado no cadastro. Sinal forte de residência real, sem depender de comprovante de renda. #### Contexto de trabalho e rotina Identifique o local com maior score de `trabalho` — útil pra checar coerência com atividade declarada em onboarding e pra análise de risco com contexto de rotina real. #### Antifraude e disputa transacional Cruze o local de uma compra contestada com os clusters do titular do cartão. Compra em cluster com alto `visita_frequente` ou `visita_eventual` aponta transação plausível; ponto fora de qualquer cluster reforça suspeita. #### Rotina, mobilidade e cobertura de PDV Caracterize deslocamento entre municípios, tempo em cada polo e quantidade de locais recorrentes — insumo para seguros de vida/auto, planos de saúde e planejamento de PDV. Entendendo o dado ## Conceito A API recebe uma **lista de tuplas** `[lat, lng, timestamp]` — tipicamente 30 dias de sinais de localização de um dispositivo móvel ou app, com timestamp em Unix seconds — e devolve uma lista de **clusters**. Cada cluster representa um local recorrente, com endereço obtido por geocodificação reversa e quatro _scores_ de classificação: `moradia`, `trabalho`, `visita_frequente` e `visita_eventual`. A classificação é feita a partir do padrão temporal em que os pontos do cluster caem: presença noturna sustentada puxa `moradia`; presença em horário comercial em dias úteis puxa `trabalho`; presenças esparsas em fins de semana ou em dias distintos puxam as duas variantes de visita. Cada score volta em duas escalas — bruta (`moradia`) e normalizada de 0 a 1 dentro da resposta (`moradia_normalizado`). Ler a normalizada é o caminho direto para comparar clusters entre si. **Mesma família, produto distinto:** este endpoint compartilha backend com o [Validador de Endereço](). O Validador confirma um endereço declarado contra a rotina; esta API vai um passo antes: _quais são os endereços da rotina, e qual é o papel de cada um_. Se você já tem endereço declarado, use o Validador. Se quer descobrir a rotina, use esta. Interpretação ## Como ler os scores Os quatro scores normalizados (0 a 1) somam informação sobre **o mesmo** cluster — não é uma partição exclusiva. Um cluster pode ter `moradia_normalizado = 0.9` _e_ `visita_frequente_normalizado = 0.5`: é a casa em que a pessoa mora e também recebe visitas com regularidade. Ler o vetor inteiro, não apenas o maior. ○ **moradia_normalizado alto ( > 0,6)** Endereço com presença noturna dominante e frequência elevada. Bom candidato a endereço residencial da pessoa. Compare com o endereço declarado no cadastro. ○ **trabalho_normalizado alto ( > 0,6)** Endereço com presença dominante em horário comercial em dias úteis. Bom candidato a local de trabalho ou estudo. Cruze com CNAE do CNPJ do estabelecimento no local. ● **visita_frequente_normalizado alto** Cluster com presença recorrente mas sem padrão de moradia ou trabalho. Locais frequentados semanalmente — casa de familiares, academia, igreja. ● **visita_eventual_normalizado alto** Presença esparsa, poucos pontos, sem padrão de repetição. Locais visitados ocasionalmente. ● **Vetor todo baixo ( < 0,2 em tudo)** Cluster com poucos pontos ou sem padrão temporal claro. Interprete com cautela — pode ser deslocamento em trânsito, ou volume insuficiente de sinais para caracterização. Request ## Formas de consulta Uma chamada, um caminho: **POST** com uma lista de tuplas `[lat, lng, timestamp]` no corpo. O tamanho recomendado é a janela de 30 dias de sinais do dispositivo — normalmente algumas centenas a poucos milhares de pontos. A resposta traz a lista de clusters identificados, na mesma requisição. Endpoint em produção. Caminho relativo à base `https://api.prismadata.io/v1`. O que você tem | Endpoint | Corpo ---|---|--- Série temporal de sinais de localizaçãotuplas [lat, lng, timestamp] | `POST /location/addr_validation/cluster_location_historic` | `[[lat, lng, ts], …]` * **Formato do timestamp** Unix seconds (número inteiro ou de ponto flutuante). Cada tupla é uma medição — a mesma coordenada aparecendo em vários timestamps é o que descreve presença sustentada. Não envie a série ordenada por coordenada; envie na ordem cronológica em que os sinais foram coletados. * **Volume de pontos importa** Séries com poucas dezenas de pontos tendem a produzir clusters com todos os scores baixos e classificação ambígua. A recomendação de operação é enviar pelo menos a janela de 30 dias com coleta razoavelmente densa (várias medições por dia). Com menos que isso, trate scores baixos como "dado insuficiente", não como "lugar irrelevante". * **Compartilha backend com o Validador de Endereço, é produto distinto** O mesmo serviço interno responde por este endpoint e por `POST /location/addr_validation/compare_address` (Validador). Se você já tem endereço declarado e quer confirmá-lo contra a rotina, use o [Validador](). Se quer descobrir a rotina para depois usá-la (endereços de moradia, trabalho, visitas), use este endpoint. * **Sem persistência** A série de pontos que você envia não é armazenada; a resposta é calculada e devolvida na mesma requisição. Se você quer reprocessar, envie a série de novo. ### Parâmetros `body` array · obrigatório Lista de tuplas `[lat, lng, timestamp]`. `lat` em graus decimais WGS84 (−90 a 90), `lng` em graus decimais WGS84 (−180 a 180), `timestamp` em Unix seconds. Na prática ## Exemplos Uma série de 9 pontos submetida ao endpoint em 2026-09-23, cobrindo Belo Horizonte (Savassi, sede da PrismaData; Anchieta) e São Paulo (Avenida Paulista). Timestamps em Unix seconds. Os 3 clusters identificados abaixo vêm exatamente do que a API devolveu — recorte dos campos mais relevantes. Corpo enviado POST /v1/location/addr_validation/cluster_location_historic [ [-19.9327, -43.9354, 1730000000], [-19.9327, -43.9354, 1730020000], [-19.9327, -43.9354, 1730050000], [-19.9450, -43.9300, 1730080000], [-19.9450, -43.9300, 1730100000], [-19.9450, -43.9300, 1730120000], [-23.5614, -46.6559, 1730250000], [-23.5614, -46.6559, 1730260000], [-19.9327, -43.9354, 1730290000] ] Cluster 0 · Savassi, Belo Horizonte R. Alagoas, 601 { "cluster_id": 0, "endereco_completo": "RUA ALAGOAS, 601 - SAVASSI, BELO HORIZONTE - MG, 30130-160", "distancia_m": 11.93, "moradia_normalizado": 0.40, "trabalho_normalizado": 0.75, "visita_frequente_normalizado": 0.0, "visita_eventual_normalizado": 0.0 } **trabalho_normalizado 0,75** domina. É o candidato principal a local de trabalho. O **moradia_normalizado 0,40** aparece porque a série da amostra concentra os pontos em horários que também cobrem o dia — com uma janela maior de 30 dias e sinais noturnos claros, um dos dois padrões se destacaria mais. A distância do centróide ao endereço geocodificado é 11,93 m, portanto match direto na porta. Cluster 1 · Anchieta, Belo Horizonte R. Montes Claros, 570 { "cluster_id": 1, "endereco_completo": "RUA MONTES CLAROS, 570 - ANCHIETA, BELO HORIZONTE - MG, 30310-702", "distancia_m": 25.11, "moradia_normalizado": 0.20, "trabalho_normalizado": 0.25, "visita_frequente_normalizado": 0.40, "visita_eventual_normalizado": 0.40 } Vetor equilibrado — **0,40 em visita_frequente e visita_eventual** , com moradia e trabalho baixos. Perfil típico de local que a pessoa frequenta em cadência regular mas sem virar rotina fixa. Aqui é onde ler o vetor inteiro paga: um único "maior" não descreve o cluster; a coexistência dos dois é o sinal. Cluster 2 · Bela Vista, São Paulo Av. Paulista, 1578 { "cluster_id": 2, "endereco_completo": "AVENIDA PAULISTA, 1578 - BELA VISTA, SAO PAULO - SP, 01310-200", "distancia_m": 25.65, "moradia_normalizado": 0.007, "trabalho_normalizado": 0.006, "visita_eventual_normalizado": 0.31, "visita_frequente_normalizado": 0.11 } Só duas passagens na série, em outro município. Moradia e trabalho ≈ 0, **visita_eventual 0,31** é o único score de destaque. Leitura correta: ida ocasional a São Paulo. O cluster ainda apareceu porque duas medições próximas no tempo, no mesmo ponto geográfico, formam um cluster mínimo — mas os scores baixos indicam para tratar como visita, não como rotina. Os JSONs acima são recortes ilustrativos. Todos os 22 campos por cluster estão descritos na próxima seção; o retorno completo traz os campos com o prefixo `prismadata__cluster_historic_location__`. Response ## Atributos Retornados O retorno é `{ "items": [ … ] }`. Cada item é um cluster com 22 campos, todos prefixados por `prismadata__cluster_historic_location__` (omitido nas tabelas abaixo por legibilidade). Os grupos abaixo são organização didática, não estrutura no payload. Identificação cluster_id Identificador do cluster dentro da resposta. Números sequenciais a partir de 0. Não é estável entre chamadas — ao reenviar a mesma série, o mesmo cluster pode receber id diferente. Localização latitude_input, longitude_input Coordenada do centróide calculado a partir dos pontos de entrada agrupados no cluster. latitude_endereco, longitude_endereco Coordenada do endereço obtido por geocodificação reversa a partir do centróide. distancia_m Distância em metros entre o centróide (input) e o endereço geocodificado. Valores baixos indicam que o cluster caiu diretamente sobre um endereço cadastrado; valores altos, que o cluster está entre endereços — bom para investigar espaços abertos ou vias. Endereço endereco_completo Endereço completo do centróide (logradouro, número, bairro, cidade, UF, CEP), obtido por geocodificação reversa. cep CEP do endereço. logradouro, numero Logradouro (rua, avenida, etc.) e número do endereço. localidade Bairro ou região do endereço. municipio, uf, cod_municipio Nome do município, sigla da UF e código IBGE do município (7 dígitos). Classificação (bruta + normalizada) moradia, moradia_normalizado Score bruto e score normalizado (0 a 1 dentro da resposta) de afinidade do cluster com o padrão de moradia — presença noturna sustentada, frequência elevada e regularidade ao longo dos dias. trabalho, trabalho_normalizado Score bruto e normalizado para o padrão de trabalho — presença em horário comercial em dias úteis. visita_frequente, visita_frequente_normalizado Score bruto e normalizado para visitas recorrentes — cluster com pontos repetidos em cadência semanal ou similar, mas sem padrão de moradia ou trabalho. visita_eventual, visita_eventual_normalizado Score bruto e normalizado para visitas esparsas — poucos pontos, sem cadência clara. Referência ## Detalhes Técnicos #### Método Clusterização espacial baseada em DBSCAN com métrica haversine. A distância entre pontos usa a superfície terrestre, não distância euclidiana em graus — evita distorção em latitudes diferentes. Cada cluster resultante é então avaliado no eixo temporal pra atribuir os quatro scores (moradia, trabalho, visita frequente, visita eventual). #### Endereço do cluster O endereço retornado vem da geocodificação reversa do centróide do cluster. Usa a mesma base de logradouros do restante da plataforma PrismaData. Endereços muito rurais ou vias novas podem cair no logradouro mais próximo com `distancia_m` elevado. #### Volume recomendado Janela típica: 30 dias de sinais de um único dispositivo, com múltiplas medições por dia. Séries curtas produzem poucos clusters e scores baixos. #### Sem persistência A série é processada na própria requisição e não é armazenada. Reprocessar exige reenviar a série. A resposta é determinística: a mesma série produz o mesmo conjunto de clusters (o `cluster_id`, porém, não é estável entre chamadas). Atenção ## Limitações #### Considere ao utilizar * Os scores normalizados são **relativos à resposta em questão** — não são probabilidades absolutas. Compare clusters entre si dentro da mesma chamada, não valores fora da chamada. * Séries com poucas dezenas de pontos ou com sinais concentrados em janela curta produzem clusters com todos os scores baixos. Trate como "dado insuficiente", não como "lugar irrelevante". * O `cluster_id` é sequencial dentro da resposta e não é estável entre chamadas. Se você precisa identidade estável, faça o pareamento pelo endereço ou coordenada, não pelo id. * O dado descreve o dispositivo, não a pessoa. Múltiplos dispositivos por pessoa ou compartilhamento de dispositivo entre pessoas mudam a interpretação dos clusters — isso é decisão do cliente na construção da série de entrada. * LGPD: os pontos de localização são dado pessoal. O produto opera sob a premissa de que o cliente já obteve base legal apropriada para tratar essa série (consentimento, execução de contrato, legítimo interesse com avaliação de balanceamento). A PrismaData não armazena a série enviada, mas o cliente segue responsável pela cadeia de tratamento. ## Pronto para testar? Solicite acesso à API de Análise de Histórico de Localização e integre-a a fluxos de KYC, antifraude, análise de risco e inteligência de rotina. [ Solicitar acesso ]()