PrismaData API (1.0.0)

A PrismaData API fornece dados geoespaciais e socioeconômicos do Brasil através de endpoints REST. Com uma única coordenada (latitude/longitude) você obtém informações sobre favelas, renda, presídios, fronteiras, setor censitário e mais.

Base URL: https://api.prismadata.io/v1

1. Conta PrismaData ativa
2. API Key (formato ak_xxxxxxxxxxxxxxxx) — obtida no painel ou via suporte

1. Autenticar

Use sua API Key diretamente no header X-Apikey de cada requisição. O gateway valida a chave e gerencia o token JWT internamente — não é necessário chamar /auth/token separadamente.

2. Chamar um endpoint

Envie uma coordenada para qualquer endpoint de localização. Exemplo: consultar o presídio mais próximo de um ponto.

3. Parsear a resposta

A resposta é um JSON com campos prefixados por prismadata__<serviço>__. Veja a seção Formato de Resposta para detalhes.

curl:

curl "https://api.prismadata.io/v1/location/prison?lat=-25.5&lng=-54.5" \
  -H "X-Apikey: ak_xxxxxxxxxxxxxxxx"

Python (httpx):

import httpx

resp = httpx.get(
    "https://api.prismadata.io/v1/location/prison",
    params={"lat": -25.5, "lng": -54.5},
    headers={"X-Apikey": "ak_xxxxxxxxxxxxxxxx"},
)
dados = resp.json()
nome = dados["prismadata__prison__nome_estabelecimento"]
print(nome or "Nenhum presídio próximo")

JavaScript (fetch):

const resp = await fetch(
  "https://api.prismadata.io/v1/location/prison?lat=-25.5&lng=-54.5",
  { headers: { "X-Apikey": "ak_xxxxxxxxxxxxxxxx" } }
);
const dados = await resp.json();
const nome = dados.prismadata__prison__nome_estabelecimento;
console.log(nome ?? "Nenhum presídio próximo");

Todas as respostas da API incluem headers de rate limiting que informam o estado atual da sua cota de requisições.

O rate limit é aplicado por usuário (identificado via token JWT) no API Gateway (KrakenD).

Além do rate limit por minuto, cada tenant pode possuir uma quota que limita o número total de requisições em um período maior (diário, semanal, mensal ou anual). Quando o tenant possui uma política de quota ativa, todas as respostas incluem os seguintes headers:

Quando a quota é excedida, a API retorna HTTP 429.

Quotas podem ser configuradas por endpoint ou globalmente para o tenant. Consulte seu contrato ou entre em contato com o suporte para detalhes sobre sua quota.

Quando o rate limit ou a quota são excedidos, a API retorna HTTP 429 com uma mensagem em texto plano indicando o motivo:

• Rate limit excedido: rate limit exceeded
• Quota excedida: limit exceeded: 1000 requests used, limit is 1000

Dica: Monitore o header X-Quota-Remaining nas respostas para evitar o 429 proativamente — quando o valor estiver baixo, reduza a taxa de requisições.

Ao receber um 429, o cliente deve:

1. Ler o header X-RateLimit-Reset ou X-Quota-Reset para saber quando a janela será reiniciada.
2. Aguardar até o timestamp indicado antes de reenviar a requisição.
3. Caso nenhum header de reset esteja disponível, usar backoff exponencial com jitter.

Exemplo em Python:

import time, random, httpx

def request_com_retry(client, method, url, **kwargs):
    for tentativa in range(5):
        resp = client.request(method, url, **kwargs)
        if resp.status_code != 429:
            return resp
        reset = (
            resp.headers.get("X-RateLimit-Reset")
            or resp.headers.get("X-Quota-Reset")
        )
        if reset:
            wait = max(0, int(reset) - int(time.time())) + 1
        else:
            wait = (2 ** tentativa) + random.uniform(0, 1)
        time.sleep(wait)
    return resp

Todos os campos de resposta seguem o padrão prismadata__<serviço>__<campo>, facilitando a identificação da origem de cada dado.

Objeto único (GET)

Endpoints GET retornam um objeto JSON plano com os campos do serviço:

{
  "prismadata__prison__nome_estabelecimento": "Unidade Penal X",
  "prismadata__prison__distancia_borda_m": 1010.79,
  "prismadata__prison__uf": "MS"
}

Dicionário indexado (batch POST)

Endpoints batch retornam um dicionário onde as chaves são os identificadores enviados na requisição e os valores são os objetos de resposta:

{
  "ponto_1": { "prismadata__prison__nome_estabelecimento": "...", ... },
  "ponto_2": { "prismadata__prison__nome_estabelecimento": "...", ... }
}

Quando um ponto está fora da área de cobertura de um serviço, os campos de detalhe retornam null. Isso indica ausência de dados, não um erro.

Porém, indicadores de proximidade ou pertencimento podem ter valor mesmo quando os campos de detalhe são null. Exemplo para um ponto longe de qualquer presídio:

{
  "prismadata__prison__ponto_dentro_presidio": false,
  "prismadata__prison__distancia_borda_m": 85000.5,
  "prismadata__prison__nome_estabelecimento": null,
  "prismadata__prison__uf": null,
  "prismadata__prison__tipo_estabelecimento": null
}

O padrão é: campos booleanos e de distância indicam relação espacial e geralmente têm valor; campos de detalhe (nome, tipo, UF) dependem de haver uma entidade próxima o suficiente.

Todas as respostas utilizam Content-Type: application/json.

Todas as respostas incluem os headers X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Veja a seção Rate Limiting & Quota para detalhes.

Erros 401, 403, 404, 429 e 500 retornam texto plano — use resp.text, não resp.json(). Exemplos de mensagens reais:

Erro 422 possui dois cenários distintos:

