Parameter list

• Address input formats
• Required parameters
• Optional parameters
• Request examples

Address input formats

The address can be sent in two ways:

• Label – A single text with the address components separated by commas, in the order road, number, district, zipcode, city, state;
• Structured – Each address component sent in a separate parameter.

Both formats can be sent in the same request. In that case, the structured parameters take precedence and the label is ignored:

Required parameters

The required parameters depend on the address input format.

Structured format

• road – Text with the street name. It may contain the number and the complement, which are split in the response. Limit of 150 characters;
• zipcode – Text with the address ZIP code (CEP). Accepts the ZIP code with or without a hyphen (example: 01310-200 or 01310200). After the hyphen is removed, it must contain exactly 8 digits;
• city – Text with the city name.

Label format

• label – Text with the full address, with the components separated by commas in the order road, number, district, zipcode, city, state. The street, ZIP code and city must be filled in the label.
  • All five separating commas must be present, even when a component is empty. Example: "av paulista,1578,,01310200,sao paulo,";
  • If any comma is missing, the error Structure error on label field is returned. This validation runs before the ZIP code format validation.

Note: requests without road, zipcode or city are rejected with a 400 error.

Optional parameters

• number – Text with the building number. It may be sent empty or contain a complement after the number (example: "654 bloco 3"); in that case, the text after the number is returned in complement. If not sent, the number is identified in road;
• district – Text with the district (neighborhood) name;
• state – Text with the state abbreviation (UF).

Request examples

Example with the label format

{
  "label": "r da cantarera 306 box 12,,centro,01024-000,sao paulo,SP"
}

Example with the structured format

{
  "road": "r da cantarera 306 box 12",
  "number": "",
  "zipcode": "01024-000",
  "district": "centro",
  "city": "sao paulo",
  "state": "SP"
}

Example with label and structured parameters

In this case, only the structured parameters are used:

{
  "label": "r da cantarera 306 box 12,,centro,01024-000,sao paulo,SP",
  "road": "r da cantarera 306 box 12",
  "number": "",
  "zipcode": "01024-000",
  "district": "centro",
  "city": "sao paulo",
  "state": "SP"
}