# Pesquisa avançada de CEPs

> Parâmetros, exemplos e respostas de GET /v1/ceps na NextAPI.

Fonte: https://www.nextapi.com.br/docs/api/get-v1-ceps

`GET /v1/ceps`

Retorna uma lista paginada de CEPs com base nos filtros fornecidos.

- O resultado da consulta é paginado com limite de 200 itens por pagina.
- Limite global de 2.000 itens.
- Cada consulta consome 2 créditos.
- Disponível somente nos planos pagos.

URL base: `https://api.nextapi.com.br`. Autenticação: cabeçalho `Authorization: Bearer SEU_TOKEN`.

## Exemplo de requisição

```bash
curl --request GET 'https://api.nextapi.com.br/v1/ceps' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Accept: application/json'
```

## Parâmetros

| Nome | Local | Obrigatório | Tipo / regras | Descrição |
| --- | --- | --- | --- | --- |
| `uf` | query | Não | `string` | Sigla do estado (ex: SP, RJ) |
| `idMunicipio` | query | Não | `integer (int32)` | Código do município |
| `nomeMunicipio` | query | Não | `string` | Nome do município para filtro (busca parcial) |
| `logradouro` | query | Não | `string` | Nome do logradouro para filtro (busca parcial) |
| `q` | query | Não | `string` | Busca global, realiza busca por palavra/texto nos campos cep, logradouro, localidade, nomeMunicipio e uf |
| `page` | query | Não | `integer (int32)` | Número da página (padrão: 1) |
| `pageSize` | query | Não | `integer (int32)` | Quantidade de itens por página (máx: 200) |

## Respostas HTTP

| Status | Descrição | Formato JSON |
| --- | --- | --- |
| `200` | Operação realizada com sucesso | CepItemResponsePagedResult |
| `400` | Erro nos parametros informados na requisição | IErrorCodeModel |
| `405` | Falta de créditos para realizar a consulta | IErrorCodeModel |
| `500` | Erro ao processar a requisição | objeto |

Autenticação e limites também podem gerar erros antes da execução da operação. Veja o [guia de tratamento de erros](https://www.nextapi.com.br/docs/erros.md).

## Resposta de sucesso

Exemplo estrutural gerado do schema: os valores são ilustrativos. Campos anuláveis podem retornar `null`.

```json
{
  "page": 0,
  "pageSize": 0,
  "total": 0,
  "items": [
    {
      "cep": "string",
      "logradouro": "string",
      "localidade": "string",
      "idMunicipio": 0,
      "nomeMunicipio": "string",
      "uf": "string",
      "latitude": 0,
      "longitude": 0,
      "dataAtualizacao": "2026-01-01T00:00:00",
      "codigoIbge": {
        "municipio": 0,
        "estado": 0,
        "pais": 0
      }
    }
  ]
}
```

## Campos da resposta

Modelo: `CepItemResponsePagedResult`

### CepItemResponsePagedResult

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `page` | `integer (int32)` | Não marcado no contrato | — |
| `pageSize` | `integer (int32)` | Não marcado no contrato | — |
| `total` | `integer (int64)` | Não marcado no contrato | — |
| `items` | `CepItemResponse[]` | Não marcado no contrato | — |

### CepItemResponse

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `cep` | `string \| null` | Sim | — |
| `logradouro` | `string \| null` | Não marcado no contrato | — |
| `localidade` | `string \| null` | Não marcado no contrato | — |
| `idMunicipio` | `integer (int32) \| null` | Não marcado no contrato | — |
| `nomeMunicipio` | `string \| null` | Não marcado no contrato | — |
| `uf` | `string \| null` | Não marcado no contrato | — |
| `latitude` | `number (double) \| null` | Não marcado no contrato | — |
| `longitude` | `number (double) \| null` | Não marcado no contrato | — |
| `dataAtualizacao` | `string (date-time) \| null` | Não marcado no contrato | — |
| `codigoIbge` | `CepCodigoIbgeResponse` | Não marcado no contrato | — |

### CepCodigoIbgeResponse

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `municipio` | `integer (int32) \| null` | Não marcado no contrato | — |
| `estado` | `integer (int32) \| null` | Não marcado no contrato | — |
| `pais` | `integer (int32) \| null` | Não marcado no contrato | — |