Address Analyzer

Examples

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"
}