1. Gateway (KrakenD) — quando o tipo do query parameter é inválido (ex: lat=abc), o gateway rejeita a requisição antes de encaminhá-la ao serviço. Neste caso o corpo da resposta é vazio (content-length: 0).
2. Serviço (FastAPI) — quando o parâmetro tem tipo correto mas valor inválido (ex: lat ausente), o serviço retorna JSON no formato ValidationError.

Importante: sempre verifique se o corpo da resposta 422 tem conteúdo antes de fazer parse JSON.

Quando os parâmetros enviados são inválidos e a requisição chega ao serviço, a API retorna um 422 com o formato padrão do FastAPI:

{
  "detail": [
    {
      "type": "missing",
      "loc": ["query", "lat"],
      "msg": "Field required",
      "input": null
    }
  ]
}

Cada item em detail contém:

• type: tipo do erro (ex: missing, value_error, type_error)
• loc: localização do parâmetro (ex: ["query", "lat"], ["body", "coordenadas"])
• msg: mensagem descritiva do erro
• input: valor recebido (ou null se ausente)

Python (httpx):

import httpx

resp = httpx.get(
    "https://api.prismadata.io/v1/location/prison",
    params={"lat": -25.5, "lng": -54.5},
    headers={"X-Apikey": "ak_xxxxxxxxxxxxxxxx"},
)

if resp.status_code == 200:
    dados = resp.json()
elif resp.status_code == 422:
    # Gateway pode retornar 422 com body vazio
    if resp.headers.get("content-type", "").startswith("application/json") and resp.text:
        erros = resp.json()["detail"]
        for erro in erros:
            print(f"Erro em {erro['loc']}: {erro['msg']}")
    else:
        print("Parâmetro com tipo inválido (rejeitado pelo gateway)")
elif resp.status_code == 429:
    reset = resp.headers.get("X-RateLimit-Reset")
    print(f"Rate limit. Retry após timestamp {reset}")
else:
    # 401, 403, 404, 500 — corpo é texto plano
    print(f"Erro {resp.status_code}: {resp.text}")

JavaScript (fetch):

const resp = await fetch(
  "https://api.prismadata.io/v1/location/prison?lat=-25.5&lng=-54.5",
  { headers: { "X-Apikey": "ak_xxxxxxxxxxxxxxxx" } }
);

if (resp.ok) {
  const dados = await resp.json();
} else if (resp.status === 422) {
  // Gateway pode retornar 422 com body vazio
  const contentType = resp.headers.get("content-type") || "";
  const body = await resp.text();
  if (contentType.includes("application/json") && body) {
    const { detail } = JSON.parse(body);
    detail.forEach(e => console.error(`Erro em ${e.loc}: ${e.msg}`));
  } else {
    console.error("Parâmetro com tipo inválido (rejeitado pelo gateway)");
  }
} else if (resp.status === 429) {
  const reset = resp.headers.get("X-RateLimit-Reset");
  console.warn(`Rate limit. Retry após timestamp ${reset}`);
} else {
  // 401, 403, 404, 500 — corpo é texto plano
  console.error(`Erro ${resp.status}: ${await resp.text()}`);
}

O token JWT tem validade configurável de 1 a 15 minutos (default: 15 min), definida pelo administrador da conta por usuário. O campo exp no payload do JWT contém o timestamp Unix de expiração.

Com X-Apikey (recomendado)

O gateway renova o token automaticamente a cada requisição. Nenhum tratamento especial é necessário.

Com username/password via /auth/token

Ao gerenciar o JWT diretamente, extraia o campo exp dos claims e renove o token antes da expiração:

import httpx
import json
import base64
import time

BASE = "https://api.prismadata.io/v1"

class TokenManager:
    def __init__(self, username: str, password: str):
        self.username = username
        self.password = password
        self.token = None
        self.exp = 0

    def _obter_token(self):
        resp = httpx.post(
            f"{BASE}/auth/token",
            data={"username": self.username, "password": self.password},
        )
        resp.raise_for_status()
        self.token = resp.json()["access_token"]
        # Extrair exp do payload JWT (segunda parte, base64)
        payload = self.token.split(".")[1]
        payload += "=" * (-len(payload) % 4)  # padding
        claims = json.loads(base64.urlsafe_b64decode(payload))
        self.exp = claims["exp"]

    def get_headers(self) -> dict:
        if time.time() >= self.exp - 30:  # renova 30s antes
            self._obter_token()
        return {"Authorization": f"Bearer {self.token}"}

mgr = TokenManager("user@email.com", "senha")
resp = httpx.get(
    f"{BASE}/location/prison",
    params={"lat": -25.5, "lng": -54.5},
    headers=mgr.get_headers(),
)

O modo sandbox permite testar a integração com a API usando dados sintéticos. As respostas mantêm a mesma estrutura e tipos de dados da produção, mas com valores fictícios.

Sandbox é uma propriedade da conta do usuário, configurada pelo administrador no Portal Administrativo. Não é algo que o desenvolvedor ativa por requisição.

1. O administrador marca a conta como sandbox via Portal Administrativo
2. O token JWT emitido para essa conta inclui o claim sandbox
3. O API Gateway injeta automaticamente o header X-Sandbox em todas as requisições
4. Os serviços retornam dados sintéticos em vez de consultar as bases reais

Nenhuma ação é necessária no código de integração. Se a conta é sandbox, todas as respostas já serão sintéticas automaticamente.

• Retorna dados com tipos e estrutura idênticos à produção
• Valores são fictícios mas plausíveis
• Não consome quota nem rate limit
• Funciona em todos os endpoints de localização e roteamento

• Desenvolvimento e prototipação
• Testes de integração
• Pipelines de CI/CD
• Validação de parsing de resposta

Solicite ao administrador a ativação do modo sandbox na sua conta para começar a receber dados sintéticos.

O SDK Python detecta automaticamente quando a conta está em modo sandbox e exibe um aviso durante a inicialização:

