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

Consulta de dados cadastrais de pessoas juridicas (Receita Federal + geo). O SDK valida o CNPJ localmente (mod-11 alfanumerico, aceita mascara) antes de fazer a request.

# Lookup individual - shape flat (49 chaves escalares)
r = client.cnpj("82.554.437/0001-31")
print(r["prismadata__pessoa_juridica__razao_social"])

# Lookup raw - shape F1 com socios/CNAEs como listas
r_raw = client.cnpj_raw("82554437000131")
for socio in r_raw["prismadata__pessoa_juridica__socios"]:
    print(socio["prismadata__pessoa_juridica__nome_ou_razao_social"])

# Batch flat (max 1024/chamada) - retorna dict indexado por CNPJ
batch = client.cnpj_batch(["82554437000131", "60701190076771"])
if batch["82554437000131"] is None:
    print("CNPJ nao encontrado")

# Batch raw (max 256/chamada - payload maior)
batch_raw = client.cnpj_raw_batch(["82554437000131"])

# Metadata do dataset
meta = client.cnpj_metadata()
print(meta["prismadata__pessoa_juridica__total_cnpjs_carregados"])

CNPJ enriquecido com geo

O agregador anexa dados dos pilares geo (favela, presidio, fronteira, renda, aglomeracao comercial, infosc, tipologia) numa unica chamada. Quando o CNPJ nao tem lat/lng, as flags geo sao silenciosamente puladas — so vem o bloco prismadata__pessoa_juridica__* com qualidade_geocodificacao_classificacao="FALHA".

r = client.cnpj_enriched(
    "82554437000131",
    slum=True, border=True, tipologia=True,
)
if "prismadata__slum__nome" in r:
    print("Favela mais proxima:", r["prismadata__slum__nome"])
else:
    print("Sem geo. Qualidade:",
          r.get("prismadata__pessoa_juridica__qualidade_geocodificacao_classificacao"))

# Batch enriquecido (max 256/chamada)
batch = client.cnpj_batch_enriched(
    ["82554437000131", "60701190076771"],
    slum=True, tipologia=True,
)

Tipologia retorna a finalidade (residencial, comercial, misto), especie cadastral e tipo de moradia do endereco CNEFE mais proximo. Base: Censo CNEFE-IBGE 2022, cobertura aproximada de 65% do territorio brasileiro.

# Por coordenada
result = client.tipologia(lat=-23.55, lng=-46.63)
# result["prismadata__tipologia__finalidade"] -> "RESIDENCIAL" / "NAO_RESIDENCIAL" / ...
# result["prismadata__tipologia__cobertura"] -> bool

# cobertura=False nao e erro - decide o que fazer no cliente
if not result["prismadata__tipologia__cobertura"]:
    motivo = result.get("prismadata__tipologia__motivo_sem_cobertura")
    # FORA_DE_AREA_BRASIL | CNEFE_NAO_CADASTRADO | DISTANCIA_EXCESSIVA

# Por endereco textual ou estruturado
result = client.tipologia_by_address(full_address="Av Paulista 1000, Sao Paulo, SP")
# ou com campos individuais (tem prioridade)
result = client.tipologia_by_address(
    zipcode="01310-100", number=1000, city="Sao Paulo", state="SP",
)
# result["prismadata__tipologia__match_method"] indica match exato ou aproximado

# Metadata do dataset (versao, cobertura)
meta = client.tipologia_metadata()
print(meta["prismadata__tipologia__versao_dados"])

# Batch por coordenada (servidor caps a 1024/chunk - SDK chunka automaticamente)
result = client.tipologia_batch({
    "p1": [-23.55, -46.63],
    "p2": [-22.90, -43.17],
})

# Batch por endereco (servidor caps a 512/chunk)
result = client.tipologia_by_address_batch({
    "a1": {"endereco_completo": "Av Paulista 1000, Sao Paulo, SP"},
    "a2": {"cep": "30130-165", "numero": "100"},
})

Tipologia tambem esta disponivel via aggregator (consulte multiplos produtos numa unica chamada):

result = client.aggregate(
    -23.55, -46.63,
    services=["tipologia", "slum", "income_static"],
)
# ou em batch
result = client.aggregate_batch(
    {"p1": [-23.55, -46.63], "p2": [-22.90, -43.17]},
    services=["tipologia", "income_static"],
)

Aviso sobre confianca: em enderecos multi-unidade (shoppings, condominios, predios comerciais), o servidor retorna indicador_estabelecimento=MULTIPLO_* e confianca pode ser MEDIA ou BAIXA. Esses campos indicam que o resultado e uma amostra, nao a unidade especifica. Veja documentacao completa em https://docs.prismadata.io/tipologia.

