Documentação da API de CEP
Um endereço, uma resposta em JSON. Copie o exemplo da sua linguagem e rode: não precisa de cadastro nem de chave.
Publicado em . Fontes oficiais: o CEP nos Correios e os códigos de municÃpio do IBGE.
Comece em um minuto
O exemplo busca o endereço pelo CEP e mostra a rua, a cidade e o código IBGE. Troque o número pelo CEP que você quer.
curl https://cep.wortic.com/cep/01001000
// Node 18+ ou navegador
const r = await fetch("https://cep.wortic.com/cep/01001000");
if (r.status === 429) throw new Error("Limite: espere " + r.headers.get("retry-after") + " s");
const e = await r.json();
console.log(e.logradouro, "-", e.cidade + "/" + e.uf, "- IBGE", e.cidade_ibge);# Python 3, só a biblioteca padrão
import json, urllib.request
with urllib.request.urlopen("https://cep.wortic.com/cep/01001000") as r:
e = json.load(r)
print(e["logradouro"], "-", e["cidade"] + "/" + e["uf"], "- IBGE", e["cidade_ibge"])<?php
$json = file_get_contents("https://cep.wortic.com/cep/01001000");
$e = json_decode($json, true);
echo $e["logradouro"], " - ", $e["cidade"], "/", $e["uf"], " - IBGE ", $e["cidade_ibge"], "\n";require "net/http"
require "json"
e = JSON.parse(Net::HTTP.get(URI("https://cep.wortic.com/cep/01001000")))
puts "#{e["logradouro"]} - #{e["cidade"]}/#{e["uf"]} - IBGE #{e["cidade_ibge"]}"// Java 11+
import java.net.URI;
import java.net.http.*;
public class Exemplo {
public static void main(String[] args) throws Exception {
var pedido = HttpRequest.newBuilder(URI.create("https://cep.wortic.com/cep/01001000")).build();
var resposta = HttpClient.newHttpClient().send(pedido, HttpResponse.BodyHandlers.ofString());
System.out.println(resposta.statusCode() + " " + resposta.body());
}
}import java.net.URI
import java.net.http.HttpClient
import java.net.http.HttpRequest
import java.net.http.HttpResponse
fun main() {
val pedido = HttpRequest.newBuilder(URI.create("https://cep.wortic.com/cep/01001000")).build()
val resposta = HttpClient.newHttpClient().send(pedido, HttpResponse.BodyHandlers.ofString())
println("${resposta.statusCode()} ${resposta.body()}")
}import Foundation
struct Endereco: Decodable { let logradouro: String; let cidade: String; let uf: String; let cidade_ibge: Int }
let url = URL(string: "https://cep.wortic.com/cep/01001000")!
let (dados, _) = try await URLSession.shared.data(from: url)
let e = try JSONDecoder().decode(Endereco.self, from: dados)
print(e.logradouro, "-", "\(e.cidade)/\(e.uf)", "- IBGE", e.cidade_ibge)// Cargo.toml: reqwest = { version = "0.12", features = ["blocking", "json"] }
// serde_json = "1"
fn main() -> Result<(), Box<dyn std::error::Error>> {
let e: serde_json::Value =
reqwest::blocking::get("https://cep.wortic.com/cep/01001000")?.json()?;
println!("{} - {}/{} - IBGE {}", e["logradouro"].as_str().unwrap_or(""), e["cidade"].as_str().unwrap_or(""),
e["uf"].as_str().unwrap_or(""), e["cidade_ibge"]);
Ok(())
}package main
import (
"encoding/json"
"fmt"
"net/http"
)
func main() {
r, err := http.Get("https://cep.wortic.com/cep/01001000")
if err != nil {
panic(err)
}
defer r.Body.Close()
var e struct {
Logradouro string `json:"logradouro"`
Cidade string `json:"cidade"`
UF string `json:"uf"`
CidadeIBGE int `json:"cidade_ibge"`
}
json.NewDecoder(r.Body).Decode(&e)
fmt.Println(e.Logradouro, "-", e.Cidade+"/"+e.UF, "- IBGE", e.CidadeIBGE)
}Saída esperada: Praça da Sé - São Paulo/SP - IBGE 3550308. Java e Kotlin mostram o código HTTP e o JSON inteiro.
No seu framework
A mesma consulta, escrita do jeito de cada pilha. TypeScript, Dart, Objective-C e COBOL rodaram contra esta API antes de entrar aqui; o TypeScript passou no compilador em modo estrito; o hook de React passou nos tipos oficiais do React 19; Laravel e WordPress tiveram a sintaxe conferida; Next.js, Vue, Svelte, Angular, Solid, Astro e Remix chamam a mesma função do TypeScript.
TypeScript (navegador, Node, Deno, Bun, borda)
// cep.ts: a consulta tipada, igual no navegador, no Node, no Deno, no Bun, no React Native e na borda.
export interface Endereco {
cep: string;
cep_formatado: string;
logradouro: string;
complemento: string;
bairro: string;
cidade: string;
cidade_ibge: number;
uf: string;
unidade: string;
fonte: string;
}
export class LimiteAtingido extends Error {
readonly esperarSegundos: number;
constructor(esperarSegundos: number) {
super(`limite da API: tente de novo em ${esperarSegundos} s`);
this.esperarSegundos = esperarSegundos;
}
}
export async function buscarCep(cep: string, sinal?: AbortSignal): Promise<Endereco> {
const r = await fetch(`https://cep.wortic.com/cep/${cep.replace(/\D/g, "")}`, { signal: sinal ?? null });
if (r.status === 429) throw new LimiteAtingido(Number(r.headers.get("retry-after") ?? 60));
if (!r.ok) throw new Error(`CEP ${cep}: HTTP ${r.status}`);
return r.json() as Promise<Endereco>;
}React e React Native
// useEndereco.ts: React e React Native. A consulta é cancelada se o CEP mudar ou o componente sair da tela.
import { useEffect, useState } from "react";
import { buscarCep, type Endereco } from "./cep.ts";
type Estado = { endereco?: Endereco; erro?: Error; carregando: boolean };
export function useEndereco(cep: string): Estado {
const [estado, setEstado] = useState<Estado>({ carregando: true });
useEffect(() => {
const controle = new AbortController();
setEstado({ carregando: true });
buscarCep(cep, controle.signal)
.then((endereco) => setEstado({ endereco, carregando: false }))
.catch((erro: unknown) => {
if (!controle.signal.aborted) setEstado({ erro: erro as Error, carregando: false });
});
return () => controle.abort();
}, [cep]);
return estado;
}Next.js (Route Handler)
// app/api/endereco/[cep]/route.ts (Next.js App Router): guarda a resposta por um dia no cache do Next.
import { buscarCep, LimiteAtingido } from "./cep.ts";
export async function GET(_: Request, { params }: { params: Promise<{ cep: string }> }): Promise<Response> {
try {
return Response.json(await buscarCep((await params).cep), { headers: { "cache-control": "s-maxage=86400" } });
} catch (e) {
if (e instanceof LimiteAtingido) return new Response(null, { status: 429, headers: { "retry-after": String(e.esperarSegundos) } });
return Response.json({ erro: (e as Error).message }, { status: 404 });
}
}Vue, Svelte, Angular, Solid, Astro e Remix
// Todos chamam a mesma buscarCep de cep.ts, no lugar onde cada framework carrega dados.
// Vue 3 (<script setup lang="ts">)
const endereco = ref<Endereco>();
onMounted(async () => (endereco.value = await buscarCep(props.cep)));
// SvelteKit (src/routes/endereco/[cep]/+page.ts)
export const load = async ({ params }) => ({ endereco: await buscarCep(params.cep) });
// Angular (componente)
endereco = signal<Endereco | undefined>(undefined);
async ngOnInit() { this.endereco.set(await buscarCep(this.cep)); }
// SolidJS
const [endereco] = createResource(() => props.cep, buscarCep);
// Astro (frontmatter da página)
const endereco = await buscarCep(Astro.params.cep!);
// Remix / React Router 7 (loader da rota)
export const loader = ({ params }: LoaderFunctionArgs) => buscarCep(params.cep!);Flutter e Dart
// cep.dart: Dart e Flutter, só com a biblioteca padrão (dart:io e dart:convert).
import 'dart:convert';
import 'dart:io';
typedef Endereco = ({String logradouro, String cidade, String uf, int ibge});
Future<Endereco> buscarCep(String cep) async {
final cliente = HttpClient();
try {
final pedido = await cliente.getUrl(Uri.https('cep.wortic.com', '/cep/${cep.replaceAll(RegExp(r'\D'), '')}'));
final resposta = await pedido.close();
if (resposta.statusCode == 429) throw HttpException('limite: espere ${resposta.headers.value('retry-after')} s');
if (resposta.statusCode != 200) throw HttpException('CEP $cep: HTTP ${resposta.statusCode}');
final e = jsonDecode(await resposta.transform(utf8.decoder).join()) as Map<String, Object?>;
return (
logradouro: e['logradouro']! as String,
cidade: e['cidade']! as String,
uf: e['uf']! as String,
ibge: e['cidade_ibge']! as int,
);
} finally {
cliente.close();
}
}
Future<void> main() async {
final e = await buscarCep('01001-000');
print('Dart: ${e.logradouro} - ${e.cidade}/${e.uf} - IBGE ${e.ibge}');
}Laravel
<?php
// Laravel 12+: o cliente HTTP do framework, com nova tentativa no limite e cache de um dia.
declare(strict_types=1);
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Http;
function buscarCep(string $cep): array
{
$digitos = preg_replace('/\D/', '', $cep);
return Cache::remember("cep:$digitos", now()->addDay(), static fn (): array => Http::baseUrl('https://cep.wortic.com')
->retry(3, static fn (int $tentativa, Exception $e): int => (int) ($e->response?->header('Retry-After') ?: 1) * 1000)
->get("/cep/$digitos")
->throw()
->json());
}WordPress
<?php
// WordPress: a API HTTP do próprio WordPress, com a resposta guardada num transient por um dia.
declare(strict_types=1);
function wortic_buscar_cep(string $cep): array|WP_Error
{
$digitos = preg_replace('/\D/', '', $cep);
$guardado = get_transient("wortic_cep_$digitos");
if (is_array($guardado)) {
return $guardado;
}
$resposta = wp_remote_get("https://cep.wortic.com/cep/$digitos", ['timeout' => 10]);
if (is_wp_error($resposta)) {
return $resposta;
}
if (wp_remote_retrieve_response_code($resposta) !== 200) {
return new WP_Error('cep', 'HTTP ' . wp_remote_retrieve_response_code($resposta));
}
$endereco = json_decode(wp_remote_retrieve_body($resposta), true, 512, JSON_THROW_ON_ERROR);
set_transient("wortic_cep_$digitos", $endereco, DAY_IN_SECONDS);
return $endereco;
}iOS e macOS (Objective-C)
// cep.m: iOS e macOS em Objective-C, com NSURLSession. clang -fobjc-arc cep.m -framework Foundation -o cep
#import <Foundation/Foundation.h>
static void buscarCep(NSString *cep, void (^pronto)(NSDictionary *_Nullable endereco, NSError *_Nullable erro)) {
NSString *digitos = [[cep componentsSeparatedByCharactersInSet:NSCharacterSet.decimalDigitCharacterSet.invertedSet]
componentsJoinedByString:@""];
NSURL *url = [NSURL URLWithString:[@"https://cep.wortic.com/cep/" stringByAppendingString:digitos]];
[[NSURLSession.sharedSession dataTaskWithURL:url
completionHandler:^(NSData *dados, NSURLResponse *resposta, NSError *erro) {
NSInteger status = ((NSHTTPURLResponse *)resposta).statusCode;
if (erro) {
pronto(nil, erro);
} else if (status != 200) {
pronto(nil, [NSError errorWithDomain:@"cep.wortic.com" code:status userInfo:nil]);
} else {
pronto([NSJSONSerialization JSONObjectWithData:dados options:0 error:&erro], erro);
}
}] resume];
}
int main(void) {
@autoreleasepool {
dispatch_semaphore_t fim = dispatch_semaphore_create(0);
buscarCep(@"01001-000", ^(NSDictionary *e, NSError *erro) {
if (erro) NSLog(@"%@", erro);
else printf("Objective-C: %s - %s/%s - IBGE %ld\n", [e[@"logradouro"] UTF8String], [e[@"cidade"] UTF8String],
[e[@"uf"] UTF8String], (long)[e[@"cidade_ibge"] integerValue]);
dispatch_semaphore_signal(fim);
});
dispatch_semaphore_wait(fim, DISPATCH_TIME_FOREVER);
}
}COBOL
>>SOURCE FORMAT FREE
*> cep.cob: COBOL (GnuCOBOL 3.2+). Busca o endereço pelo curl do sistema e tira o logradouro e a cidade com UNSTRING.
*> cobc -x -free cep.cob -o cep && ./cep 01001000
IDENTIFICATION DIVISION.
PROGRAM-ID. CEP.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT RESPOSTA ASSIGN TO "cep-resposta.txt" ORGANIZATION LINE SEQUENTIAL.
DATA DIVISION.
FILE SECTION.
FD RESPOSTA.
01 LINHA PIC X(4096).
WORKING-STORAGE SECTION.
01 CEP PIC X(9).
01 COMANDO PIC X(200).
01 ANTES PIC X(4096).
01 RESTO PIC X(4096).
01 LOGRADOURO PIC X(150).
01 CIDADE PIC X(100).
PROCEDURE DIVISION.
ACCEPT CEP FROM ARGUMENT-VALUE
STRING "curl -s https://cep.wortic.com/cep/" FUNCTION TRIM(CEP) " -o cep-resposta.txt"
DELIMITED BY SIZE INTO COMANDO
CALL "SYSTEM" USING COMANDO
OPEN INPUT RESPOSTA
READ RESPOSTA
CLOSE RESPOSTA
UNSTRING LINHA DELIMITED BY '"logradouro":"' INTO ANTES RESTO
UNSTRING RESTO DELIMITED BY '"' INTO LOGRADOURO
UNSTRING LINHA DELIMITED BY '"cidade":"' INTO ANTES RESTO
UNSTRING RESTO DELIMITED BY '"' INTO CIDADE
DISPLAY "COBOL: " FUNCTION TRIM(LOGRADOURO) " - " FUNCTION TRIM(CIDADE)
STOP RUN.Os dois endereços
| Endereço | O que devolve |
|---|---|
GET /cep/{cep} | O endereço do CEP: logradouro, complemento, bairro, cidade, código IBGE da cidade, estado e unidade. Aceita o CEP com ou sem traço. |
GET /cep/buscar?uf=&cidade=&logradouro=&limite= | Os CEPs de uma rua numa cidade: rua com 3 letras ou mais, cidade com ou sem acento, até 50 CEPs (padrão 20). |
Descrição completa, campo a campo, em openapi.json. Ele abre direto no Postman, no Insomnia e nos geradores de cliente.
Respostas de erro
| Código | Quando | O que fazer |
|---|---|---|
400 cep_invalido | O CEP não tem 8 números | Confira o número antes de consultar |
400 uf_invalida | A sigla do estado não existe | Use a sigla, como SP ou RS |
400 busca_curta | Rua com menos de 3 letras | Peça mais letras ao usuário |
404 nao_encontrado | CEP que não está na base dos Correios | Trate como "não achei" |
422 | Falta uf, cidade ou logradouro, ou o limite está fora de 1 a 50 | Mande os três campos |
402 limite_gratis | Mais de 60 consultas no minuto, sem chave | Espere os segundos do retry-after ou assine um plano: a resposta traz os planos e os links de compra |
429 bloqueado | IP bloqueado por 1 ou 6 horas | Espere o retry-after e reduza o ritmo |
403 banido | IP banido de vez | Fale com a Wortic |
Limite e bloqueio
Sem chave, são 60 consultas por minuto por IP. Cada minuto em que o IP passa do limite conta uma vez. Com 10 vezes, o IP fica bloqueado por 1 hora. Depois de 3 bloqueios de 1 hora, o seguinte é de 6 horas. Depois de 3 bloqueios de 6 horas, o IP é banido de vez. Quem fica abaixo de 60 por minuto nunca é bloqueado.
Para volume maior, use uma chave no cabeçalho x-api-key: vale o limite do seu plano e a escada de bloqueio não se aplica. Fale com a Wortic.
Pagamento por máquina (HTTP 402)
Desde 14/11/2026, quem passa do limite grátis recebe 402 Payment Required nos dois formatos que agentes de IA entendem: o cabeçalho payment-required (x402 versão 2, com os planos em accepts, valor em centavos e moeda BRL) e o cabeçalho www-authenticate: Payment (MPP). O corpo, em português, lista os planos com o link de compra de cada um. Por enquanto a compra é pelo link; o pagamento direto pela API ainda não está ligado e responde 402 meio_ainda_nao_ligado. Programas que tratam 429 continuam funcionando se tratarem 402 do mesmo jeito.
A resposta encontrada pode ser guardada por 24 horas (cache-control: public, max-age=86400) e a de "não encontrado" por 1 hora.
Sem banco de dados no caminho
A API lê a base dos Correios direto de um arquivo jsonW, o formato de dados da Wortic, grátis para usar no seu produto. Conheça em jsonw.org.
Junto com o CNPJ
A ficha da empresa pelo CNPJ, com o endereço dela, está na API de CNPJ. Para agentes que leem a API por conta própria, o llms.txt traz as rotas, o limite e como citar a fonte.