[PrismaData] Atenção: conta em modo sandbox — respostas contêm dados sintéticos.

Use operações em lote quando precisar consultar múltiplos pontos ou endereços em uma única chamada. Isso reduz latência e simplifica a integração.

Envie um JSON onde as chaves são identificadores únicos (strings) e os valores são arrays [latitude, longitude]:

{
  "ponto_1": [-23.550520, -46.633308],
  "ponto_2": [-22.906847, -43.172897]
}

A resposta é um dicionário com as mesmas chaves enviadas na requisição, mapeando para os objetos de resposta do serviço:

{
  "ponto_1": {
    "prismadata__prison__nome_estabelecimento": "...",
    "prismadata__prison__distancia_borda_m": 1500.0
  },
  "ponto_2": {
    "prismadata__prison__nome_estabelecimento": "...",
    "prismadata__prison__distancia_borda_m": 3200.0
  }
}

Para rotas, cada item contém coordenadas de origem e destino:

{
  "rotas": [
    {
      "origem": {"lat": -19.9191, "lng": -43.9378},
      "destino": {"lat": -19.9498, "lng": -43.9477}
    }
  ]
}

Sem falha parcial: cada ponto é processado independentemente. Todos os pontos retornam resultado — pontos fora de cobertura recebem campos de detalhe null (veja seção Formato de Resposta).

Agregador sem serviços habilitados: se nenhum flag de serviço for informado via query parameter (slum, prison, border, etc.), a resposta contém objetos vazios {} para cada ponto.

A cobrança de chamadas batch é feita por número de itens no lote. Um batch com 10 pontos equivale a 10 chamadas individuais.

Python (httpx):

import httpx

coordenadas = {
    "ponto_1": [-23.550520, -46.633308],
    "ponto_2": [-22.906847, -43.172897],
}

resp = httpx.post(
    "https://api.prismadata.io/v1/location/batch",
    json=coordenadas,
    headers={"X-Apikey": "ak_xxxxxxxxxxxxxxxx"},
)
resultados = resp.json()

for chave, dados in resultados.items():
    print(f"{chave}: {dados}")

curl:

curl -X POST "https://api.prismadata.io/v1/location/batch" \
  -H "X-Apikey: ak_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"ponto_1": [-23.55, -46.63], "ponto_2": [-22.90, -43.17]}'

JavaScript (fetch):

const coordenadas = {
  ponto_1: [-23.550520, -46.633308],
  ponto_2: [-22.906847, -43.172897]
};

const resp = await fetch(
  "https://api.prismadata.io/v1/location/batch",
  {
    method: "POST",
    headers: {
      "X-Apikey": "ak_xxxxxxxxxxxxxxxx",
      "Content-Type": "application/json"
    },
    body: JSON.stringify(coordenadas)
  }
);
const resultados = await resp.json();
Object.entries(resultados).forEach(([chave, dados]) => {
  console.log(`${chave}:`, dados);
});

Requer Python >= 3.10.

pip install prismadata

Extras opcionais:

pip install prismadata[pandas]     # enriquecimento de DataFrames
pip install prismadata[sklearn]    # transformer scikit-learn
pip install prismadata[cache]      # cache local em disco
pip install prismadata[progress]   # barra de progresso (tqdm)
pip install prismadata[all]        # todos os extras

from prismadata import Client

client = Client(api_key="ak_xxxxxxxxxxxxxxxx")

# Consultar favela mais proxima
result = client.slum(lat=-23.55, lng=-46.63)
print(result)

# Geocodificar um endereco
geo = client.geocode(full_address="Av Paulista 1000, Sao Paulo")
print(geo)

O SDK aceita 3 formas de credencial (em ordem de prioridade):

1. API Key direta:

client = Client(api_key="ak_xxxxxxxxxxxxxxxx")

2. Usuario e senha:

client = Client(username="user@email.com", password="senha")

3. Variaveis de ambiente:

export PRISMADATA_APIKEY=ak_xxxxxxxxxxxxxxxx
# ou
export PRISMADATA_USERNAME=user@email.com
export PRISMADATA_PASSWORD=senha

client = Client()  # detecta automaticamente

A renovacao do token JWT e automatica — o SDK cuida internamente.

from prismadata import AsyncClient

async with await AsyncClient.create(api_key="ak_xxxxxxxxxxxxxxxx") as client:
    result = await client.slum(lat=-23.55, lng=-46.63)
    print(result)

    # Enriquecimento de DataFrames tambem funciona
    enriched = await client.enrich(df, services=["slum", "income_static"])

O AsyncClient usa factory pattern — note o await antes de AsyncClient.create(). Todos os metodos do Client possuem equivalente assincrono no AsyncClient.

Para consultas em volume, use os metodos *_batch:

points = {
    "p1": [-23.55, -46.63],
    "p2": [-22.90, -43.17],
    "p3": [-19.92, -43.94],
}

# Batch de favelas
result = client.slum_batch(points)

# Batch de presídios
result = client.prison_batch(points)

# Batch de renda estatica
result = client.personal_income_static_batch(points)

# Batch de renda PDF (distribuicao de probabilidade)
result = client.personal_income_pdf_batch(points)

# Batch de renda PDF com parametros demograficos
result = client.personal_income_pdf_batch_detailed({
    "p1": {"lat": -23.55, "lng": -46.63, "gender": "M", "age": 50},
    "p2": {"lat": -22.90, "lng": -43.17, "gender": "F", "age": 30, "is_responsible": True},
})

# Batch com multiplos servicos (agregador)
result = client.aggregate_batch(
    points,
    services=["slum", "prison", "infosc"],
)

O SDK divide automaticamente lotes grandes em chunks e reenvia com retry em caso de erro.

Geocodificacao em Lote

