Proposal:Multiple addresses

From OpenStreetMap Wiki
Jump to navigation Jump to search
housenumber plates (click image for description)
corner of a house, with a housenumber on each side
Multiple adresses
Proposal status: Obsoleted (inactive)
Proposed by: fkv
Tagging: addr:1:*=*
Applies to: nodearearelation
Definition: extend addr:* scheme to enable multiple adresses per object

Rendered as: similar to multiple address nodes
Draft started: 2012-08-11
RFC start: 2012-09-21


A house (or other object) can have multiple addresses. The only way to map these addresses in OSM is currently to assign them to multiple address nodes instead of the object itself. This is a pity because applications need to find out which address nodes belong to which buildings. Another problem is that there is no consense on where to place these address nodes. Some mappers prefer to place them inside the building, while others place them at the building's margin, possibly using entrance=* nodes.

This proposal aims to eliminate the need for separate address nodes. Another goal is to clarify what an address actually is. Additionally, a new tag for PO boxes is introduced, which has not been possible with the traditional addr:* scheme.

Meaning of addresses

As already mentioned, there is no consense on where to place address nodes. Discussions always came to dead ends, because people were discussing something that had not been properly defined. Talking of addresses, people have a lot of different things in mind. So what is an address in the first place?

According to Wikipedia, "an address is a collection of information, presented in a mostly fixed format, used for describing the location of a building, apartment, or other structure or a plot of land". Thus, the address is an attribute of the whole apartment, building or even the plot of land, not just the entrance. This proposal suggests to set addresses on those objects instead of their entrances or independant nodes. However, if an entrance is marked with a house number on-site, it's ok to set addr:housenumber on that entrance too (i.e. additionally). Similarly, you may set addr:unit on an entrance marked with a staircase number.

don't coerce applications

People who set addresses on entrances mostly do that for the looks and to enable door-to-door-routing. This proposal suggests to leave it over to the renderer where to display housenumbers. As to routing, it may be better to use another entrance to the same building, depending on where you come from. A renderer or router can easily find out all entrances to an area by examining all entrance nodes which are part of the delimiting line(s).

nested objects

If you set an address for a plot of land, that address implicitly applies to all subareas (e.g. buildings) and nodes within that area (unless overruled by tags on those objects). So you don't need to set the address on the building redundantly. Similarly, you don't need to set an address on a shop (or office etc.) node if the same address is already set on the building or plot of land. However, you may want to set the address on the shop node too, because many applications are not elaborate enough to combine the tags of the shop with the address of the surrounding object.


If an object has only one address, you can use the simple addr=* tags as usual.

If there are 2 or more addresses, insert "1:" after "addr:" for the first address, "2:" for the second address, and so on. If at least one addr:<count>:* tag exists, the simple addr:* tags (without the count-colon part) are default values for the individual addresses.

This proposal does not limit <count> to one-digit numbers, but applications interpreting only one-digit counts will rarely go wrong, as there are probably very few real-world objects with more than 9 addresses.



Let's say that this house has 4 addresses:

  1. Foo street 1
    12345 Grand City
  2. Bar Road 5
    12345 Grand City
  3. Baz Avenue 3
    12345 Grand City
  4. Qux Way 2
    12345 Grand City

The conventional approach would be to create 5 objects:

  • an area with building=yes
  • a node with addr:country=EL + addr:city=Grand City + addr:postcode=12345 + addr:street=Foo Street + addr:housenumber=1
  • a node with addr:country=EL + addr:city=Grand City + addr:postcode=12345 + addr:street=Bar Road + addr:housenumber=5
  • a node with addr:country=EL + addr:city=Grand City + addr:postcode=12345 + addr:street=Baz Avenue + addr:housenumber=3
  • a node with addr:country=EL + addr:city=Grand City + addr:postcode=12345 + addr:street=Qux Way + addr:housenumber=2

...totalling 5 objects with 21 tags.

The new approach is to create just one area with:

addr:city=Grand City
addr:1:street=Foo Street
addr:2:street=Bar Road
addr:3:street=Baz Avenue
addr:4:street=Qux Way

new tag for PO boxes

If a resident or office has a post office box, their mail is to be delivered to the respective post office. If you want to visit them in person, you may want to enter their postal address in your routing application and to get routed to their residence. Therefore, this proposal suggests a new tag addr:pob=*, or addr:<count>:pob=*. Let's append this to the above example:

