ViaCEP

https://viacep.com.br
Admin
ViaCEP is a free, high-performance webservice for querying Brazilian Postal Codes (CEP), offering...
Tokens:3,521
Snippets:17
Trust Score:8.5
Update:2 months ago
Show doc for...
Tokens:
Raw
### JSON Response Format

Source: https://viacep.com.br/

Example of a successful JSON response from the ViaCEP webservice.

```json

    {
      "cep": "01001-000",
      "logradouro": "Praça da Sé",
      "complemento": "lado ímpar",
      "unidade": "",
      "bairro": "Sé",
      "localidade": "São Paulo",
      "uf": "SP",
      "estado": "São Paulo",
      "regiao": "Sudeste",
      "ibge": "3550308",
      "gia": "1004",
      "ddd": "11",
      "siafi": "7107"
    }
            
```

--------------------------------

### XML Response Format

Source: https://viacep.com.br/

Example of a successful XML response from the ViaCEP webservice.

```xml

    <?xml version="1.0" encoding="UTF-8"?>
    <xmlcep>
        <cep>01001-000</cep>
        <logradouro>Praça da Sé</logradouro>
        <complemento>lado ímpar</complemento>
        <unidade></unidade>
        <bairro>Sé</bairro>
        <localidade>São Paulo</localidade>
        <uf>SP</uf>
        <estado>São Paulo</estado>
        <regiao>Sudeste</regiao>
        <ibge>3550308</ibge>
        <gia>1004</gia>
        <ddd>11</ddd>
        <siafi>7107</siafi>
    </xmlcep>
            
```

--------------------------------

### JSONP Response Format

Source: https://viacep.com.br/

Example of a successful JSONP response using a callback function.

```json

    callback_name({
      "cep": "01001-000",
      "logradouro": "Praça da Sé",
      "complemento": "lado ímpar",
      "unidade": "",
      "bairro": "Sé",
      "localidade": "São Paulo",
      "uf": "SP",
      "estado": "São Paulo",
      "regiao": "Sudeste",
      "ibge": "3550308",
      "gia": "1004",
      "ddd": "11",
      "siafi": "7107"
    });
            
```

--------------------------------

### GET /ws/{cep}/json/

Source: https://viacep.com.br/ws/01001000/json

Retrieves address information for a given CEP.

```APIDOC
## GET /ws/{cep}/json/

### Description
Retrieves address details for a specific Brazilian postal code (CEP).

### Method
GET

### Endpoint
/ws/{cep}/json/

### Parameters
#### Path Parameters
- **cep** (string) - Required - The 8-digit postal code (e.g., 01001000)

### Response
#### Success Response (200)
- **cep** (string) - The postal code
- **logradouro** (string) - Street name
- **complemento** (string) - Address complement
- **unidade** (string) - Unit
- **bairro** (string) - Neighborhood
- **localidade** (string) - City
- **uf** (string) - State abbreviation
- **estado** (string) - State name
- **regiao** (string) - Region
- **ibge** (string) - IBGE code
- **gia** (string) - GIA code
- **ddd** (string) - Area code
- **siafi** (string) - SIAFI code

### Response Example
{
  "cep": "01001-000",
  "logradouro": "Praça da Sé",
  "complemento": "lado ímpar",
  "unidade": "",
  "bairro": "Sé",
  "localidade": "São Paulo",
  "uf": "SP",
  "estado": "São Paulo",
  "regiao": "Sudeste",
  "ibge": "3550308",
  "gia": "1004",
  "ddd": "11",
  "siafi": "7107"
}
```

--------------------------------

### GET /ws/{uf}/{cidade}/{logradouro}/{format}/

Source: https://viacep.com.br/

Searches for CEPs based on state, city, and street name.

```APIDOC
## GET /ws/{uf}/{cidade}/{logradouro}/{format}/

### Description
Searches for CEPs matching the provided state, city, and street name. City and logradouro must contain at least three characters.

### Method
GET

### Endpoint
viacep.com.br/ws/{uf}/{cidade}/{logradouro}/{format}/

### Parameters
#### Path Parameters
- **uf** (string) - Required - State abbreviation.
- **cidade** (string) - Required - City name (min 3 characters).
- **logradouro** (string) - Required - Street name (min 3 characters).
- **format** (string) - Required - The desired response format (json or xml).

### Response
#### Success Response (200)
- Returns a list of up to 50 CEPs matching the criteria.

#### Error Response (400)
- Returned when city or logradouro parameters have fewer than three characters.
```

