Brazil Address Standard

A Brazilian address carries two things most address models treat as optional: the neighbourhood, the bairro, and the two-letter abbreviation of the state, the UF. Both are part of the postal address. Between the house number and the bairro sits the complemento, the floor, room, suite or apartment inside the building, written as free text on the same line as the street.

This article describes the Brazilian address format, how CDQ represents it in the CDQ address model, how the complemento is delivered, and which reference data CDQ maintains for Brazil. It is the reference for anyone mapping Brazilian business partner data into CDQ, or consuming curated Brazilian addresses from CDQ.

In this article, you will understand:

• How a Brazilian address is structured, and which of its parts the post office actually uses
• Why the bairro and the state abbreviation belong in the address, and where each goes
• How each Brazilian level maps to a concept in the CDQ address model, and which SAP field it reaches
• How the complemento splits into floor, room and apartment, and which one is the house number supplement
• Which reference data CDQ maintains for Brazil, and what the published values look like
• Where the current CDQ coverage for Brazil is incomplete

Available in:

• CDQ Wiki: business partner metadata for Brazil: browse the published Brazilian metadata

A Brazilian address has a familiar shape: a street type and name, a number, a post code and a city. What is specific to Brazil is where integrations go wrong:

Brazil has two administrative levels below the country that appear on an address, and one sub-municipal level that the post office relies on.

A municipality in Brazil is the city: there is no county or province between the state and the municipality, so a Brazilian address has no level 2 administrative area beyond the city itself.

The Federal District is a single municipality, Brasília. Its administrative regions take the place of bairros: where a region is not divided into bairros, the region is written as the bairro, and where it is, the bairro is followed by the region in brackets, as in Veredas (Brazlândia).

Empresa Exemplo Ltda.
Avenida Paulista, 1000, 12º andar, sala 1203
Bela Vista
01310-100 São Paulo / SP

The street type comes first, then the name, a comma and the number, then the complemento. The bairro has its own line. The last line holds the CEP, the city and the state abbreviation; the post office also accepts the CEP alone on the last line below São Paulo / SP.

The complemento identifies the unit inside the building. It is free text with a common vocabulary:

So Avenida Paulista, 1000, 12º andar, sala 1203 reads: number 1000 on Avenida Paulista, twelfth floor, room 1203.

Some forms are easy to misread:

The CEP has eight digits written as five, a hyphen and three: 01310-100. It was five digits until 1992, when the three-digit suffix was added. The first five digits identify the region, sub-region, sector and subsector. The suffix identifies a street, a side or section of a long street, or a single recipient. Suffixes from 900 to 999 are reserved for special cases, such as post office boxes and large recipients.

A five-digit CEP is not wrong, it is old, and it cannot be completed without the street.

The bairro has no obvious field. Systems built on a street, city and post code shape put the bairro in the second street line, in the city, or nowhere. A bairro in the city field makes the city unmatched against any municipality list.

The state arrives as an abbreviation, a name, or both. SP, São Paulo, Sao Paulo and São Paulo - SP all mean the same state. Since the city and the state of São Paulo and Rio de Janeiro share a name, a name on its own does not say which level it belongs to.

Numbers in street names are common. Rua 25 de Março, Avenida 9 de Julho, Rua XV de Novembro. A parser that takes the first number it sees as the house number will take the date.

Rodovia addresses carry two numbers that are not a house number. In Rodovia SP-330, km 98, the road code and the kilometre mark both look like numbers. Neither is a CEP.

Quadra, bloco and lote replace the street in planned areas. In Brasília and in many developments the address is a sequence of sector, quadra, bloco or conjunto, and lote. These locate a building rather than name a street.

The CDQ address model has two parallel hierarchies. Administrative areas represent the political containers, typed REGION and COUNTY. Localities represent the places themselves, typed CITY, DISTRICT, QUARTER or BLOCK. Streets are held as thoroughfares with the number in its own field, and the position inside the building as typed premises.

Brazil maps as follows:

SAP reserves a second house number field, HOUSE_NUM2, for the Iberian and Latin American supplement to the house number. Brazil is one of the five countries for which CDQ fills it. What goes there is the unit: the room, the suite or the apartment. The floor goes to the dedicated floor field, and the bloco to the building field.