house number (top) and conscription number (bottom)

conscription numbers

It has so far not been possible to tag both the old conscription number and the new housenumber on the same object. We might introduce a new key for conscription numbers, but this would break compatibility with the myriads of numbers already in the database. Furthermore it is not always clear whether a given number is a housenumber or a concription number. This proposal enables you to map housenumbers and conscription numbers independently even without a new conscription_number key.

Großwarasdorf (Ortstafel).jpg

multilingual addresses

addr:2:city=Veliki Borištof

Note that alternate names for single address parts (such as here and in the following examples) are a feature, but not the primary goal of this proposal. If there's a J F Kennedy Street in Großwarasdorf, you better fall back to semicolon notation for the street or the city, or omit alternate spellings. It is possible to extend the addr scheme later to cover this.

common spelling variations


common or obscure abbreviations

addr:1:street=John Fitzgerald Kennedy Street
addr:2:street=John F Kennedy Street
addr:3:street=J F Kennedy Street
addr:4:street=Kennedy Street


It's up to renderers how to handle multiple addresses on an object.

Sample Algorithms

rendering housenumbers inside

  1. get the nearest street by name for each address
  2. order them by importance (primary > residential) and/or closeness (0m > 100m)
  3. for the top priority address, determine the side of the object (building) closest to the relative street
  4. if there's enough space, display the housenumber there
  5. continue with (3) for the next address

rendering housenumbers and/or unit numbers on entrances

  1. if addr:housenumber is set on the entrance, display that number
  2. otherwise determine the address(es) of the innermost object the entrance is part of
  3. if that object has no address defined, repeat (2) with the next innermost object
  4. get the nearest street by name for each address with a housenumber
  5. of those streets, take the one which is closest to the entrance
  6. take the housenumber given in that address

Do the same for unit numbers. You may combine them with regard to local conventions, e.g. using a slash as a separator.

Sample Output

Housenum rend num+stc.svg
rendering housenumbers inside, and labelling entrances with their unit numbers
Housenum rend stc.svg
labelling entrances with housenumbers and unit numbers
Housenum rend bubble.svg
displaying the complete addresses on mouse over

Note that applications may make it configurable for the user, e.g. via a menu like this:
Housenr menu.svg

Sample Code

Sample perl code to resolve the address tags on an object from a hash %tags into an array @addresses:

my %addresses;
my %defaults;
for (keys %tags) {
  if (/^addr:(?:([\d]*):)?(.+)/) {
    my ($num,$subkey) = ($1,$2);
    if ($num) {
      $addresses{$num} ||= {};
      $addresses{$num}->{$subkey} = $tags{$_};
    } else {
      $defaults{$subkey} = $tags{$_};
my @addresses;
if (%addresses) {
  @addresses = map $addresses{$_}, sort keys %addresses;
  for my $key (keys %defaults) {
    for (@addresses) {
      $_->{$key} = $defaults{$key} unless exists $_->{key};
} elsif (%defaults) {
  @addresses = (\%defaults);


  1. leave it over to the renderer where to display housenumbers
  2. simplification: no address nodes, all relevant tags on the same object, no need for relations
  3. enable routing to POIs (shops, restaurants, etc.) with alternate addresses
  4. put an end to arguments on where to place address nodes
  5. enable mapping of housenumbers together with conscription numbers
  6. enable multilingual addresses


When you like to add an alternate name, would you create extra nodes just for the names? No! You set just a couple of tags on the very same object: name, alt_name, int_name, nat_name, reg_name, loc_name, old_name, official_name, short_name, sorting_name. As if this were not enough, there's also name:en, name:ru, name:de, name:hu... Hundreds of tags, all for names, never ever questioned. This proposal effectively adds 9 infixes 1..9 to the addr:* scheme. Judge yourself.


Applications should be aware of separate address nodes. However, their further creation is discouraged.

In order to make existing applications evaluate at least one of the addresses completely, you can set

addr:street=Foo Street

redundantly in addition to

addr:city=Grand City
addr:1:street=Foo Street
addr:2:street=Bar Road

but beware that this makes it less comprehensible to human readers, and redundancy is always problematic due to space and at later changes.

See also


not yet