Documentação da API
API MyCEP para consulta de CEP e endereços
Integre sistemas, portais e rotinas internas com a base MyCEP. A API pública permite consultar um CEP específico ou pesquisar endereços por cidade e logradouro, retornando dados normalizados com bairro, UF e código IBGE quando disponíveis.
Referência interativa
Todos os endpoints, parâmetros e respostas — com “executar” no navegador usando a sua chave.
Exemplos de integração
O mesmo pedido em 8 linguagens. Troque a chave pelo valor gerado em Chaves de API.
curl "https://api.mycep.app.br/api/v1/search/cep/01001000" \
-H "Authorization: Bearer cep_live_sua_chave_aqui"
import { MyCepClient } from '@mycep/sdk'
const mycep = new MyCepClient({ apiKey: process.env.MYCEP_API_KEY })
const endereco = await mycep.lookupCep('01001-000')
console.log(endereco.logradouro, endereco.cidade, endereco.uf)
// Sem o SDK, com fetch puro:
const resposta = await fetch('https://api.mycep.app.br/api/v1/search/cep/01001000', {
headers: { Authorization: `Bearer ${process.env.MYCEP_API_KEY}` },
})
if (!resposta.ok) throw new Error('Falha na consulta')
console.log(await resposta.json())
import os
import requests
BASE = "https://api.mycep.app.br"
headers = {"Authorization": f"Bearer {os.environ['MYCEP_API_KEY']}"}
resposta = requests.get(f"{BASE}/api/v1/search/cep/01001000", headers=headers, timeout=10)
resposta.raise_for_status()
endereco = resposta.json()
print(endereco["logradouro"], endereco["cidade"], endereco["uf"])
<?php
$chave = getenv('MYCEP_API_KEY');
$ch = curl_init('https://api.mycep.app.br/api/v1/search/cep/01001000');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 10,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $chave],
]);
$corpo = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status !== 200) {
throw new RuntimeException('Falha na consulta ao MyCEP');
}
$endereco = json_decode($corpo, true);
echo $endereco['logradouro'], ' - ', $endereco['cidade'], '/', $endereco['uf'];
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
public class MyCep {
private static final String BASE = "https://api.mycep.app.br";
public static String buscarCep(String cep) throws Exception {
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(BASE + "/api/v1/search/cep/" + cep))
.header("Authorization", "Bearer " + System.getenv("MYCEP_API_KEY"))
.timeout(Duration.ofSeconds(10))
.GET()
.build();
HttpResponse<String> response =
client.send(request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() != 200) {
throw new IllegalStateException("Falha na consulta ao MyCEP");
}
return response.body();
}
}
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
public class MyCepClient
{
private const string Base = "https://api.mycep.app.br";
private static readonly HttpClient Http = new HttpClient();
public static async Task<string> BuscarCepAsync(string cep)
{
var chave = Environment.GetEnvironmentVariable("MYCEP_API_KEY");
using var request = new HttpRequestMessage(
HttpMethod.Get, $"{Base}/api/v1/search/cep/{cep}");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", chave);
using var response = await Http.SendAsync(request);
response.EnsureSuccessStatusCode();
return await response.Content.ReadAsStringAsync();
}
}
# app/services/my_cep.rb
require "net/http"
require "json"
class MyCep
BASE = URI("https://api.mycep.app.br").freeze
def self.buscar_cep(cep)
uri = URI.join(BASE, "/api/v1/search/cep/#{cep.gsub(/\D/, '')}")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer #{Rails.application.credentials.mycep_api_key}"
resposta = Net::HTTP.start(uri.host, uri.port, use_ssl: true, read_timeout: 10) do |http|
http.request(request)
end
raise "Falha na consulta ao MyCEP" unless resposta.is_a?(Net::HTTPSuccess)
JSON.parse(resposta.body)
end
end
package mycep
import (
"encoding/json"
"fmt"
"net/http"
"os"
"time"
)
const base = "https://api.mycep.app.br"
type Endereco struct {
Cep string `json:"cep"`
Logradouro string `json:"logradouro"`
Bairro string `json:"bairro"`
Cidade string `json:"cidade"`
UF string `json:"uf"`
IBGE string `json:"ibge"`
}
func BuscarCEP(cep string) (*Endereco, error) {
req, err := http.NewRequest("GET", base+"/api/v1/search/cep/"+cep, nil)
if err != nil {
return nil, err
}
req.Header.Set("Authorization", "Bearer "+os.Getenv("MYCEP_API_KEY"))
client := &http.Client{Timeout: 10 * time.Second}
resp, err := client.Do(req)
if err != nil {
return nil, err
}
defer resp.Body.Close()
if resp.StatusCode != http.StatusOK {
return nil, fmt.Errorf("mycep: status %d", resp.StatusCode)
}
var endereco Endereco
if err := json.NewDecoder(resp.Body).Decode(&endereco); err != nil {
return nil, err
}
return &endereco, nil
}
Resposta
{
"cep": "01001-000",
"tipoLogradouro": "Praça",
"logradouro": "da Sé",
"bairro": "Sé",
"cidade": "São Paulo",
"uf": "SP",
"ibge": "3550308",
"latitude": -23.5505,
"longitude": -46.6333,
"geoPrecision": "street",
"siafi": "7107",
"ddd": "11",
"timezone": "America/Sao_Paulo"
}
Buscar endereço por CEP
Use este endpoint quando o sistema já possui o CEP e precisa recuperar logradouro, bairro, cidade, UF e código IBGE.
GET /api/v1/search/cep/01001000
{
"cep": "01001-000",
"tipoLogradouro": "Praça",
"logradouro": "da Sé",
"bairro": "Sé",
"cidade": "São Paulo",
"uf": "SP",
"ibge": "3550308",
"latitude": -23.5505,
"longitude": -46.6333,
"geoPrecision": "street",
"siafi": "7107",
"ddd": "11",
"timezone": "America/Sao_Paulo"
}
Buscar por cidade e logradouro
Use a busca textual para encontrar endereços quando o usuário informa cidade e parte do logradouro. Os dois parâmetros vão no caminho da URL em UTF-8 percent-encoded — é o que encodeURIComponent (JS), rawurlencode (PHP) e quote (Python) fazem. Acento enviado em ISO-8859-1 ou % literal sem virar %25 recebem 400.
GET /api/v1/search/address/Rio%20de%20Janeiro/Avenida%20Nilo%20Pe%C3%A7anha
{
"addresses": [
"…lista de endereços no mesmo formato…"
]
}
Autenticação e limites de uso
Assinantes autenticam por chave, não por IP. Crie uma chave em Conta → Chaves de API e envie-a no header Authorization: Bearer cep_live_…. Isso funciona de qualquer runtime — serverless, container ou função de borda — sem IP de saída fixo. A chave é exibida por inteiro apenas na criação: guardamos somente um hash.
Se quiser, cada chave aceita restrições opcionais de IP e de origem (Origin/Referer, para uso no navegador). Sem restrições, a chave vale de qualquer lugar; com elas, o que não bater é recusado.
A cota é mensal por assinante (o contador reseta no primeiro dia do mês, horário de Brasília) e varia por plano — veja planos. Ao esgotar, a API responde 429 com quota_exceeded.
A consulta pública anônima continua disponível em até 5 requisições por minuto e 30 por dia por endereço IP, sem campos de enriquecimento. Ao exceder qualquer um dos dois, o IP fica bloqueado por 6 horas. Para mais volume, crie uma conta grátis e use sua chave de API (500 consultas por mês).
Assinantes antigos que autenticam por IP cadastrado continuam funcionando com as condições do seu plano — a mudança para chave é opcional.
Sistemas parceiros (ex.: model5 clinic) usam uma chave de sistema no header Authorization: Bearer api_… — sem limite de consultas. Chaves MCP (mcp_…) valem só em POST /mcp e são recusadas na API REST.
Referência completa, com “try it” no navegador: /docs · documento OpenAPI: /openapi.json.
Operamos com monitoramento contínuo e esforços comerciais razoáveis de disponibilidade. SLA contratual com percentual garantido, IP dedicado e faturamento por contrato fazem parte do plano Enterprise.
Os exemplos desta página são ilustrativos e fornecidos no estado em que se encontram: não integram o objeto da assinatura e não constituem recomendação de arquitetura para o seu caso — ver a seção 12 dos Termos de Assinatura.
Campos retornados
cep |
CEP formatado (00000-000) |
tipoLogradouro |
Tipo do logradouro (Rua, Avenida, Praça…) |
logradouro |
Nome completo do logradouro |
bairro |
Bairro, quando disponível |
cidade / uf |
Município e unidade federativa |
ibge |
Código IBGE do município |