# Geocodificar enderecos em lote (max 512 por chunk)
addresses = {
    "p1": {"endereco_completo": "Av Paulista 1000, Sao Paulo, SP"},
    "p2": {"cep": "30130-165", "numero": "100", "logradouro": "Rua da Bahia"},
}
result = client.geocode_batch(addresses)

# Geocodificacao reversa em lote (max 1024 por chunk)
points = {"p1": [-23.55, -46.63], "p2": [-22.90, -43.17]}
result = client.reverse_geocode_batch(points)

# Geocodificacao + agregacao em lote
result = client.geocode_aggregate_batch(
    addresses,
    services=["slum", "infosc"],
)
# Cada resultado contem campos do geocoder + dos servicos solicitados

Com o extra pandas, enriqueca DataFrames diretamente:

import pandas as pd
from prismadata import Client

client = Client(api_key="ak_xxxxxxxxxxxxxxxx")

df = pd.DataFrame({
    "lat": [-23.55, -22.90, -19.92],
    "lng": [-46.63, -43.17, -43.94],
})

enriched = client.enrich(
    df,
    services=["slum", "prison", "income_static"],
)
print(enriched.columns.tolist())

Com o extra sklearn, use o transformer em pipelines de ML:

from sklearn.pipeline import Pipeline
from prismadata import Client

client = Client(api_key="ak_xxxxxxxxxxxxxxxx")

transformer = client.get_transformer(
    services=["slum", "income_static"],
    lat_col="latitude",
    lng_col="longitude",
)

pipe = Pipeline([
    ("prismadata", transformer),
    ("model", your_model),
])

from prismadata import Client
from prismadata.exceptions import (
    AuthenticationError,
    BatchError,
    RateLimitError,
    PrismaDataError,
)

try:
    client = Client(api_key="ak_xxxxxxxxxxxxxxxx")
    result = client.slum(lat=-23.55, lng=-46.63)
except AuthenticationError:
    print("Credenciais invalidas")
except RateLimitError:
    print("Rate limit excedido, aguarde e tente novamente")
except PrismaDataError as e:
    print(f"Erro da API: {e}")

Falhas Parciais em Batch

Quando um lote grande falha parcialmente, o SDK coleta os resultados dos chunks que deram certo e levanta BatchError com os dados parciais:

try:
    result = client.slum_batch(large_point_dict)
except BatchError as e:
    # Resultados dos chunks que deram certo
    for key, value in e.partial_results.items():
        process(key, value)

    # Chaves dos chunks que falharam (para retry manual)
    print(f"Falhou: {e.failed_keys}")

O SDK implementa retry automatico com backoff exponencial para erros transientes (429, 500, 502, 503, 504). Alem disso, respeita os headers Retry-After e X-RateLimit-Reset do servidor.

