# ViaCEP

> Look up Brazilian addresses by CEP (postal code), and find the CEPs of a street by state, city and street name.

App · 2 actions. Web page: https://docs.lodol.com/docs/integrations/viacep

## Actions

### Find CEPs by address

Find the CEPs of a street from its state, city and name. Returns up to 50 matches, closest names first; a long street can have one CEP per stretch.

**Inputs**

- State (`state`, text, required): The state the city is in. One of: `AC` (AC - Acre), `AL` (AL - Alagoas), `AP` (AP - Amapá), `AM` (AM - Amazonas), `BA` (BA - Bahia), `CE` (CE - Ceará), `DF` (DF - Distrito Federal), `ES` (ES - Espírito Santo), `GO` (GO - Goiás), `MA` (MA - Maranhão), and 17 more.
- City (`city`, text, required): The city's name, at least 3 characters, such as São Paulo. Accents are optional.
- Street (`street`, text, required): All or part of the street's name, at least 3 characters, such as Paulista. Leave out the type (Rua, Avenida).

**Outputs**

- `count` (number): How many addresses matched.
- `may_be_truncated` (true/false): True when 50 came back, ViaCEP's limit, so there may be more. Narrow the street name to find them.
- `results` (list): Matching addresses, each with its CEP.

**Example output**

```json
{
  "count": 2,
  "may_be_truncated": false,
  "results": [
    {
      "cep": "01001-000",
      "city": "S\u00e3o Paulo",
      "complement": "lado \u00edmpar",
      "ddd": "11",
      "gia_code": "1004",
      "ibge_code": "3550308",
      "neighborhood": "S\u00e9",
      "region": "Sudeste",
      "siafi_code": "7107",
      "state": "SP",
      "state_name": "S\u00e3o Paulo",
      "street": "Pra\u00e7a da S\u00e9",
      "unit": null
    },
    {
      "cep": "01001-901",
      "city": "S\u00e3o Paulo",
      "complement": "371",
      "ddd": "11",
      "gia_code": "1004",
      "ibge_code": "3550308",
      "neighborhood": "S\u00e9",
      "region": "Sudeste",
      "siafi_code": "7107",
      "state": "SP",
      "state_name": "S\u00e3o Paulo",
      "street": "Pra\u00e7a da S\u00e9",
      "unit": "Edif\u00edcio Santa L\u00eddia"
    }
  ]
}
```

### Look up an address by CEP

Get the street, neighborhood, city and state of a CEP (Brazilian postal code), with the city's IBGE code and DDD (phone area code).

**Inputs**

- CEP (`cep`, text, required): The 8-digit postal code, with or without the hyphen, such as 01001-000.

**Outputs**

- `cep` (text): The CEP (postal code), as 01001-000.
- `city` (text): City (localidade).
- `complement` (text): Which part of the street the CEP covers, such as lado ímpar (odd-numbered side).
- `ddd` (text): The city's DDD (phone area code).
- `gia_code` (text): São Paulo state's GIA tax code, for SP addresses.
- `ibge_code` (text): The city's 7-digit IBGE code.
- `neighborhood` (text): Neighborhood (bairro).
- `region` (text): Region of Brazil, such as Sudeste.
- `siafi_code` (text): The city's SIAFI code, used in federal finance systems.
- `state` (text): Two-letter state code (UF), such as SP.
- `state_name` (text): State name.
- `street` (text): Street name (logradouro). Empty for a CEP that covers a whole town.
- `unit` (text): The building or organisation, for a CEP of its own.

**Example output**

```json
{
  "cep": "01001-000",
  "city": "S\u00e3o Paulo",
  "complement": "lado \u00edmpar",
  "ddd": "11",
  "gia_code": "1004",
  "ibge_code": "3550308",
  "neighborhood": "S\u00e9",
  "region": "Sudeste",
  "siafi_code": "7107",
  "state": "SP",
  "state_name": "S\u00e3o Paulo",
  "street": "Pra\u00e7a da S\u00e9",
  "unit": null
}
```