---
title: "Consulta de CEP (lookups.cep) no SDK Python da NFE.io"
description: "Consulte o endereço e o código IBGE do município a partir do CEP com client.lookups.cep."
source_url: https://nfe.io/docs/desenvolvedores/bibliotecas/python/recursos/consulta-cep/
product: bibliotecas
last_updated: 2026-10-14
tags: ["python", "referencia", "consulta"]
integration: ["sdk"]
---

# Consulta de CEP (`lookups.cep`)

`client.lookups.cep` devolve o endereço de um CEP pela
[API de Consulta de Endereços](/desenvolvedores/rest-api/consulta-de-enderecos-v1), em
`https://address.api.nfe.io`. O uso mais comum é obter o **código IBGE do município**
(`city.code`), exigido no endereço do tomador da NFS-e.

:::note Use a `data_api_key`
As consultas usam a chave de dados (`data_api_key` ou `NFE_DATA_API_KEY`). Veja
[Configuração](../configuration.md).
:::

## Método

```python
lookups.cep(cep, *, options=None) -> Address
```

## Exemplo

```python
from nfeio import NfeClient

client = NfeClient()

endereco = client.lookups.cep("01310-100")  # com ou sem traço
print(endereco.postal_code)                 # "01310100"
print(endereco["street"], endereco["district"])
print(endereco["city"]["code"], endereco["city"]["name"], endereco["state"])
```

`Address` tem uma propriedade tipada, `postal_code` (8 dígitos, sem traço). Os demais campos
(`street`, `streetSuffix`, `district`, `city`, `state`, `country`, `additionalInformation`) ficam no
acesso por chave.

## Montar o endereço do tomador

```python
from nfeio import NfeClient
from nfeio.types import AddressParams

client = NfeClient()

endereco = client.lookups.cep("01310-100")
address: AddressParams = {
    "country": "BRA",
    "postalCode": endereco.postal_code or "",
    "street": endereco["street"],
    "number": "2000",
    "district": endereco["district"],
    "city": {"code": endereco["city"]["code"], "name": endereco["city"]["name"]},
    "state": endereco["state"],
}
```

O resultado pode ir direto em `borrower.address` na emissão da NFS-e.

## Validação local

O CEP precisa ter 8 dígitos (o traço é opcional). Fora disso, o SDK levanta `InvalidParameterError`
antes da requisição:

```python
from nfeio import InvalidParameterError, NfeClient

client = NfeClient(api_key="chave-de-exemplo", data_api_key="chave-de-dados-de-exemplo")

try:
    client.lookups.cep("0131-010")
except InvalidParameterError as erro:
    print(erro.param, "-", erro)  # cep - cep must have 8 digits, got '0131-010'
```

Um CEP com formato válido que não existe na base volta como erro da API (`InvalidRequestError` ou
`NotFoundError`).

## Veja também

- [Consulta de CNPJ](./legal-entity-lookup.md) e [Consulta de CPF](./natural-person-lookup.md).
- [Notas de serviço](./service-invoices.md): o endereço do tomador na emissão.