Aglomeracoes comerciais sao poligonais continuas de tecido comercial denso (~11k regioes no Brasil), com atributos como qtd de PDVs, score, porte, vocacao, faixa de renda e trechos de rua ranqueados.

# Aglomeracao + trecho de rua mais proximo de um ponto
result = client.commercial_cluster(lat=-23.5613, lng=-46.6558)

# Top 3 aglomeracoes proximas (resposta indexada por 1_, 2_, 3_)
result = client.commercial_cluster(
    lat=-23.5613, lng=-46.6558, top_n=3, radius_km=10.0,
)

# Filtrar por vocacao (aceita string ou lista)
result = client.commercial_cluster(
    lat=-23.5613, lng=-46.6558,
    vocation=["Moda", "Alimentacao"],
    min_size="Grande",
)

# Enriquecimento de carteira de PDVs (ate 1024 pontos por request)
carteira = {
    "pdv_1": [-23.5613, -46.6558],
    "pdv_2": [-22.9068, -43.1729],
}
result = client.commercial_cluster_batch(carteira, top_n=1)
# result = {"pdv_1": {...campos flat...}, "pdv_2": {...}}

# Drill-down: detalhes de uma aglomeracao + todos os trechos
detail = client.commercial_cluster_detail("5ebd0eb4f6b4")

# Geometria (opcional, premium): GeoJSON dict ou WKT string
# Requer role `admin` ou `viewer:commercial_cluster` no JWT - fale com vendas.
r = client.commercial_cluster(-23.5613, -46.6558, include_geometry=True)
geom = r["prismadata__commercial_cluster__geometria"]
# geom e dict: {"type": "Polygon", "coordinates": [[[...]]]}

r_wkt = client.commercial_cluster(-23.5613, -46.6558, include_geometry=True, wkt=True)
# r_wkt[...geometria] e str: "POLYGON((...))"

# Sem a role: levanta GeometryNotAuthorizedError (HTTP 403).
# Batch nao suporta geometria - usar single point ou detail.
# Tentar incluir_geometria em batch levanta GeometryBatchNotSupportedError.

# Granularidade fina: trecho de rua mais proximo (raio em metros)
street = client.commercial_cluster_street(-23.5613, -46.6558, radius_m=200.0)

# Busca por filtros (sem ponto geografico) - lista paginada
results = client.commercial_cluster_search(
    filters={
        "state": ["SP", "RJ"],
        "vocation": ["Moda"],
        "size": ["Grande"],
        "income_range": ["Premium", "Luxo"],
        "min_pdv_count": 500,
        "bbox": {"min_lat": -24, "min_lng": -47, "max_lat": -23, "max_lng": -46},
    },
    limit=50,
)

# Ranking top-N por criterio e escopo
top_sp = client.commercial_cluster_ranking(
    criterion="score", scope="state", state="SP", top_n=20,
)

Para combinar commercial_cluster com outros produtos numa unica chamada, use o aggregator (caminho preferido para enriquecimento de carteira):

# Por ponto
result = client.aggregate(
    -23.5613, -46.6558,
    services=["commercial_cluster", "slum", "prison"],
    commercial_cluster_top_n=3,
    commercial_cluster_raio_km=10.0,
)

# Por endereco textual (geocoda + enriquece)
result = client.geocode_aggregate(
    full_address="Av Paulista 1000, Sao Paulo, SP",
    services=["commercial_cluster", "slum"],
)

# Batch
result = client.aggregate_batch(
    carteira,
    services=["commercial_cluster", "border"],
    commercial_cluster_top_n=1,
)

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.

Requer Node.js >= 18.

npm install prismadata

O pacote e publicado em CJS + ESM com tipos TypeScript embutidos — funciona em projetos JavaScript ou TypeScript sem dependencias extras.

import { PrismaDataClient } from "prismadata";

const client = new PrismaDataClient({ apiKey: "ak_xxxxxxxxxxxxxxxx" });

// Consultar favela mais proxima
const result = await client.slum(-23.55, -46.63);
console.log(result);

// Geocodificar um endereco
const geo = await client.geocode({ fullAddress: "Av Paulista 1000, Sao Paulo" });
console.log(geo);

Todos os metodos sao assincronos (Promise). O SDK nao expoe variante sincrona — use await ou .then().

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

1. API Key direta:

const client = new PrismaDataClient({ apiKey: "ak_xxxxxxxxxxxxxxxx" });

2. Usuario e senha:

const client = new PrismaDataClient({
  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

const client = new PrismaDataClient(); // detecta automaticamente

A renovacao do token JWT e automatica — o SDK cuida internamente. A autenticacao e iniciada de forma "eager" no construtor (concluida antes do primeiro request).

const client = new PrismaDataClient({
  apiKey: "ak_xxxxxxxxxxxxxxxx",
  timeout: 30,            // Timeout por request em segundos (default: 30)
  cache: true,            // Cache em memoria (default: false)
  cacheTtl: 86400,        // TTL do cache em segundos (default: 86400)
  cleanColumns: false,    // Remove prefixo prismadata__ das respostas (default: false)
  appName: "my-app",      // Enviado como header X-App em cada request
});

O helper cleanColumns tambem e exposto como funcao standalone:

import { cleanColumns } from "prismadata";

const cleaned = cleanColumns(result);
// "prismadata__favela__distancia_m" -> "favela_distancia_m"

Para consultas em volume, use os metodos *Batch:

const points = {
  p1: [-23.55, -46.63] as [number, number],
  p2: [-22.90, -43.17] as [number, number],
  p3: [-19.92, -43.94] as [number, number],
};

const slums = await client.slumBatch(points);
const prisons = await client.prisonBatch(points);
const borders = await client.borderBatch(points);
const sectors = await client.infoscBatch(points);

// Renda estatica em lote (percentil e faixa salarial)
const incomeStatic = await client.incomeStaticBatch(points);

// Renda PDF em lote (distribuicao de probabilidade)
const incomePdf = await client.incomePdfBatch(points);

// Renda PDF com parametros demograficos por ponto
const incomePdfDetailed = await client.incomePdfBatchDetailed({
  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 },
});

// Multiplos servicos numa unica chamada (agregador)
const aggregated = await client.aggregateBatch(points, {
  services: ["slum", "prison", "infosc"],
});

O SDK divide automaticamente lotes grandes em chunks (1024 por chunk em endpoints de localizacao, 16 em endpoints de roteamento) e prossegue com os chunks restantes em caso de falha parcial.

Geocodificacao em Lote

// Geocodificar enderecos em lote
const addresses = {
  p1: { endereco_completo: "Av Paulista 1000, Sao Paulo, SP" },
  p2: { cep: "30130-165", numero: "100", logradouro: "Rua da Bahia" },
};
const geocoded = await client.geocodeBatch(addresses);

// Geocodificacao reversa em lote
const points = {
  p1: [-23.55, -46.63] as [number, number],
  p2: [-22.90, -43.17] as [number, number],
};
const reversed = await client.reverseGeocodeBatch(points);

// Geocodificacao + agregador em lote
const enriched = await client.geocodeAggregateBatch(addresses, {
  services: ["slum", "infosc"],
});

Progresso em Lote

Todos os metodos *Batch aceitam um callback opcional onProgress:

await client.slumBatch(points, (completed, total) => {
  console.log(`${completed}/${total}`);
});

Aglomeracoes comerciais sao poligonais continuas de tecido comercial denso (~11k regioes no Brasil), com atributos como qtd de PDVs, score, porte, vocacao, faixa de renda e trechos de rua ranqueados.

// Aglomeracao + trecho de rua mais proximo de um ponto
const result = await client.commercialCluster(-23.5613, -46.6558);

// Top 3 aglomeracoes proximas (resposta indexada por 1_, 2_, 3_)
const top3 = await client.commercialCluster(-23.5613, -46.6558, {
  topN: 3,
  radiusKm: 10.0,
});

// Filtrar por vocacao (aceita string ou array) e porte minimo
const filtered = await client.commercialCluster(-23.5613, -46.6558, {
  vocation: ["Moda", "Alimentacao"],
  minSize: "Grande",
});

// Enriquecimento de carteira de PDVs (ate 1024 pontos por request)
const carteira = {
  pdv_1: [-23.5613, -46.6558] as [number, number],
  pdv_2: [-22.9068, -43.1729] as [number, number],
};
const batchResult = await client.commercialClusterBatch(carteira);
// batchResult = { pdv_1: { ...campos flat... }, pdv_2: { ... } }

// Drill-down: detalhes de uma aglomeracao + todos os trechos
const detail = await client.commercialClusterDetail("5ebd0eb4f6b4");

// Geometria (opcional, premium): GeoJSON object ou WKT string.
// Requer role `admin` ou `viewer:commercial_cluster` no JWT — fale com vendas.
const geojson = await client.commercialCluster(-23.5613, -46.6558, {
  includeGeometry: true,
});
const geom = geojson.prismadata__commercial_cluster__geometria;
// geom e objeto: { type: "Polygon", coordinates: [[[...]]] }

const wkt = await client.commercialCluster(-23.5613, -46.6558, {
  includeGeometry: true,
  wkt: true,
});
// wkt.prismadata__commercial_cluster__geometria e string: "POLYGON((...))"

// Sem a role: lanca GeometriaNaoAutorizadaError (HTTP 403).
// Batch nao suporta geometria — use single point ou detail.
// Forcar incluir_geometria em batch lanca GeometriaBatchNaoSuportadoError.

// Granularidade fina: trecho de rua mais proximo (raio em metros)
const street = await client.commercialClusterStreet(-23.5613, -46.6558, {
  radiusM: 200,
});

// Busca por filtros (sem ponto geografico) — lista paginada
const search = await client.commercialClusterSearch(
  {
    state: ["SP", "RJ"],
    vocation: ["Moda"],
    size: ["Grande"],
    income_range: ["Premium", "Luxo"],
    min_pdv_count: 500,
    bbox: { min_lat: -24, min_lng: -47, max_lat: -23, max_lng: -46 },
  },
  { limit: 50 },
);

// Ranking top-N por criterio e escopo
const topSp = await client.commercialClusterRanking({
  criterio: "score",
  escopo: "uf",
  uf: "SP",
  topN: 20,
});

Para combinar commercial_cluster com outros produtos numa unica chamada, use o aggregator (caminho preferido para enriquecimento de carteira):

// Por ponto
const byPoint = await client.aggregate(-23.5613, -46.6558, {
  services: ["commercial_cluster", "slum", "prison"],
  commercial_cluster_top_n: 3,
  commercial_cluster_raio_km: 10.0,
});

// Por endereco textual (geocoda + enriquece)
const byAddress = await client.geocodeAggregate({
  fullAddress: "Av Paulista 1000, Sao Paulo, SP",
  services: ["commercial_cluster", "slum"],
});

// Batch
const batchAgg = await client.aggregateBatch(carteira, {
  services: ["commercial_cluster", "border"],
  commercial_cluster_top_n: 1,
});

O modo sandbox e detectado automaticamente a partir do claim sandbox no JWT — nao ha flag explicita no cliente nem header X-Sandbox a passar. Tokens emitidos como sandbox retornam dados sinteticos em todos os endpoints, sem consumir quota real. Quando o token e sandbox, o SDK emite um console.warn no startup avisando o usuario.

Todos os erros estendem PrismaDataError, que carrega statusCode, body e headers (quando disponiveis).

import {
  PrismaDataClient,
  AuthenticationError,
  BatchError,
  GeometriaBatchNaoSuportadoError,
  GeometriaNaoAutorizadaError,
  PrismaDataError,
  QuotaExhaustedError,
  RateLimitError,
} from "prismadata";

try {
  const client = new PrismaDataClient({ apiKey: "ak_xxxxxxxxxxxxxxxx" });
  const result = await client.slum(-23.55, -46.63);
} catch (error) {
  if (error instanceof QuotaExhaustedError) {
    console.log("Quota mensal esgotada — nao sera feito retry");
  } else if (error instanceof RateLimitError) {
    console.log("Rate limit excedido apos retries — aguarde e tente novamente");
  } else if (error instanceof GeometriaNaoAutorizadaError) {
    console.log("Sem a role viewer:commercial_cluster — fale com vendas");
  } else if (error instanceof AuthenticationError) {
    console.log("Credenciais invalidas");
  } else if (error instanceof PrismaDataError) {
    console.log(`Erro da API (${error.statusCode}): ${error.message}`);
  }
}

Falhas Parciais em Batch

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

try {
  const result = await client.slumBatch(largePointDict);
} catch (error) {
  if (error instanceof BatchError) {
    // Resultados dos chunks que deram certo
    for (const [key, value] of Object.entries(error.partialResults)) {
      process(key, value);
    }
    // Chaves dos chunks que falharam (para retry manual)
    console.log(`Falhou: ${error.failedKeys.join(", ")}`);
  }
}

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. Quota esgotada (X-Quota-Remaining: 0) nao e re-tentada — o erro QuotaExhaustedError e lancado imediatamente.

Quota

Apos qualquer request bem-sucedido, client.quotaInfo expoe o estado mais recente da quota (a partir dos headers X-Quota-*) ou null quando o tenant nao possui politica de quota:

await client.slum(-23.55, -46.63);
console.log(client.quotaInfo);
// { limit: 100000, used: 1234, remaining: 98766, period: "month", reset: 1717200000 }

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