--------------------------------

### ViaCEP JSON Response Example

Source: https://viacep.com.br/ws/01001000/json

Represents the standard JSON object returned when querying a valid CEP.

```json
{
  "cep": "01001-000",
  "logradouro": "Praça da Sé",
  "complemento": "lado ímpar",
  "unidade": "",
  "bairro": "Sé",
  "localidade": "São Paulo",
  "uf": "SP",
  "estado": "São Paulo",
  "regiao": "Sudeste",
  "ibge": "3550308",
  "gia": "1004",
  "ddd": "11",
  "siafi": "7107"
}
```

--------------------------------

### ViaCEP XML Response Example

Source: https://viacep.com.br/ws/01001000/xml

Represents the standard XML structure for a CEP lookup result.

```xml
<xmlcep>
<cep>01001-000</cep>
<logradouro>Praça da Sé</logradouro>
<complemento>lado ímpar</complemento>
<unidade/>
<bairro>Sé</bairro>
<localidade>São Paulo</localidade>
<uf>SP</uf>
<estado>São Paulo</estado>
<regiao>Sudeste</regiao>
<ibge>3550308</ibge>
<gia>1004</gia>
<ddd>11</ddd>
<siafi>7107</siafi>
...
</xmlcep>
```

--------------------------------

### GET /ws/{cep}/{format}/

Source: https://viacep.com.br/

Retrieves address details for a specific 8-digit CEP.

```APIDOC
## GET /ws/{cep}/{format}/

### Description
Retrieves address information based on a valid 8-digit CEP. The response format can be specified as json or xml.

### Method
GET

### Endpoint
viacep.com.br/ws/{cep}/{format}/

### Parameters
#### Path Parameters
- **cep** (string) - Required - The 8-digit postal code.
- **format** (string) - Required - The desired response format (json or xml).

#### Query Parameters
- **callback** (string) - Optional - Used for JSONP requests to specify the callback function name.

### Response
#### Success Response (200)
- **cep** (string) - The postal code.
- **logradouro** (string) - Street name.
- **complemento** (string) - Address complement.
- **bairro** (string) - Neighborhood.
- **localidade** (string) - City.
- **uf** (string) - State abbreviation.
- **ibge** (string) - IBGE code.

#### Error Response (400)
- Returned when the CEP format is invalid (e.g., not 8 digits).
```

--------------------------------

### GET /ws/{cep}/xml/

Source: https://viacep.com.br/ws/01001000/xml

Retrieves address information for a specific CEP in XML format.

```APIDOC
## GET /ws/{cep}/xml/

### Description
Retrieves address details for a given Brazilian postal code (CEP) returned as an XML document.

### Method
GET

### Endpoint
/ws/{cep}/xml/

### Parameters
#### Path Parameters
- **cep** (string) - Required - The 8-digit postal code (e.g., 01001000)

### Response
#### Success Response (200)
- **cep** (string) - The postal code
- **logradouro** (string) - Street name
- **complemento** (string) - Address complement
- **bairro** (string) - Neighborhood
- **localidade** (string) - City
- **uf** (string) - State abbreviation
- **estado** (string) - State name
- **regiao** (string) - Region
- **ibge** (string) - IBGE code
- **gia** (string) - GIA code
- **ddd** (string) - Area code
- **siafi** (string) - SIAFI code

### Response Example
<xmlcep>
<cep>01001-000</cep>
<logradouro>Praça da Sé</logradouro>
<complemento>lado ímpar</complemento>
<unidade/>
<bairro>Sé</bairro>
<localidade>São Paulo</localidade>
<uf>SP</uf>
<estado>São Paulo</estado>
<regiao>Sudeste</regiao>
<ibge>3550308</ibge>
<gia>1004</gia>
<ddd>11</ddd>
<siafi>7107</siafi>
</xmlcep>
```

--------------------------------

### GET /ws/{cep}/json/?callback={callback_name}

Source: https://viacep.com.br/ws/01001000/json?callback=callback_name

Retrieves address details for a given CEP, returning the result wrapped in a specified JavaScript callback function.