This is why a sala or a conjunto is modelled as a room rather than as a suite. In an SAP system with the Brazilian localization, HOUSE_NUM2 is the master-data field the electronic invoice, the NF-e, takes its complemento from. A unit delivered anywhere else does not appear on the invoice. HOUSE_NUM2 holds ten characters, so the unit fits and the whole complemento usually does not, which is a second reason to keep the floor in its own field.

The delivery to SAP is a fixed selection from the typed premises of the address:

So 1000, 12º andar, sala 1203 is delivered as:

A room, suite or apartment is delivered twice: it reaches HOUSE_NUM2 and, because ROOM_NUMBER takes the first of room, door and apartment, ROOM_NUMBER as well. A customer reviewing an SAP load for duplicated content will see the unit in both fields for Brazil, and should read HOUSE_NUM2 as the authoritative one.

CDQ delivers the state with its ISO 3166-2 code, for example BR-SP. An SAP system does not validate against ISO: it validates the region field against its own region key table, T005S, which is part of a customer's configuration. That key exists for tax and jurisdiction purposes, which is why the level it sits at differs from one country to the next.

The region key is customer-specific configuration, so this standard does not define one. What this standard fixes is the ISO 3166-2 code. For Brazil the key your configuration holds is conventionally the two-letter abbreviation, which is the part of the ISO code after BR-, so the mapping is a transformation rather than a lookup. CDQ also carries a default SAP key for all 27 states, and it is that same abbreviation.

Treat the ISO code as the value CDQ guarantees and the SAP key as a mapping you own.

Avenida Paulista, 1000, 12º andar, sala 1203, Bela Vista, 01310-100 São Paulo / SP, in the CDQ address model:

27 entries: the 26 states and the Federal District. Each carries its ISO 3166-2 code, the two-letter abbreviation as its default SAP key, and names in Portuguese, with English, French, German and Chinese where these exist.

A state is resolved from its name or from its two-letter abbreviation, with or without the BR- prefix, so SP, BR-SP and São Paulo all resolve to BR-SP. Most states whose name carries a diacritic are also matched without it, so Sao Paulo resolves to São Paulo and Goias to Goiás.

Fernando de Noronha is a district of Pernambuco (BR-PE) and has no code of its own. The Manaus Free Trade Zone is a customs and tax regime, not a territory: a company in it has an ordinary Amazonas address with the region BR-AM.

56 entries, covering the Portuguese street vocabulary with its abbreviation, English equivalents, and the post office box.

Where a term is recognised, the expanded form is written to the thoroughfare value and the abbreviated form to the thoroughfare short name, and the short name is what the SAP street line takes.

Eight digits, with an optional hyphen after the fifth: both 01310-100 and 01310100 are recognised as a regular CEP. The value is carried as supplied, so a CEP without its hyphen is not rewritten to the hyphenated form. A five-digit CEP is not recognised as a regular post code.

These are the gaps worth knowing about before designing an integration.

A Brazilian address writes the street type first, the number after a comma, and then the complemento: the floor and the room, suite or apartment. The bairro has its own line, and the last line carries the eight-digit CEP, the city and the two-letter state abbreviation.

The state and the municipality are the only administrative levels, and both are written on the address: the municipality as the city, the state as its abbreviation. The bairro is not administrative, and the post office still uses it.

CDQ places the state in administrative area level 1, the municipality in locality level 1 and the bairro in locality level 2. The number goes to the house number, the floor to the floor field, the bloco to the building field, and the room or apartment to the house number supplement, which is the field SAP reserves for this in Brazil. The CEP stays one value.

The 27 states and the Brazilian street vocabulary are maintained as CDQ reference data, and the state is resolved from its abbreviation as well as its name. The complemento vocabulary is where the current coverage is weakest: its words are not yet premise terms, so the floor and the unit usually arrive inside the street value and stay there, and a unit that is delivered reaches two SAP fields.

• Business partner metadata for Brazil
• Portugal Address Standard
• Spain Address Standard
• United States Address Standard

We are constantly working on providing an outstanding user experience with our products. Please share your opinion about this tutorial!