SDK oficial em R para a API de inteligencia geoespacial da PrismaData (https://api.prismadata.io/v1). Este guia cobre instalacao, autenticacao, consultas individuais e em lote, enriquecimento de data.frames, integracao com tidymodels e tratamento de erros.

1. Instalacao
2. Quick Start
3. Autenticacao
4. Operacoes em Lote
5. Enriquecimento de Data.Frames
6. Pipeline tidymodels
7. Tratamento de Erros
8. Falhas Parciais em Batch

Via CRAN

Quando disponivel no CRAN, basta executar:

install.packages("prismadata")

Via GitHub (versao de desenvolvimento)

Para instalar a versao mais recente diretamente do repositorio:

# Instale o pacote remotes caso ainda nao tenha
install.packages("remotes")

# Instale o prismadata a partir do GitHub
remotes::install_github("prismadata/prismadata-r")

Dependencias opcionais

O pacote possui dependencias opcionais que habilitam funcionalidades extras. Instale conforme a necessidade:

# Cache em disco (para evitar chamadas repetidas a API)
install.packages("cachem")

# Enriquecimento de tibbles e manipulacao com dplyr
install.packages(c("tibble", "dplyr"))

# Integracao com tidymodels (step_prismadata)
install.packages("recipes")

Exemplo minimo para comecar a usar o pacote: criar um cliente, consultar a proximidade de favela para um par de coordenadas e inspecionar o resultado.

library(prismadata)

# Cria o cliente com sua chave de API
client <- prismadata_client(api_key = "ak_xxxxxxxxxxxxxxxx")

# Consulta a favela mais proxima de um ponto em Sao Paulo
resultado <- client$slum(lat = -23.55, lng = -46.63)

# Inspeciona o retorno
str(resultado)
# $ prismadata__favela__nome        : chr "Paraisopolis"
# $ prismadata__favela__distancia_m : num 3420
# $ prismadata__favela__area_ha     : num 102.3
# ...

O objeto client expoe metodos para todos os servicos da API: geocodificacao, inteligencia de localizacao, roteamento, validacao de enderecos e consultas de credito.

# Geocodificacao
geo <- client$geocode(full_address = "Av Paulista 1000, Sao Paulo, SP")

# Geocodificacao reversa
endereco <- client$reverse_geocode(lat = -23.5632, lng = -46.6542)

# Proximidade de presidio
presidio <- client$prison(lat = -23.55, lng = -46.63)

# Proximidade de fronteira
fronteira <- client$border(lat = -23.55, lng = -46.63)

# Informacoes do setor censitario (IBGE)
setor <- client$infosc(lat = -23.55, lng = -46.63)

# Estimativa de renda estatica
renda <- client$income_static(lat = -23.55, lng = -46.63)

# Calculo de rota entre dois pontos
rota <- client$route(
  points = list(c(-23.55, -46.63), c(-22.90, -43.17)),
  profile = "car"
)

# Isocrona (area alcancavel em 10 minutos de carro)
iso <- client$isochrone(lat = -23.55, lng = -46.63, time_limit = 600, profile = "car")

O pacote suporta tres formas de autenticacao, avaliadas na seguinte ordem de prioridade:

Metodo 1 -- Chave de API (api_key)

A forma mais simples. Voce recebe a chave no painel da PrismaData.

client <- prismadata_client(api_key = "ak_xxxxxxxxxxxxxxxx")

Metodo 2 -- Usuario e senha (username / password)

Autentica via endpoint /auth/token, obtendo um JWT que e renovado automaticamente.

client <- prismadata_client(
  username = "usuario@empresa.com",
  password = "minha_senha_segura"
)

Metodo 3 -- Variaveis de ambiente

Quando nenhum argumento e passado, o pacote busca credenciais automaticamente nas variaveis de ambiente. Isso e ideal para ambientes de producao, CI/CD e containers.

# Opcao A: defina a variavel PRISMADATA_APIKEY
Sys.setenv(PRISMADATA_APIKEY = "ak_xxxxxxxxxxxxxxxx")

# Opcao B: defina PRISMADATA_USERNAME e PRISMADATA_PASSWORD
Sys.setenv(PRISMADATA_USERNAME = "usuario@empresa.com")
Sys.setenv(PRISMADATA_PASSWORD = "minha_senha_segura")

# O cliente detecta as credenciais automaticamente
client <- prismadata_client()

A ordem de resolucao e:

1. Argumento api_key explicito
2. Argumentos username + password explicitos
3. Variavel de ambiente PRISMADATA_APIKEY
4. Variaveis de ambiente PRISMADATA_USERNAME + PRISMADATA_PASSWORD

Se nenhuma credencial for encontrada, o pacote emite um erro do tipo prismadata_authentication_error com instrucoes de configuracao.

Opcoes adicionais do cliente

client <- prismadata_client(
  api_key = "ak_xxxxxxxxxxxxxxxx",
  timeout = 60,                # Timeout de requisicao em segundos (padrao: 30)
  cache = TRUE,                # Habilita cache em disco (requer pacote cachem)
  cache_ttl = 86400,           # Tempo de vida do cache em segundos (padrao: 24h)
  clean_columns = TRUE,        # Remove prefixo "prismadata__" dos nomes de colunas
  show_progress = TRUE,        # Exibe barra de progresso em operacoes batch
  app_name = "meu_app"        # Nome da aplicacao enviado no header X-App
)

Verificando a autenticacao

# Retorna informacoes do usuario autenticado
info <- client$me()
print(info)
# $username
# [1] "usuario@empresa.com"
# $roles
# [1] "admin" "full_reader"

Para consultar muitos pontos de uma vez, use os metodos *_batch(). O pacote faz o auto-chunking automaticamente: listas com mais de 1024 pontos sao divididas em blocos e enviadas sequencialmente, com barra de progresso.

slum_batch() -- Proximidade de favela em lote

# Cria uma lista nomeada de coordenadas (lat, lng)
pontos <- list(
  "sp_centro"  = c(-23.5505, -46.6333),
  "rj_centro"  = c(-22.9068, -43.1729),
  "bh_centro"  = c(-19.9191, -43.9386),
  "poa_centro" = c(-30.0346, -51.2177),
  "recife"     = c(-8.0476, -34.8770)
)

# Consulta em lote
resultados <- client$slum_batch(pontos)

# Cada resultado e acessado pela chave do ponto
resultados$sp_centro$prismadata__favela__distancia_m
# [1] 2145.7

resultados$rj_centro$prismadata__favela__nome
# [1] "Morro da Providencia"

aggregate_batch() -- Multiplos servicos em lote

Consulta varios servicos simultaneamente para cada ponto (favela, presidio, fronteira, setor censitario).

pontos <- list(
  "loc_1" = c(-23.55, -46.63),
  "loc_2" = c(-22.90, -43.17)
)

resultados <- client$aggregate_batch(
  points = pontos,
  services = c("slum", "prison", "infosc")
)

# O resultado de cada ponto contem campos de todos os servicos solicitados
resultados$loc_1$prismadata__favela__distancia_m
resultados$loc_1$prismadata__presidio__distancia_m
resultados$loc_1$prismadata__info_sc__cod_setor

route_batch() -- Rotas em lote

Calcula multiplas rotas de uma vez. O limite por chunk para roteamento e de 16 itens.

# Cada item deve conter um elemento "points" com a lista de coordenadas
itens_rota <- list(
  list(points = list(c(-23.55, -46.63), c(-23.56, -46.65))),
  list(points = list(c(-22.90, -43.17), c(-22.91, -43.20))),
  list(points = list(c(-19.92, -43.94), c(-19.93, -43.96)))
)

resultados <- client$route_batch(itens_rota, profile = "car")

# Estrutura do retorno
resultados$TOTAL       # Total de rotas solicitadas
resultados$SUCESSOS    # Quantidade de rotas calculadas com sucesso
resultados$FALHAS      # Quantidade de falhas
resultados$RESULTADOS  # Lista com os dados de cada rota

Geocodificacao em lote

# Geocodificar enderecos em lote (max 512 por chunk)
enderecos <- list(
  "p1" = list(endereco_completo = "Av Paulista 1000, Sao Paulo, SP"),
  "p2" = list(cep = "30130-165", numero = "100", logradouro = "Rua da Bahia")
)
resultados <- client$geocode_batch(enderecos)

# Geocodificacao reversa em lote (max 1024 por chunk)
pontos <- list("p1" = c(-23.55, -46.63), "p2" = c(-22.90, -43.17))
resultados <- client$reverse_geocode_batch(pontos)

# Geocodificacao + agregacao em lote
resultados <- client$geocode_aggregate_batch(
  enderecos,
  services = c("slum", "infosc")
)
# Cada resultado contem campos do geocoder + dos servicos solicitados
resultados$p1$prismadata__geocoder__latitude
resultados$p1$prismadata__slum__favela_distancia_m

Outros metodos batch disponiveis

# Proximidade de presidio em lote
client$prison_batch(pontos)

# Proximidade de fronteira em lote
client$border_batch(pontos)

# Setor censitario em lote
client$infosc_batch(pontos)

# Isocronas em lote
itens_iso <- list(
  list(lat = -23.55, lng = -46.63, time_limit = 600),
  list(lat = -22.90, lng = -43.17, time_limit = 300)
)
client$isochrone_batch(itens_iso, profile = "car", direction = "outgoing")

Nota sobre auto-chunking

• Servicos de localizacao (slum_batch, prison_batch, border_batch, infosc_batch, aggregate_batch): limite de 1024 pontos por chunk.
• Servicos de roteamento (route_batch, isochrone_batch): limite de 16 itens por chunk.

Quando a quantidade de pontos excede o limite, o pacote divide automaticamente em chunks, envia cada um separadamente e consolida os resultados. A barra de progresso e exibida quando ha mais de um chunk (desative com show_progress = FALSE no construtor do cliente).

O metodo client$enrich() recebe um data.frame com colunas de latitude e longitude e retorna o mesmo data.frame acrescido de colunas com dados geoespaciais da PrismaData.

# Data.frame de entrada com coordenadas
df <- data.frame(
  id  = c("loja_sp", "loja_rj", "loja_bh"),
  lat = c(-23.5505, -22.9068, -19.9191),
  lng = c(-46.6333, -43.1729, -43.9386)
)

# Enriquece com dados de favela, setor censitario e renda
enriquecido <- client$enrich(
  df,
  lat_col = "lat",
  lng_col = "lng",
  services = c("slum", "infosc", "income_static")
)

# O data.frame agora possui colunas adicionais
names(enriquecido)
# [1] "id"  "lat"  "lng"
# [4] "prismadata__favela__distancia_m"  "prismadata__favela__nome"
# [7] "prismadata__info_sc__cod_setor"   "prismadata__renda__mediana"
# ...

# Visualiza o resultado
head(enriquecido)

Usando com dplyr e tibbles

library(dplyr)

enriquecido <- client$enrich(df, services = c("slum", "prison")) |>
  as_tibble() |>
  filter(prismadata__favela__distancia_m < 5000) |>
  arrange(prismadata__favela__distancia_m)

Limpando nomes de colunas

Para remover o prefixo prismadata__ e simplificar os nomes, crie o cliente com clean_columns = TRUE:

client <- prismadata_client(
  api_key = "ak_xxxxxxxxxxxxxxxx",
  clean_columns = TRUE
)

enriquecido <- client$enrich(df, services = c("slum"))
names(enriquecido)
# [1] "id"  "lat"  "lng"  "favela_distancia_m"  "favela_nome"  ...

Voce tambem pode limpar nomes manualmente em qualquer momento:

# Limpa nomes de um vetor de caracteres
clean_columns(c("prismadata__favela__distancia_m", "prismadata__geocoder__latitude"))
# [1] "favela_distancia_m"  "geocoder_latitude"

# Limpa nomes de um data.frame
df_limpo <- clean_columns(enriquecido)

O pacote oferece o step step_prismadata() para integracao direta com o framework tidymodels/recipes. Ele permite adicionar features geoespaciais ao seu pipeline de machine learning de forma declarativa.

Exemplo completo

library(recipes)
library(prismadata)

# Suponha um dataset de treino com coordenadas e uma variavel alvo
dados_treino <- data.frame(
  lat    = c(-23.55, -22.90, -19.92, -30.03, -8.05),
  lng    = c(-46.63, -43.17, -43.94, -51.22, -34.88),
  valor  = c(1500, 2300, 1800, 1200, 900),
  target = c(1, 0, 1, 0, 1)
)

dados_teste <- data.frame(
  lat    = c(-23.56, -22.91),
  lng    = c(-46.64, -43.18),
  valor  = c(1600, 2100),
  target = c(1, 0)
)

# Define a receita com o step de enriquecimento PrismaData
receita <- recipe(target ~ ., data = dados_treino) |>
  step_prismadata(
    lat, lng,
    services = c("slum", "income_static"),
    api_key = "ak_xxxxxxxxxxxxxxxx"
  )

# Prepara a receita (faz as chamadas a API para os dados de treino)
receita_preparada <- prep(receita, training = dados_treino)

# Aplica a receita nos dados de teste (faz as chamadas para os dados de teste)
dados_enriquecidos <- bake(receita_preparada, new_data = dados_teste)

# O resultado e um tibble com as colunas originais + colunas de enriquecimento
print(dados_enriquecidos)

Combinando com outros steps

library(recipes)
library(prismadata)

receita <- recipe(target ~ ., data = dados_treino) |>
  step_prismadata(
    lat, lng,
    services = c("slum", "prison", "infosc"),
    api_key = "ak_xxxxxxxxxxxxxxxx",
    clean_columns = TRUE
  ) |>
  step_normalize(all_numeric_predictors()) |>
  step_dummy(all_nominal_predictors())

Notas sobre step_prismadata

• O step requer exatamente 2 colunas (latitude e longitude, nessa ordem).
• Durante o prep(), uma chamada e feita com a primeira linha dos dados de treino para descobrir os nomes das colunas de enriquecimento. Em seguida, o dataset completo e enriquecido durante o bake().
• O parametro skip = TRUE pode ser usado para pular o step durante o bake() (util para debug).
• Autenticacao via username/password tambem e suportada no step.

O pacote define uma hierarquia de condicoes (errors) customizadas, todas herdando de prismadata_error. Isso permite capturar erros especificos com tryCatch.

Hierarquia de erros

Exemplo: capturando erros especificos

tryCatch(

{
    resultado <- client$slum(lat = -23.55, lng = -46.63)
    print(resultado)
  },

  # Erro de autenticacao (credencial invalida ou expirada)
  prismadata_authentication_error = function(e) {
    message("Erro de autenticacao: ", conditionMessage(e))
    message("Status HTTP: ", e$status_code)
  },

  # Limite de requisicoes por segundo excedido
  prismadata_rate_limit_error = function(e) {
    message("Rate limit excedido. Aguarde antes de tentar novamente.")
    message("Status HTTP: ", e$status_code)
  },

  # Cota de uso esgotada (creditos insuficientes)
  prismadata_quota_error = function(e) {
    message("Cota esgotada: ", conditionMessage(e))
  },

  # Parametros de entrada invalidos
  prismadata_validation_error = function(e) {
    message("Dados de entrada invalidos: ", conditionMessage(e))
  },

  # Qualquer outro erro da API PrismaData
  prismadata_error = function(e) {
    message("Erro da API: ", conditionMessage(e))
    message("Status HTTP: ", e$status_code)
    message("Corpo da resposta: ", paste(e$body, collapse = ", "))
  }
)

Exemplo: retry manual apos rate limit

consulta_com_retry <- function(client, lat, lng, tentativas = 3) {
  for (i in seq_len(tentativas)) {
    resultado <- tryCatch(
      client$slum(lat = lat, lng = lng),

      prismadata_rate_limit_error = function(e) {
        if (i < tentativas) {
          tempo_espera <- 2^i
          message(sprintf("Rate limit atingido. Tentativa %d/%d. Aguardando %ds...",
                          i, tentativas, tempo_espera))
          Sys.sleep(tempo_espera)
          NULL
        } else {
          stop("Rate limit excedido apos ", tentativas, " tentativas.")
        }
      }
    )

    if (!is.null(resultado)) return(resultado)
  }
}

resultado <- consulta_com_retry(client, lat = -23.55, lng = -46.63)

Nota sobre retries automaticos

O pacote ja implementa retry automatico com backoff exponencial para os seguintes status HTTP: 429 (rate limit), 500, 502, 503 e 504 (erros de servidor). Sao feitas ate 3 tentativas antes de emitir o erro. O header Retry-After e respeitado quando presente na resposta.

Operacoes em lote podem falhar parcialmente: parte dos chunks retorna com sucesso enquanto outros falham (por timeout, erro de servidor etc.). Nesses casos, o pacote emite um erro do tipo prismadata_batch_error que carrega tanto os resultados parciais quanto as chaves que falharam.

Estrutura do prismadata_batch_error

O erro prismadata_batch_error possui dois campos extras acessiveis no handler:

• e$partial_results: lista nomeada com os resultados dos chunks que tiveram sucesso.
• e$failed_keys: vetor de caracteres com as chaves (IDs dos pontos) que falharam.

Exemplo: recuperando resultados parciais

# Lista grande de pontos
pontos <- list(
  "p001" = c(-23.55, -46.63),
  "p002" = c(-22.90, -43.17),
  "p003" = c(-19.92, -43.94),
  "p004" = c(-30.03, -51.22),
  "p005" = c(-8.05,  -34.88)
  # ... imagine centenas de pontos
)

resultados <- tryCatch(
  client$slum_batch(pontos),

  # Captura falha parcial
  prismadata_batch_error = function(e) {
    message(sprintf(
      "Falha parcial: %d resultados obtidos, %d chaves falharam",
      length(e$partial_results),
      length(e$failed_keys)
    ))

    # Exibe quais chaves falharam
    message("Chaves com falha: ", paste(e$failed_keys, collapse = ", "))

    # Retorna os resultados parciais para nao perder o que ja foi processado
    e$partial_results
  },

  # Outros erros da API
  prismadata_error = function(e) {
    message("Erro geral da API: ", conditionMessage(e))
    NULL
  }
)

# Processa os resultados parciais (se houver)
if (!is.null(resultados)) {
  message(sprintf("Processando %d resultados parciais...", length(resultados)))

  for (chave in names(resultados)) {
    distancia <- resultados[[chave]]$prismadata__favela__distancia_m
    message(sprintf("  %s: %.1f metros da favela mais proxima", chave, distancia))
  }
}

Exemplo: retry das chaves que falharam

consulta_batch_resiliente <- function(client, pontos, max_tentativas = 3) {
  resultados_finais <- list()
  pendentes <- pontos

  for (tentativa in seq_len(max_tentativas)) {
    if (length(pendentes) == 0) break

    resultado <- tryCatch(
      client$slum_batch(pendentes),

      prismadata_batch_error = function(e) {
        # Acumula resultados parciais
        resultados_finais <<- c(resultados_finais, e$partial_results)

        # Filtra apenas os pontos que falharam para retry
        chaves_falha <- e$failed_keys
        message(sprintf(
          "Tentativa %d: %d sucessos, %d falhas. Retentando falhas...",
          tentativa,
          length(e$partial_results),
          length(chaves_falha)
        ))
        pendentes <<- pontos[chaves_falha]
        NULL
      }
    )

    if (!is.null(resultado)) {
      # Tudo funcionou nesta tentativa
      resultados_finais <- c(resultados_finais, resultado)
      pendentes <- list()
    }
  }

  if (length(pendentes) > 0) {
    warning(sprintf(
      "%d pontos nao puderam ser processados apos %d tentativas: %s",
      length(pendentes),
      max_tentativas,
      paste(names(pendentes), collapse = ", ")
    ))
  }

  resultados_finais
}

# Uso
todos_resultados <- consulta_batch_resiliente(client, pontos)

Exemplo: falha parcial em route_batch

Para operacoes de roteamento em lote, a estrutura do partial_results e diferente -- segue o formato com TOTAL, SUCESSOS, FALHAS e RESULTADOS:

itens_rota <- list(
  list(points = list(c(-23.55, -46.63), c(-23.56, -46.65))),
  list(points = list(c(-22.90, -43.17), c(-22.91, -43.20)))
)

resultado <- tryCatch(
  client$route_batch(itens_rota, profile = "car"),

  prismadata_batch_error = function(e) {
    parcial <- e$partial_results

    message(sprintf(
      "Rotas: %d total, %d sucessos, %d falhas",
      parcial$TOTAL,
      parcial$SUCESSOS,
      parcial$FALHAS
    ))

    message("Indices com falha: ", paste(e$failed_keys, collapse = ", "))

    # Retorna os resultados parciais
    parcial
  }
)

Para mais informacoes, consulte a documentacao da API em https://docs.prismadata.io ou abra uma issue no repositorio GitHub.

O servico de autenticacao PrismaData gerencia credenciais, tokens JWT e API Keys para acesso as APIs de dados PrismaData.

Existem duas formas de autenticar nas APIs PrismaData. Recomendamos o uso de API Key por sua simplicidade e menor latencia.

1. API Key (recomendado)

A API Key e a forma mais simples de autenticacao. Basta envia-la no header X-Apikey em qualquer request ao gateway:

curl https://api.prismadata.io/v1/location/prison?lat=-25.5&lng=-54.5 \
  -H "X-Apikey: ak_xxxxxxxxxxxxxxxx"

Vantagens da API Key:

• Nao expira (a menos que seja revogada pelo administrador)
• O gateway gerencia o token JWT automaticamente (gera, cacheia e renova)
• Nenhum controle de validade necessario pelo cliente
• Menor latencia: o token e cacheado no gateway e reutilizado entre requests

2. Login com usuario e senha

Para obter um token JWT diretamente, envie suas credenciais via POST /token:

curl -X POST https://api.prismadata.io/v1/auth/token \
  -d "username=seu_usuario&password=sua_senha"

Em seguida, use o token retornado no header Authorization:

curl https://api.prismadata.io/v1/location/prison?lat=-25.5&lng=-54.5 \
  -H "Authorization: Bearer eyJ..."

Importante sobre tokens JWT:

• O token possui um tempo de expiracao (claim exp), tipicamente 15 minutos
• O cliente deve controlar a validade do token e renova-lo antes da expiracao
• Apos expirado, o token e rejeitado pelo gateway e um novo deve ser obtido via POST /token

O endpoint /token aceita dois modos de autenticacao via application/x-www-form-urlencoded:

Com API Key (campo api_key):

curl -X POST https://api.prismadata.io/v1/auth/token \
  -d "api_key=ak_xxxxxxxxxxxxxxxx"

Com usuario e senha (campos username e password):

curl -X POST https://api.prismadata.io/v1/auth/token \
  -d "username=seu_usuario&password=sua_senha"

O token JWT contém os seguintes claims:

Headers do JWT: kid (Key ID), iss ("PrismaDataAuth"), alg (RS256).

Os endpoints de autenticacao possuem rate limiting de 5 requisicoes por minuto por IP.

Credenciais de acesso sao fornecidas pela equipe PrismaData. Para solicitar acesso, entre em contato pelo portal.

API de Identificacao de Pais por IP/Coordenada para Compliance PLD/FT.

Identifica o pais de origem de um acesso a partir de endereco IP ou coordenada geografica, retornando classificacao de risco, status em listas de sancoes internacionais (GAFI, OFAC, UE), paraisos fiscais (RFB, UE), deteccao de VPN/Proxy/TOR/Datacenter/Satelite, ASN (Autonomous System Number) e indice de confianca da geolocalizacao.

Cada resposta inclui assinatura digital Ed25519, funcionando como laudo tecnico verificavel por terceiros (auditores, BACEN, PF).

• Monitoramento de pais de acesso para compliance com Circular BACEN 3.978/2020
• Deteccao de acessos via VPN, TOR, proxy ou satelite em plataformas financeiras
• Identificacao de ASN e organizacao responsavel pelo IP
• Avaliacao de confianca da geolocalizacao (reduzida para conexoes via satelite)
• Enriquecimento de dados para analise de risco PLD/FT
• Geracao de evidencias auditaveis para o BACEN

Verificacao publica de assinaturas digitais Ed25519.

Laudos e relatorios de consultas de compliance.

O dado de fronteiras indica se um ponto está localizado em uma faixa de fronteira e traz algumas informações desta fronteira, como proximidade da fronteira, qual é o país mais próximo e se a mancha urbana do município que o ponto se encontra está próximo da faixa de fronteira.

A faixa de fronteira, segundo o IBGE, é uma faixa de até 150 km de largura ao longo das fronteiras terrestres do Brasil, considerada importante para a defesa nacional. Essa área abrange 16,7% do território brasileiro.

Maiores informações podem ser encontradas na documentação de produto. Testes manuais com o fim de se compreender melhor o dado podem ser feitos aqui.

Existem 3 entidades que compõem o dado de favelas: Favelas, complexos e ilhas.

As favelas propriamente ditas que são regiões que são classificadas desta forma pelo IBGE em função das características construtivas do domicílios contidos nesta região. Note que favelas, em conjunto, quando se encontram próximas, podem formar complexos de favelas.

Além disso, é possível a existência de regiões dentro de favelas ou complexos nas quais os aspectos construtivos dos domicílios não se enquadram dentro do conceito do IBGE para que um domicílio seja considerado de favela, contudo são regiões que estão cercadas por regiões de favela. Neste caso, denominou-se esta região de ilha, já que ela se encontra rodeada por favela apesar dela própria não ser uma região de favela. Frequentemente as ilhas, são regiões que contêm domicilios de conjuntos habitacionais.

Caso o ponto se encontre distante mais de 5000 metros de uma entidade valores vazios são retornados.

Maiores informações podem ser encontradas na documentação de produto. Testes manuais com o fim de se compreender melhor o dado podem ser feitos aqui.