Examples
- Example 1 – Address with a correction suggestion
- Example 2 – Address without a correction suggestion
- Example 3 – Address with several typing problems
- Example 4 – Complement sent in the number parameter
- Example 5 – Address without a number (s/n)
- Example 6 – City that does not match the ZIP code
- Example 7 – Non-existent ZIP code
Example 1 – Address with a correction suggestion
In this example, the address is sent in the label format, with an abbreviated street type, the ZIP code with a hyphen and the city without accents.
Request
{
"label": "av paulista 1578 museu,,bela vista,01310-200,sao paulo,SP"
}
Response
The response brings the suggested official spelling for the street, district and city, with the number and complement split. The returned status is CORRECTED.
{
"road": "Avenida Paulista",
"number": "1578",
"complement": "museu",
"district": "Bela Vista",
"zipcode": "01310200",
"city": "São Paulo",
"state": "SP",
"status": "CORRECTED",
"matchScore": 100.0,
"label": "Avenida Paulista, 1578, Bela Vista, 01310200, São Paulo, SP"
}
Example 2 – Address without a correction suggestion
In this example, the address is sent in the structured format and the street does not match the ZIP code provided.
Request
{
"road": "rua das acacias 45",
"number": "",
"zipcode": "01310200",
"district": "bela vista",
"city": "São Paulo",
"state": "SP"
}
Response
The number was split from the street, but there is no correction suggestion. The returned status is NORMALIZED.
{
"road": "rua das acacias",
"number": "45",
"complement": "",
"district": "bela vista",
"zipcode": "01310200",
"city": "São Paulo",
"state": "SP",
"status": "NORMALIZED",
"matchScore": 18.75,
"label": "rua das acacias, 45, bela vista, 01310200, São Paulo, SP"
}
Example 3 – Address with several typing problems
In this example, the address sent in the label format has the street type abbreviated with a period, a typo in the street name, the number attached to the “nº” marker, the complement separated by a hyphen, the ZIP code with a hyphen and the district and city without accents.
Request
{
"label": "R. da Cantarera nº306 - box 12,,centro,01024-000,sao paulo,SP"
}
Response
The API corrects the street name, splits the number and the complement and returns the official spelling of the district and city. The returned status is CORRECTED.
{
"road": "Rua da Cantareira",
"number": "306",
"complement": "box 12",
"district": "Centro",
"zipcode": "01024000",
"city": "São Paulo",
"state": "SP",
"status": "CORRECTED",
"matchScore": 94.74,
"label": "Rua da Cantareira, 306, Centro, 01024000, São Paulo, SP"
}
Example 4 – Complement sent in the number parameter
In this example, the address is sent in the structured format and the number parameter contains the number followed by the complement.
Request
{
"road": "av paulista",
"number": "1578 museu masp",
"zipcode": "01310200",
"district": "bela vista",
"city": "sao paulo",
"state": "SP"
}
Response
The text after the number is returned in complement, and number keeps only the number. The returned status is CORRECTED.
{
"road": "Avenida Paulista",
"number": "1578",
"complement": "museu masp",
"district": "Bela Vista",
"zipcode": "01310200",
"city": "São Paulo",
"state": "SP",
"status": "CORRECTED",
"matchScore": 100.0,
"label": "Avenida Paulista, 1578, Bela Vista, 01310200, São Paulo, SP"
}
Example 5 – Address without a number (s/n)
In this example, the address sent in the label format indicates that the property has no number (“s/n”) and includes a reference after the street.
Request
{
"label": "rua augusta s/n esquina com al santos,,consolacao,01305-000,sao paulo,SP"
}
Response
number is returned empty and the reference is returned in complement. The returned status is CORRECTED.
{
"road": "Rua Augusta",
"number": "",
"complement": "esquina com al santos",
"district": "Consolação",
"zipcode": "01305000",
"city": "São Paulo",
"state": "SP",
"status": "CORRECTED",
"matchScore": 100.0,
"label": "Rua Augusta, , Consolação, 01305000, São Paulo, SP"
}
Example 6 – City that does not match the ZIP code
In this example, the address is sent in the structured format with a São Paulo ZIP code, but with the city and state of Rio de Janeiro.
Request
{
"road": "av paulista 1578",
"number": "",
"zipcode": "01310-200",
"district": "bela vista",
"city": "rio de janeiro",
"state": "RJ"
}
Response
Since the city does not match the ZIP code provided, there is no correction suggestion: the address is only standardized, with the number split from the street. The returned status is NORMALIZED.
{
"road": "avenida paulista",
"number": "1578",
"complement": "",
"district": "bela vista",
"zipcode": "01310200",
"city": "rio de janeiro",
"state": "RJ",
"status": "NORMALIZED",
"matchScore": 0.0,
"label": "avenida paulista, 1578, bela vista, 01310200, rio de janeiro, RJ"
}
Example 7 – Non-existent ZIP code
In this example, the address is sent in the structured format with a ZIP code that does not exist.
Request
{
"road": "rua das flores 120 apto 32",
"number": "",
"zipcode": "99999-999",
"district": "centro",
"city": "sao paulo",
"state": "SP"
}
Response
Since the ZIP code was not found, there is no correction suggestion. The number and the complement are split from the street and the returned status is NORMALIZED.
{
"road": "rua das flores",
"number": "120",
"complement": "apto 32",
"district": "centro",
"zipcode": "99999999",
"city": "sao paulo",
"state": "SP",
"status": "NORMALIZED",
"matchScore": 0.0,
"label": "rua das flores, 120, centro, 99999999, sao paulo, SP"
}