Conecte seus sistemas
à API ZipData.

Comece com um token de avaliação.

Solicite seu acesso à equipe ZipData. O token identifica a integração e deve ficar no servidor da sua aplicação, sem aparecer no código público do navegador.

Solicitar meu token

Uma integração para duas pesquisas.

Endereço base: https://consulta.zipdata.com.br. Envie o corpo com application/x-www-form-urlencoded.

Consulta por CEP

Pesquisa por endereço

No endpoint /search/multiple, envie type, token, street, city, uf e return. Os campos district e cep são opcionais para refinar a pesquisa.

Exemplo em PHP

Configure ZIPDATA_TOKEN como variável de ambiente do servidor. O exemplo utiliza as extensões cURL e JSON.

<?php
$token = getenv('ZIPDATA_TOKEN');
$dados = [
    'type' => 'api',
    'token' => $token,
    'cep' => '01001000',
    'return' => 'acento'
];
$ch = curl_init('https://consulta.zipdata.com.br/search/unique');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => http_build_query($dados),
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/x-www-form-urlencoded'
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 20
]);
$raw = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($raw === false) {
    throw new RuntimeException('Falha de conexão com a API.');
}
curl_close($ch);
if ($status < 200 || $status >= 300) {
    throw new RuntimeException('A consulta não foi concluída.');
}
$resultado = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
// Utilize os campos disponíveis na resposta da sua consulta.

Exemplo em Python

O exemplo usa a biblioteca requests e a mesma variável de ambiente.

import os
import requests

resposta = requests.post(
    "https://consulta.zipdata.com.br/search/unique",
    data={
        "type": "api",
        "token": os.environ["ZIPDATA_TOKEN"],
        "cep": "01001000",
        "return": "acento",
    },
    timeout=20,
)
resposta.raise_for_status()
resultado = resposta.json()

Interprete o retorno da sua consulta.

O resultado vem em JSON, acompanhado do status HTTP. Confira quais campos estão disponíveis nos testes com seu token e trate dados ausentes no seu sistema. Os exemplos desta página mostram a requisição, sem definir um esquema fixo para todas as respostas.

Prepare o tratamento de falhas.

• Defina um tempo limite de conexão e de resposta.
• Confira o status HTTP antes de utilizar o conteúdo.
• Trate falhas de decodificação JSON e campos indisponíveis.
• Evite tentativas ilimitadas e registre erros sem incluir o token.