Introdução
Documentação oficial da ZipFinder API
Bem-vindo à documentação oficial do ZipFinder. Nossa API RESTful foi desenhada para alta disponibilidade e latência ultrabaixa, utilizando fontes atualizadas para consulta de endereços no Brasil.
Autenticação
Todas as requisições para a ZipFinder API devem ser autenticadas com sua API key.
Use o header HTTP x-api-key
para acessar os endpoints públicos.
Header Necessário
x-api-key: {sua_api_key_aqui}
Busca CEP
Consulte um CEP retornando país, logradouro, bairro, cidade, estado, código IBGE, latitude, longitude, origem da informação e data de atualização.
/v1/postal-codes/{postalCode}
Exemplo curl
curl --request GET \ --url http://localhost:7071/api/v1/postal-codes/04757-000 \ --header "x-api-key: SUA_API_KEY"
JSON response
{
"IsoAlpha2Country": "BR",
"IsoAlpha3Country": "BRA",
"ZipCode": "04757-000",
"Street": "Rua Bento Branco de Andrade Filho",
"TypeStreet": "Rua",
"NameStreet": "Bento Branco de Andrade Filho",
"Neighborhood": "Jardim Dom Bosco",
"City": "São Paulo",
"State": "SP",
"IbgeCode": "3550308",
"Latitude": -23.63583033646994,
"Longitude": -46.74829410149799,
"Source": "Correios do Brasil",
"LastUpdated": "2026-04-22T19:10:42.000Z"
}
Detalhe por CEP + Número
Consulte o endereço detalhado a partir do CEP e do prefixo do número. A busca usa a base consolidada do IBGE, ordena por maior ocorrência e confiança e retorna apenas um resultado.
/v1/postal-codes/{postalCode}/details?number={prefixo}
number
faz busca por prefixo equivalente a LIKE '34%'.
Exemplo curl
curl --request GET \ --url "http://localhost:7071/api/v1/postal-codes/69309630/details?number=34" \ --header "x-api-key: SUA_API_KEY"
JSON response
{
"ZipCode": "69309-630",
"Number": "34",
"Street": "Rua Exemplo",
"TypeStreet": "Rua",
"NameStreet": "Exemplo",
"Neighborhood": "Centro",
"City": "Boa Vista",
"State": "RR",
"IbgeCode": "1400100",
"Latitude": 2.823500,
"Longitude": -60.675300,
"Confidence": 0.9821,
"Source": "IBGE",
"LastUpdated": "2026-04-22T19:10:42.000Z"
}
Estados API
Liste os estados disponíveis para um país usando o código ISO alpha-3, como `BRA`.
GET /v1/countries/{countryCode}/states
{
"Country": {
"IsoAlpha2": "BR",
"IsoAlpha3": "BRA",
"Name": "Brasil"
},
"States": [
{ "Code": "SP", "Name": "Sao Paulo" },
{ "Code": "RJ", "Name": "Rio de Janeiro" }
]
}
Cidades API
Liste as cidades de um estado dentro de um país para compor formulários, filtros e fluxos de preenchimento assistido.
GET /v1/countries/{countryCode}/states/{state}/cities
{
"Country": {
"IsoAlpha2": "BR",
"IsoAlpha3": "BRA",
"Name": "Brasil"
},
"State": {
"Code": "SP",
"Name": "Sao Paulo"
},
"Cities": ["Campinas", "Sao Paulo"]
}