```APIDOC
## GET /ws/{cep}/json/?callback={callback_name}

### Description
Retrieves address information for a specific Brazilian postal code (CEP) and returns the data as a JSON object wrapped in a callback function for JSONP support.

### Method
GET

### Endpoint
/ws/{cep}/json/?callback={callback_name}

### Parameters
#### Path Parameters
- **cep** (string) - Required - The 8-digit postal code (e.g., 01001000).

#### Query Parameters
- **callback** (string) - Required - The name of the JavaScript function to wrap the response.

### Response
#### Success Response (200)
- **cep** (string) - Postal code
- **logradouro** (string) - Street name
- **complemento** (string) - Address complement
- **unidade** (string) - Unit
- **bairro** (string) - Neighborhood
- **localidade** (string) - City
- **uf** (string) - State abbreviation
- **estado** (string) - State name
- **regiao** (string) - Region
- **ibge** (string) - IBGE code
- **gia** (string) - GIA code
- **ddd** (string) - Area code
- **siafi** (string) - SIAFI code

### Response Example
callback_name({
  "cep": "01001-000",
  "logradouro": "Praça da Sé",
  "complemento": "lado ímpar",
  "unidade": "",
  "bairro": "Sé",
  "localidade": "São Paulo",
  "uf": "SP",
  "estado": "São Paulo",
  "regiao": "Sudeste",
  "ibge": "3550308",
  "gia": "1004",
  "ddd": "11",
  "siafi": "7107"
});
```

--------------------------------

### ViaCEP Address JSON Response

Source: https://viacep.com.br/ws/RS/Porto%20Alegre/Domingos/json

Example of the JSON structure returned by the ViaCEP API containing address details like logradouro, bairro, and IBGE codes.

```json
    "logradouro": "Acesso Olavo Domingos de Oliveira",
    "complemento": "",
    "unidade": "",
    "bairro": "Jardim Carvalho",
    "localidade": "Porto Alegre",
    "uf": "RS",
    "estado": "Rio Grande do Sul",
    "regiao": "Sul",
    "ibge": "4314902",
    "gia": "",
    "ddd": "51",
    "siafi": "8801"
  },
  {
    "cep": "91740-650",
    "logradouro": "Praça Domingos Fernandes de Souza",
    "complemento": "",
    "unidade": "",
    "bairro": "Cavalhada",
    "localidade": "Porto Alegre",
    "uf": "RS",
    "estado": "Rio Grande do Sul",
    "regiao": "Sul",
    "ibge": "4314902",
    "gia": "",
    "ddd": "51",
    "siafi": "8801"
  }
]
```

--------------------------------

### JSONP Callback Response Format

Source: https://viacep.com.br/ws/01001000/json?callback=callback_name

The response wraps the address data in a function call specified by the callback_name parameter.

```json
callback_name({
  "cep": "01001-000",
  "logradouro": "Praça da Sé",
  "complemento": "lado ímpar",
  "unidade": "",
  "bairro": "Sé",
  "localidade": "São Paulo",
  "uf": "SP",
  "estado": "São Paulo",
  "regiao": "Sudeste",
  "ibge": "3550308",
  "gia": "1004",
  "ddd": "11",
  "siafi": "7107"
});
```

--------------------------------

### Retrieve Address Data for Domingos José

Source: https://viacep.com.br/ws/RS/Porto%20Alegre/Domingos%2BJos%C3%A9/json

A JSON array containing address details including CEP, neighborhood, and IBGE codes for specific streets in Porto Alegre.

```json
[
  {
    "cep": "91790-072",
    "logradouro": "Rua Domingos José Poli",
    "complemento": "",
    "unidade": "",
    "bairro": "Restinga",
    "localidade": "Porto Alegre",
    "uf": "RS",
    "estado": "Rio Grande do Sul",
    "regiao": "Sul",
    "ibge": "4314902",
    "gia": "",
    "ddd": "51",
    "siafi": "8801"
  },
  {
    "cep": "91910-420",
    "logradouro": "Rua José Domingos Varella",
    "complemento": "",
    "unidade": "",
    "bairro": "Cavalhada",
    "localidade": "Porto Alegre",
    "uf": "RS",
    "estado": "Rio Grande do Sul",
    "regiao": "Sul",
    "ibge": "4314902",
    "gia": "",
    "ddd": "51",
    "siafi": "8801"
  },
  {
    "cep": "90420-200",
    "logradouro": "Rua Domingos José de Almeida",
    "complemento": "",
    "unidade": "",
    "bairro": "Rio Branco",
    "localidade": "Porto Alegre",
    "uf": "RS",
    "estado": "Rio Grande do Sul",
    "regiao": "Sul",
    "ibge": "4314902",
    "gia": "",
    "ddd": "51",
    "siafi": "8801"
  }
]
```
Tokens:
Raw