Você precisa de risco de criminalidade por CEP esta semana, não de uma reformulação de GIS. Ao final deste guia, você fará uma consulta a um endpoint, passará um CEP e obterá uma nota geral de criminalidade, além de uma divisão das taxas de criminalidade violenta, patrimonial e outras que você pode inserir diretamente em seu produto.
O que você obtém da API de Dados de Criminalidade por CEP
A API de Dados de Criminalidade por CEP retorna um objeto JSON para um determinado CEP dos EUA com:
- Nota Geral de Criminalidade, além de notas separadas para Criminalidade Violenta, Patrimonial e Outras.
- Taxas de criminalidade por categoria (por exemplo, Agressão, Roubo, Furto, Furto de Veículo, etc.).
- Totais e pontuações por categoria.
- CEPs próximos com suas notas.
- CEPs com população semelhante e suas notas.
Casos de uso comuns incluem sobreposições de busca de propriedades, ferramentas de relocação, filtros de risco para serviços de entrega e painéis de segurança internos. Você passa um CEP e obtém dados estruturados e consistentes que pode renderizar imediatamente.
Começando no Zyla API Hub
O Zyla API Hub oferece uma conta, uma chave de API e um modelo de assinatura + cota que funciona em mais de 10.000 APIs públicas. Para usar esta API:
- Abra a página da API em Zyla API Hub.
- Na página de listagem, clique em Inscrever-se ou Começar Teste Gratuito (quando disponível) para obter sua chave.
- Chame o endpoint com Authorization: Bearer YOUR_API_KEY.
Você pode iniciar um teste de 7 dias diretamente da listagem: Iniciar teste de 7 dias na API de Dados de Criminalidade por CEP. Verifique a página da API para opções de acesso e preços atuais.
Endpoint que você usará
Esta API expõe um único endpoint amigável para desenvolvedores.
- Nome: Obter Taxas de Criminalidade por CEP
- Método: GET
- URL: https://zylalabs.com/api/824/crime-data-by-zipcode-api/583/get-crime-rates-by-zip
- Parâmetro de consulta obrigatório: zip (número). Exemplo: 01370
- Auth: Authorization: Bearer YOUR_API_KEY
Teste rápido com curl
Copie/cole e substitua YOUR_API_KEY pela sua chave:
curl -s -X GET "https://zylalabs.com/api/824/crime-data-by-zipcode-api/583/get-crime-rates-by-zip?zip=01370" \
-H "Authorization: Bearer YOUR_API_KEY"Exemplo de resposta oficial
{"Overall":{"Zipcode":"01370","Overall Crime Grade":"B","Violent Crime Grade":"C-","Property Crime Grade":"B","Other Crime Grade":"B"},"Crime BreakDown":[{"Violent Crime Rates":{"Assault":"2.759","Robbery":"0.4627","Rape":"0.5506","Murder":"0.0218"},"0":{"Total Violent Crime":"3.795","Total Violent Crime Score":"(C-)"}},{"Property Crime Rates":{"Theft":"8.498","Vehicle Theft":"0.6988","Burglary":"1.563","Arson":"0.0619"},"0":{"Total Property Crime":"10.82","Total Property Crime Score":"(B)"}},{"Other Crime Rates":{"Kidnapping":"0.1303","Drug Crimes":"1.553","Vandalism":"3.749","Identity Theft":"0.4203","Animal Cruelty":"0.0490"},"0":{"Total Other Rate":"5.902","Total Other Score":"(B)"}}],"Crime Rates Nearby":[{"Nearby Zip":"01338, MA","Overall Crime Grade":"B-","Violent Crime Grade":"D","Property Crime Grade":"B-"},{"Nearby Zip":"01340, MA","Overall Crime Grade":"A-","Violent Crime Grade":"A-","Property Crime Grade":"B"},{"Nearby Zip":"01341, MA","Overall Crime Grade":"A","Violent Crime Grade":"C-","Property Crime Grade":"A"},{"Nearby Zip":"01301, MA","Overall Crime Grade":"C+","Violent Crime Grade":"C-","Property Crime Grade":"C"},{"Nearby Zip":"01330, MA","Overall Crime Grade":"A","Violent Crime Grade":"A-","Property Crime Grade":"A"},{"Nearby Zip":"01346, MA","Overall Crime Grade":"A","Violent Crime Grade":"C","Property Crime Grade":"A"},{"Nearby Zip":"01339, MA","Overall Crime Grade":"A-","Violent Crime Grade":"C","Property Crime Grade":"A"},{"Nearby Zip":"01342, MA","Overall Crime Grade":"A","Violent Crime Grade":"B+","Property Crime Grade":"A+"},{"Nearby Zip":"01376, MA","Overall Crime Grade":"B-","Violent Crime Grade":"C+","Property Crime Grade":"B-"},{"Nearby Zip":"01337, MA","Overall Crime Grade":"A","Violent Crime Grade":"B-","Property Crime Grade":"A"}],"Similar Population Crime Rates":[{"Similar Zip":"34217, FL","Overall Crime Grade":"A-","Violent Crime Grade":"C+","Property Crime Grade":"C+"},{"Similar Zip":"72046, AR","Overall Crime Grade":"F","Violent Crime Grade":"D-","Property Crime Grade":"D-"},{"Similar Zip":"52778, IA","Overall Crime Grade":"B","Violent Crime Grade":"A-","Property Crime Grade":"A"},{"Similar Zip":"54126, WI","Overall Crime Grade":"A","Violent Crime Grade":"A+","Property Crime Grade":"A+"},{"Similar Zip":"02715, MA","Overall Crime Grade":"A+","Violent Crime Grade":"A-","Property Crime Grade":"A-"},{"Similar Zip":"67025, KS","Overall Crime Grade":"B-","Violent Crime Grade":"B+","Property Crime Grade":"B+"},{"Sim…O que ler deste payload:
- Geral: use a Nota Geral de Criminalidade e as sub-notas para colorir um distintivo de CEP ou medidor de risco.
- Divisão de Criminalidade: leia as taxas por categoria (por exemplo, Agressão, Furto) e os totais e pontuações por categoria.
- Taxas de Criminalidade Próximas: ofereça CEPs alternativos com suas notas.
- Taxas de Criminalidade de População Semelhante: mostre as notas de CEPs comparáveis para contexto.
Nota: as taxas numéricas são retornadas como strings. Converta para números em seu código se precisar calcular com elas.
Exemplo em Python: buscar notas e taxas principais
Este exemplo chama o mesmo endpoint, analisa o JSON e extrai notas e alguns valores de taxa. Substitua YOUR_API_KEY pela sua chave.
import os
import requests
API_KEY = os.getenv("ZYLALABS_API_KEY", "YOUR_API_KEY")
ZIP = "01370"
url = "https://zylalabs.com/api/824/crime-data-by-zipcode-api/583/get-crime-rates-by-zip"
resp = requests.get(url, params={"zip": ZIP}, headers={"Authorization": f"Bearer {API_KEY}"}, timeout=20)
resp.raise_for_status()
data = resp.json()
overall = data.get("Overall", {})
grades = {
"zip": overall.get("Zipcode"),
"overall": overall.get("Overall Crime Grade"),
"violent": overall.get("Violent Crime Grade"),
"property": overall.get("Property Crime Grade"),
"other": overall.get("Other Crime Grade")
}
# Percorra a Divisão de Criminalidade para extrair algumas taxas representativas
assault = robbery = theft = None
for section in data.get("Crime BreakDown", []):
if "Violent Crime Rates" in section:
v = section["Violent Crime Rates"]
assault = float(v.get("Assault")) if v.get("Assault") is not None else None
robbery = float(v.get("Robbery")) if v.get("Robbery") is not None else None
if "Property Crime Rates" in section:
p = section["Property Crime Rates"]
theft = float(p.get("Theft")) if p.get("Theft") is not None else None
print("Notas:", grades)
print("Taxas principais:", {"Assault": assault, "Robbery": robbery, "Theft": theft})
# Lista de CEPs próximos (primeiros três)
neighborhood = data.get("Crime Rates Nearby", [])[:3]
print("Próximos:", nearby)Notas de implementação que economizam tempo
- Autenticação: sempre envie Authorization: Bearer YOUR_API_KEY.
- Entrada: zip é numérico. Certifique-se de passar um CEP de 5 dígitos. Se sua interface captura CEP+4, remova o sufixo.
- Análise: campos como “Agressão”, “Furto” são strings. Converta para float se necessário.
- Cache: faça cache por CEP para evitar buscas repetidas na mesma sessão. As notas de criminalidade mudam lentamente em relação à cadência de solicitações, então um cache diário geralmente é suficiente.
- Fallbacks: se um CEP estiver ausente ou retornar divisões incompletas, exiba a Nota Geral de Criminalidade e CEPs Próximos como alternativas.
- Mapeamento de UI: trate notas (A+ a F) como categorias ordenadas para escalas de cores; não assuma uma escala numérica linear a menos que você converta explicitamente.
- Erros: registre respostas não-2xx com a mensagem e entrada de CEP em seus logs. Adicione validação de entrada do lado do cliente para CEPs de 5 dígitos.
Padrões e casos de uso comuns
- Busca de propriedades: mostre um distintivo de Nota Geral de Criminalidade nas páginas de listagem com base no CEP da propriedade.
- Qualificação de leads: direcione leads de vendas de CEPs de menor risco para filas prioritárias.
- Logística: filtre janelas de entrega ou adicione alertas para motoristas usando as notas de Criminalidade Violenta e Patrimonial.
- Orçamento de seguros: incorpore totais por categoria (por exemplo, Furto de Veículo) em modelos de risco internos.
- Ferramentas de relocação: sugira CEPs Próximos com notas mais altas como alternativas.
Chamando a API de agentes de IA via MCP
Se você usar clientes compatíveis com MCP (por exemplo, Claude Code, Cursor, Windsurf), pode chamar as APIs Zyla através do gateway MCP. Aponte seu cliente para o endpoint MCP e inclua sua chave conforme configurado pela sua ferramenta. Saiba mais aqui: MCP.
O mesmo endpoint do hub é acessível através do gateway, então a única mudança é como seu cliente roteia a solicitação e anexa a Autorização. Consulte a documentação do seu cliente MCP para configuração de ferramentas e roteamento de prompts.
Lista de verificação de fiação de ponta a ponta
- Obtenha uma chave de API na página de listagem do Zyla API Hub.
- Valide e normalize o CEP para uma string numérica de 5 dígitos.
- GET https://zylalabs.com/api/824/crime-data-by-zipcode-api/583/get-crime-rates-by-zip com zip e token Bearer.
- Renderize a Nota Geral de Criminalidade imediatamente; carregue as divisões detalhadas de forma preguiçosa se sua interface precisar delas.
- Ofereça alternativas próximas usando Taxas de Criminalidade Próximas se a nota estiver abaixo do seu limite.
- Cache as respostas por CEP para reduzir latência e chamadas.
FAQ
Qual parâmetro o endpoint requer?
Passe zip como um número na string de consulta, por exemplo, zip=01370.
Como faço para autenticar?
Envie Authorization: Bearer YOUR_API_KEY nos cabeçalhos da solicitação.
O que a API retorna?
Um objeto JSON contendo notas gerais e de categoria de criminalidade, taxas detalhadas, notas de CEPs próximos e notas de CEPs de população semelhante.
As taxas numéricas são números ou strings?
Elas são strings no payload; converta para float no seu código quando necessário.
Como é tratado o faturamento?
A Zyla usa um modelo de assinatura + cota (não pago por chamada). Verifique a página da API para opções de acesso atuais. Você pode iniciar um teste de 7 dias na página de listagem.
Pronto para integrar? Crie sua conta no Zyla API Hub, obtenha sua chave e implemente seu recurso de criminalidade por CEP usando o endpoint da listagem. Comece aqui: API de Dados de Criminalidade por CEP.
Resposta oficial da API
{"Overall":{"Zipcode":"01370","Overall Crime Grade":"B","Violent Crime Grade":"C-","Property Crime Grade":"B","Other Crime Grade":"B"},"Crime BreakDown":[{"Violent Crime Rates":{"Assault":"2.759","Robbery":"0.4627","Rape":"0.5506","Murder":"0.0218"},"0":{"Total Violent Crime":"3.795","Total Violent Crime Score":"(C-)"}},{"Property Crime Rates":{"Theft":"8.498","Vehicle Theft":"0.6988","Burglary":"1.563","Arson":"0.0619"},"0":{"Total Property Crime":"10.82","Total Property Crime Score":"(B)"}},{"Other Crime Rates":{"Kidnapping":"0.1303","Drug Crimes":"1.553","Vandalism":"3.749","Identity Theft":"0.4203","Animal Cruelty":"0.0490"},"0":{"Total Other Rate":"5.902","Total Other Score":"(B)"}}],"Crime Rates Nearby":[{"Nearby Zip":"01338, MA","Overall Crime Grade":"B-","Violent Crime Grade":"D","Property Crime Grade":"B-"},{"Nearby Zip":"01340, MA","Overall Crime Grade":"A-","Violent Crime Grade":"A-","Property Crime Grade":"B"},{"Nearby Zip":"01341, MA","Overall Crime Grade":"A","Violent Crime Grade":"C-","Property Crime Grade":"A"},{"Nearby Zip":"01301, MA","Overall Crime Grade":"C+","Violent Crime Grade":"C-","Property Crime Grade":"C"},{"Nearby Zip":"01330, MA","Overall Crime Grade":"A","Violent Crime Grade":"A-","Property Crime Grade":"A"},{"Nearby Zip":"01346, MA","Overall Crime Grade":"A","Violent Crime Grade":"C","Property Crime Grade":"A"},{"Nearby Zip":"01339, MA","Overall Crime Grade":"A-","Violent Crime Grade":"C","Property Crime Grade":"A"},{"Nearby Zip":"01342, MA","Overall Crime Grade":"A","Violent Crime Grade":"B+","Property Crime Grade":"A+"},{"Nearby Zip":"01376, MA","Overall Crime Grade":"B-","Violent Crime Grade":"C+","Property Crime Grade":"B-"},{"Nearby Zip":"01337, MA","Overall Crime Grade":"A","Violent Crime Grade":"B-","Property Crime Grade":"A"}],"Similar Population Crime Rates":[{"Similar Zip":"34217, FL","Overall Crime Grade":"A-","Violent Crime Grade":"C+","Property Crime Grade":"C+"},{"Similar Zip":"72046, AR","Overall Crime Grade":"F","Violent Crime Grade":"D-","Property Crime Grade":"D-"},{"Similar Zip":"52778, IA","Overall Crime Grade":"B","Violent Crime Grade":"A-","Property Crime Grade":"A"},{"Similar Zip":"54126, WI","Overall Crime Grade":"A","Violent Crime Grade":"A+","Property Crime Grade":"A+"},{"Similar Zip":"02715, MA","Overall Crime Grade":"A+","Violent Crime Grade":"A-","Property Crime Grade":"A-"},{"Similar Zip":"67025, KS","Overall Crime Grade":"B-","Violent Crime Grade":"B+","Property Crime Grade":"B+"},{"Sim…Resposta oficial da API
{"Overall":{"Zipcode":"01370","Overall Crime Grade":"B","Violent Crime Grade":"C-","Property Crime Grade":"B","Other Crime Grade":"B"},"Crime BreakDown":[{"Violent Crime Rates":{"Assault":"2.759","Robbery":"0.4627","Rape":"0.5506","Murder":"0.0218"},"0":{"Total Violent Crime":"3.795","Total Violent Crime Score":"(C-)"}},{"Property Crime Rates":{"Theft":"8.498","Vehicle Theft":"0.6988","Burglary":"1.563","Arson":"0.0619"},"0":{"Total Property Crime":"10.82","Total Property Crime Score":"(B)"}},{"Other Crime Rates":{"Kidnapping":"0.1303","Drug Crimes":"1.553","Vandalism":"3.749","Identity Theft":"0.4203","Animal Cruelty":"0.0490"},"0":{"Total Other Rate":"5.902","Total Other Score":"(B)"}}],"Crime Rates Nearby":[{"Nearby Zip":"01338, MA","Overall Crime Grade":"B-","Violent Crime Grade":"D","Property Crime Grade":"B-"},{"Nearby Zip":"01340, MA","Overall Crime Grade":"A-","Violent Crime Grade":"A-","Property Crime Grade":"B"},{"Nearby Zip":"01341, MA","Overall Crime Grade":"A","Violent Crime Grade":"C-","Property Crime Grade":"A"},{"Nearby Zip":"01301, MA","Overall Crime Grade":"C+","Violent Crime Grade":"C-","Property Crime Grade":"C"},{"Nearby Zip":"01330, MA","Overall Crime Grade":"A","Violent Crime Grade":"A-","Property Crime Grade":"A"},{"Nearby Zip":"01346, MA","Overall Crime Grade":"A","Violent Crime Grade":"C","Property Crime Grade":"A"},{"Nearby Zip":"01339, MA","Overall Crime Grade":"A-","Violent Crime Grade":"C","Property Crime Grade":"A"},{"Nearby Zip":"01342, MA","Overall Crime Grade":"A","Violent Crime Grade":"B+","Property Crime Grade":"A+"},{"Nearby Zip":"01376, MA","Overall Crime Grade":"B-","Violent Crime Grade":"C+","Property Crime Grade":"B-"},{"Nearby Zip":"01337, MA","Overall Crime Grade":"A","Violent Crime Grade":"B-","Property Crime Grade":"A"}],"Similar Population Crime Rates":[{"Similar Zip":"34217, FL","Overall Crime Grade":"A-","Violent Crime Grade":"C+","Property Crime Grade":"C+"},{"Similar Zip":"72046, AR","Overall Crime Grade":"F","Violent Crime Grade":"D-","Property Crime Grade":"D-"},{"Similar Zip":"52778, IA","Overall Crime Grade":"B","Violent Crime Grade":"A-","Property Crime Grade":"A"},{"Similar Zip":"54126, WI","Overall Crime Grade":"A","Violent Crime Grade":"A+","Property Crime Grade":"A+"},{"Similar Zip":"02715, MA","Overall Crime Grade":"A+","Violent Crime Grade":"A-","Property Crime Grade":"A-"},{"Similar Zip":"67025, KS","Overall Crime Grade":"B-","Violent Crime Grade":"B+","Property Crime Grade":"B+"},{"Sim…
