A Portuguese address puts three numbers on the street line: the number of the building, the floor inside it, and which door on that floor. The last two look like a single afterthought written as 2.º Dto, and they are the part most often lost, because most address models have nowhere to put them.
This article describes the Portuguese address format, how CDQ represents it in the CDQ address model, how the floor and the side of the door are delivered, and which reference data CDQ maintains for Portugal. It is the reference for anyone mapping Portuguese business partner data into CDQ, or consuming curated Portuguese addresses from CDQ.
In this article, you will understand:
- How a Portuguese address is structured, and what the part after the house number means
- Why none of the three administrative levels appears on a Portuguese address, and what still needs them
- How each Portuguese level maps to a concept in the CDQ address model, and which SAP field it reaches
- Why the floor and the side of the door go to two different output fields, and which one is the house number supplement
- Which reference data CDQ maintains for Portugal, and what the published values look like
- Where the current CDQ coverage for Portugal is incomplete
Available in:
- CDQ Wiki: business partner metadata for Portugal: browse the published Portuguese metadata
A Portuguese address has the ordinary European shape: a street, a number, a post code and a place. Most of it needs no special handling.
What is specific to Portugal is narrower, and it is where integrations actually go wrong:
| Specific to Portugal | Why it matters |
|---|---|
| The position inside the building is written on the street line | 2.º Dto is a floor and a door, and it arrives inside the street value where it corrupts every comparison on that field |
| The post code has a three digit extension precise to one building | it is far more specific than a normal postal code, and the seven digits are one value rather than two |
| The building number follows a comma | and street names frequently contain numbers, so the first number on the line is often part of the name |
| The postal locality is not always the municipality | a Portuguese city field can hold a village that appears in no municipality list |
| None of the three administrative levels appears on an address | a Portuguese address without a district is complete as an address |
Portugal has three administrative levels below the country and one postal level. None of the administrative ones is used to deliver mail.
| Level | Portuguese | What it is | Used to address mail | Example |
|---|---|---|---|---|
| 1 | distrito | district, 18 on the mainland, with the Azores and Madeira as autonomous regions at the same level | no | Lisboa |
| 2 | concelho or município | municipality, 308 of them | no | Lisboa |
| 3 | freguesia | civil parish, the smallest administrative unit | no | Santa Maria Maior |
| postal | localidade | the postal locality, which is what the post code is issued against | yes | LISBOA |
The district and the municipality frequently share a name, as Lisboa and Porto do, so a name on its own does not say which level it belongs to.
The three administrative levels are still business data: the municipality is what a Portuguese company is registered in, and the district is the level an SAP region field is usually keyed on and the level reporting is cut by.
Empresa Exemplo, Lda.
Rua Augusta, 123, 2.º Dto
1100-053 LISBOAThe street type comes first, then the name, then a comma and the building number, then the floor and the door. The post code precedes the postal locality on the last line.
2.º Dto is not a suffix on the house number. It is two separate facts:
| Written | Portuguese | Means |
|---|---|---|
2.º | segundo andar | second floor |
R/C | rés-do-chão | ground floor |
Cv | cave | basement |
Sob. | sobreloja | mezzanine |
Dto | direito | the right-hand door on that floor |
Esq | esquerdo | the left-hand door |
Frt | frente | the front door |
Tras | trás | the rear door |
So Rua Augusta, 123, 2.º Dto reads: number 123 on Rua Augusta, second floor, right-hand door. Where a building has more than two doors per floor, letters are used instead: 2.º A, 2.º B.
Direito and Esquerdo describe which door you knock on. Left in the street field they turn Rua Augusta into Rua Augusta 2 Dto, which matches nothing, and two flats in the same building become two different streets. They are premises and belong in premises fields.
Since 1998 a Portuguese post code has been four digits, a hyphen and three more: 1100-053. The first four identify a postal area. The three digit extension identifies a single street, a section of a long street, one building, or one high volume recipient.
| Form | Example | Status |
|---|---|---|
| Four digits and a three digit extension | 1100-053 | the current format |
| Four digits only | 1100 | the pre-1998 format, still present in older master data |
An extension of -000 is used where no more precise code exists. A four digit code is not wrong, it is old, and it cannot be completed without the street.
Both forms are validated and neither is rewritten, so a seven digit value arriving without its hyphen is carried as supplied and a four digit code is not completed. Post code normalisation is currently available for Canada and Mexico.
The building number follows a comma, and the comma matters. Rua Augusta, 123 separates the name from the number. Without it, Rua Augusta 123 is still readable, but Avenida 5 de Outubro, 12 without the comma is not: the 5 belongs to the street name and the 12 to the building.
Numbers in street names are common. Avenida 24 de Julho, Rua 5 de Outubro, Praça 8 de Maio. A parser that takes the first number it sees as the house number will take the date.
Lote and Bloco are not house numbers. In a planned development the address can be Lote 12, Bloco B, where the plot number replaces the street number and the block letter identifies one building of several.
Urbanização, Bairro and Quinta name an area, not a street. They frequently appear on the line above the street and identify the development the street sits in.
A freguesia name repeats across the country. Santo António, São Pedro and Santa Maria occur in dozens of municipalities. A parish name is only meaningful with its municipality.
The name on the post code line is the postal locality, which for a small place is the name of the village rather than the municipality it belongs to. A Portuguese city field can therefore hold a place that appears in no municipality list.
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.
Portugal maps as follows:
| Portuguese level | CDQ concept | Type | SAP field |
|---|---|---|---|
| distrito | administrative area, level 1 | REGION | region |
| concelho | administrative area, level 2 | COUNTY | county |
| localidade | locality, level 1 | CITY | city |
| freguesia | locality, level 2 | DISTRICT | district |
| urbanização, bairro, quinta | locality | QUARTER | district |
| zona industrial | thoroughfare | INDUSTRIAL_ZONE | appended to district |
| street type and name | thoroughfare | STREET | street |
| building number, or the lote | thoroughfare number | n/a | house number, HOUSE_NUM1 |
| andar, the floor | premise | LEVEL | floor |
| Dto, Esq, Frt, Tras, or the door letter | premise | DOOR | house number supplement, HOUSE_NUM2 |
| bloco | premise | BUILDING | building |
| apartamento | premise | APARTMENT | house number supplement, HOUSE_NUM2 |
| Apartado | postal delivery point | POST_OFFICE_BOX | PO box |
| código postal | post code | REGULAR | post code |
This is the decision that makes a Portuguese address survive an SAP load.
SAP reserves a second house number field, HOUSE_NUM2, for the Iberian and Latin American convention of a supplement to the house number. Portugal is one of the five countries for which CDQ fills it. What goes in there is the door: the side, or the letter, or the apartment. The floor goes to the dedicated floor field, because SAP has one and because the floor is a different fact from the door.
So 123, 2.º Dto is delivered as:
| Output field | Value |
|---|---|
house number, HOUSE_NUM1 | 123 |
| floor | 2.º |
house number supplement, HOUSE_NUM2 | Dto |
Three separate facts in three separate fields, each of which can be compared, and none of which has to be parsed back out of a string.
123 2.º Dto answers two different questions in one field: which building on the street, and which unit inside that building. Splitting them is what makes either question answerable on its own.
Keeping them together fails in both directions at once. An exact comparison on street and number stops recognising that a partner at 123 2.º Dto and a partner at 123 3.º Esq are in the same building, which is what site consolidation and hierarchy detection look for. A fuzzy comparison has the opposite problem: most of the characters in those two values agree, so it reads them as near identical and can treat two different flats as one partner. The combined value is too different for the first check and too similar for the second.
Multi-tenant buildings are also where the question gets asked in the first place, because that is where several business partners share one street and one number.
| Rejected alternative | Why |
|---|---|
Treat Dto and Esq as part of the street name | It is where they arrive, and it is the thing that has to be corrected. A street is a line on the ground shared by every building on it; a door side is a property of one flat. |
| Put the floor in the house number supplement together with the door | The supplement is one field, and packing two facts into it recreates the problem it exists to solve. SAP has a floor field, and it takes the floor. |
| Split the post code into the four digit area and the three digit extension | The seven digits are one post code, written with a hyphen. Separating them invites a partial write in which an extension outlives the area code it belonged to, producing a code that was never issued. |
CDQ delivers the district with its ISO 3166-2 code. 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 it follows national tax or statistical numbering rather than ISO, and 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: a T005S is specific to a customer and to a client, and no single value would be correct everywhere. What this standard fixes is the ISO 3166-2 code. The mapping from it to the key your system expects is yours to maintain.
For Portugal the key your configuration holds is conventionally the district number, which is the numeric part of the ISO code you receive, so the mapping is a transformation rather than a lookup.
Treat the ISO code as the value CDQ guarantees and the SAP key as a mapping you own.
Rua Augusta, 123, 2.º Dto, 1100-053 Lisboa, in the CDQ address model:
| Field | Value |
|---|---|
| Country | PT |
Administrative area 1 (REGION) | Lisboa |
| Administrative area 1 short name | 11 |
Administrative area 2 (COUNTY) | Lisboa |
Locality 1 (CITY) | Lisboa |
Locality 2 (DISTRICT) | Santa Maria Maior |
Thoroughfare (STREET) | Rua Augusta |
| Thoroughfare number | 123 |
Premise (LEVEL) | 2.º |
Premise (DOOR) | Dto |
| Post code | 1100-053 |
The examples below show the shape of each dataset, not its full contents. The complete published lists for Portugal are on the CDQ Wiki page business partner metadata for Portugal, which also covers legal forms, identifier types and the integrated data sources.
20 entries: the 18 mainland districts, the Azores and Madeira. Each carries its ISO 3166-2 code and names in Portuguese, with English, French, German and Chinese where these exist.
| Code | Portuguese | English | Also matched as |
|---|---|---|---|
PT-11 | Distrito de Lisboa | Lisbon District | Lisboa, Lisbon |
PT-13 | Distrito do Porto | Porto District | PORTO |
PT-15 | Distrito de Setúbal | Setúbal District | SETÚBAL, Setubal |
PT-20 | Açores | Azores | not published |
PT-30 | Madeira | Madeira | Madeira Island |
Districts whose name carries a diacritic are also matched without it, so Evora resolves to Évora and Braganca to Bragança.
38 entries, covering the Portuguese street vocabulary with the official abbreviation.
| Term | Abbreviation | What it is |
|---|---|---|
| Rua | R. | street |
| Avenida | AV | avenue |
| Praça | PC | square |
| Largo | LG | a small square |
| Travessa | TV | a cross street |
| Beco | BC | an alley |
| Estrada | ESTR | a road |
| Caminho | CAM | a lane |
| Calçada | CC | a paved climbing street |
| Alameda | AL | a tree-lined avenue |
| Rotunda | ROT | a roundabout |
| Praceta | PCT | a small square off a street |
| Urbanização | URB | a development |
| Loteamento | LOTEAM | a subdivision |
| Bairro | BR | a neighbourhood |
| Apartado | none | 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.
Four digits, a hyphen, three digits. The four digit form is recognised as the superseded format. A country prefix is removed, so PT-1100-053 resolves to 1100-053.
The district is standardised against reference data: whether it arrives with or without the word Distrito, with or without its diacritics, the canonical name and the ISO code are written back.
Street terms are recognised in the street text and rewritten to the official abbreviation, so Avenida and AV produce the same delivered value.
Post codes have their country prefix removed and are validated against the seven digit format, with the four digit form recognised as superseded.
The municipality, the parish and the locality are preserved as submitted. Where an address provider is enabled, it can enrich and complete them.
These are the gaps worth knowing about before designing an integration.
| Limitation | What it means for an integration |
|---|---|
| The Portuguese premises vocabulary is not yet published | The floor and the door are the part of a Portuguese address that most needs recognising, and the Portuguese words for them are not yet maintained as reference data. Until they are, a floor and a door arriving inside the street value stay there: they are never discarded, but the floor field and the house number supplement can be empty for an address that clearly has both. This is the single most important thing to know before loading Portuguese addresses. |
| The street vocabulary covers the common forms and not yet all of them | Where a Portuguese street type is published, the street is delivered expanded in the thoroughfare value and abbreviated in the short name, and the short name is what the SAP street line takes. Where the type is not yet published, the street is preserved exactly as submitted and no short name is produced. |
| The district is standardised, and not derived | A district that arrives is matched against reference data and completed. One that is absent stays absent, because CDQ standardises a supplied value rather than deriving one from the post code. Since the district is not part of a Portuguese postal address, absent is the normal case, and deriving it needs a published post code to locality table. |
Until the Portuguese premises vocabulary is published, the position inside the building generally arrives in the street value and stays there. Before an SAP load, check the street values of your Portuguese records for a trailing floor and door, and expect the floor field and the house number supplement to be empty. Where your source already holds the floor and the door in their own fields, supply them that way and they will reach the right output fields.
A Portuguese address writes the street type first, the building number after a comma, and then the floor and the side of the door. Those last two are separate facts, and the post code that follows carries a three digit extension precise enough to identify one building.
None of Portugal's three administrative levels is written on an address. The district, the municipality and the parish are carried because a company is registered in a municipality, because an SAP region field is usually keyed on the district, and because reporting is cut by both.
CDQ places the district in administrative area level 1 and the municipality in level 2, the postal locality in locality level 1 and the parish in level 2. The building number goes to the house number, the floor to the floor field, and the side of the door to the house number supplement, which is the field SAP reserves for exactly this in Portugal. The post code stays one value.
The twenty districts and the Portuguese street vocabulary are maintained as CDQ reference data. The premises vocabulary is where the current coverage is weakest, and it is the part a Portuguese address depends on most: until the floor and door words are published, both usually arrive inside the street value and stay there. Municipalities and parishes are preserved as submitted.
- Business partner metadata for Portugal
- France Address Standard
- Germany 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!