Proposed features/House numbers/Karlsruhe Schema

This schema is used for tagging buildings with house-numbers (or full addresses). You can watch a quick video of how to use the simpler form in Potlatch to get you started.

It is one of several proposed schemes. Currently it is the most popular one. You may use or ignore it. This is how we do it.

The scheme is (as anything in OSM) subject to change after everyone has gathered experience with tagging house-numbers and interpreting the mapped data.

Basics

Houses are geolocated next to streets. As such they are related to a way for their postal address but contain their own geolocation independent of their street.

In OSM parlance:

• A house is, generally, represented by a node next to (not on!) the street. Or you can use a way describing the outline of the building tagged with building=*.
• Special ways may be introduced between houses to indicate that house number interpolation should take place (i.e., the system should assume that between house 10 and house 20 there are also 12, 14, 16, 18, or so).

Tags

The following tags are defined and in common use:

Tag	Presence	Element-type	Values	Description
addr:housenumber or addr:housename	required		string	The "house number". May contain non-digits. If a single entry has multiple house numbers, separate them by ",". E.g., "12b,12c". or The name of a house. This is sometimes used in some countries like UK and Ireland instead of a house number.
addr:street	optional		string	The (main) name of the related street. If not given a program may assume the name of the nearest street it can find, but this is not easy or fast to do in all cases, so putting the name in here is encouraged (somewhat faster. Best option is still the relation below.).
addr:state	optional		string	The state for those countries like the US and Australia that have state abbreviations in their addresses. For other countries this is not used.
addr:postcode	optional		string	Postal code of the building/addressed area. Different countries have different length and different characters allowed for postal codes.
addr:city	optional		string	City as used in postal addresses of the building/addressed area.
addr:country	optional		2-letter string	The ISO 3166-1 alpha-2 two letter country code in upper case (see wikipedia:ISO 3166-1 alpha-2). This might be needed because postal codes are only unique inside a country. Example: "DE" for Germany, "FR" for France, "IT" for Italy, Caveat: The ISO 3166-1 alpha-2 two letter code for Great Britain is "GB" and not "UK".
addr:full	optional		string	Full postal address. This can be used in addition to other tags if the other tags are not enough to fully describe an address.
addr:interpolation	required		even/odd/all/alphabetic	How to interpolate the house numbers belonging to the way along the related street. See below.

These tags work well in many countries. But other countries use very different ways of addressing that don't match these tags. Feel free to use other addr:* tags for other forms of postal addresses needed for your area. As long as you agree to the simple premise that buildings (or land parcels) have addresses you should be able to use this or an extended schema for your postal addresses.

Single house next to the way

<node id="1">
  <tag k="addr:housenumber" v="10" />
  <tag k="addr:street" v="AStreet" /> 
</node>

The location on the way is calculated by finding the nearest point on the nearest street. (See below for giving hints about what street is meant.)

We may also use a polygon for the house (building=yes). Where a single point is needed and no more suitable point can be determined (main entrance) the center of the bounding-box of the polygon can be used.

Using interpolation to mark many houses along a way

Parallel to the way representing the street we construct n nodes connected by their own way. This way has the sole use of describing the fact that house number interpolation should take place between the connected nodes (and what numbering scheme to use for interpolation).

<node id="01" lat=... lon=...>
  <tag k="addr:housenumber" v="10" /> 
  <tag k="addr:street" v="AStreet" /> 
</node>
<node id="02" lat=... lon=...>
  <tag k="addr:housenumber" v="20" /> 
  <tag k="addr:street" v="AStreet" /> 
</node>
<node id="03" lat=... lon=...>
  <tag k="addr:housenumber" v="100" /> 
  <tag k="addr:street" v="AStreet" /> 
</node>
<way id="??">
  <node ref="01"/>
  <node ref="02"/>
  <node ref="03"/>
  <tag k="addr:interpolation" v="even" />
  <!-- see note below on putting street names here! -->
</way>

We use linear interpolation along the way between any 2 consecutive nodes that represent an integer house number.

For missing house numbers (e.g., missing "12") two ways need to be drawn (e.g., "1-11" and "13-25").

If there is a house number on a single node or single building polygon and that house number also appears as the result of an interpolation, software should handle this case gracefully and favour the individually tagged house number as the real position. Such conflicts should sooner or later always be corrected in the data.

We expect this "interpolation way" to be a temporary construct. In the long run, OSM will have every single house mapped as a building outline, and every single house will be tagged with its house number, so that interpolation ways will gradually vanish. However they are good to make a quick start with house numbers, and reportedly there's existing data waiting to be imported that will also require interpolation.

Nodes that do not have an integer value for their addr:housenumber tag are ignored for odd/even/all interpolation (e.g., "12b"). Endpoints of interpolation ways of type "odd", "even", or "all" can not have house numbers containing non-integers.

Note: Some mappers use the "addr:street" tag on interpolation ways and leave it off the individual nodes. While of course everyone can tag what they like, this is not recommended by the inventors of the Karlsruhe Schema. The reason for this is that interpolation ways are supposed to be a temporary construct; we expect that once all individual houses have been mapped, the interpolation way can be simply removed without loss of information. They are not meant to stay.

Non-integral interpolation

You can use the interpolation method "alphabetic" to interpolate the alphabetical characters in the house number. So if you have all the houses from 7a to 7f in a row, you can connect them by a way tagged with addr:interpolation=alphabetic. You can not mix alphabetic interpolation with other interpolation methods. There is a special case for the Latin character set in which the first entry in the sequence is a number, followed by the number plus the letter A. For example, the range 25-25F means that the houses are numbered 25, 25A, 25B, …, 25F.

Giving hints about the full address (optional)

<node id="01" lat=... lon=...>
  <tag k="addr:housenumber" v="10" />
  <tag k="addr:postcode" v="832989" />
  <tag k="addr:full" v="First Street 10
                           832989 My Town
                           France" />
</node>

Giving hints about the road-access (optional)

<relation id="??">
  <tag k="type" v="roadAccess" />
  <member type="node" ref="11" role="accessto" />
  <member type="node" ref="12" role="accessvia" />
  <!-- (optionally multiple <member type="node" ref="11" role="accessvia" />
        for multiple access-locations to the adressed place; e.g., for
        convention-centers) -->
  <member type="way" ref="???" role="accessfrom" /> <!-- optional -->
</relation>

In other words: Create a relation of type "roadAccess" with these members:

• accessto = the address node tagged as shown above, at least with addr:housenumber=*. Since such address nodes mostly are notably far away from "their" street, they should additionally be tagged with addr:street=*.
• accessvia = a node (access node) on the street (trivial) or close to the street (e.g., gate). A routing algorithm should treat this node as start or end point of a route in the same way it would treat an address node without this relation. If more than one access node is given it should choose the best one (e.g., for a shortest or fastest route).
• accessfrom (optional) = a way (road, street, service street) which must be used to access this address.

Using relations to associate house and street (optional)

Instead of using the addr:street tag, it's also possible to use relations to provide a connection between housenumber and street. Those are more easy and less error-prone to evaluate in software. However, if you don't want to fiddle around with them, feel free to use the addr:street tag as described in the next section. Also, relations are much slower to parse by software if there is not enough memory to cache the whole dataset. Today, it seems a large majority of users simply stick with the addr:street tag.

According to Marcus Wolschon, one of both (addr:street or the relation associatedStreet) shall be enough. (See mail "Re: Hausnummernmapping & Relationen (Karlsruher Schema)" from 2009-04-15 09:18:48 GMT on German talk-de mailing list).

Tags

Members

Way/node	Role	Recurrence	Comment
	street	one or more	The associated street (more than one way possible if they are the same street, just have been split for mapping reasons)
	house	one or more	One or more house numbers (use "house" in tagging but in parsing also allow: "addr:houselink", address )

See Relations/Proposed/Street and Relations/Proposed/Collected_Ways!

Computers can easily add these relations where they are missing while pre-processing a bounding-box for searching.

Associating a node with a street

<node id="11" lat=... lon=...>
  <tag k="addr:housenumber" v="10" /> 
</node>
<relation id="??">
  <tag k="type" v="associatedStreet" /> 
  <member type="node" ref="11" role="house" />
  <member type="way" ref="???" role="street" />
</relation>

Hint: Computer programs that need to navigate house-numbers can create these relations internally from the first case as a step in pre-processing. Appropriate pre-processors will be provided.

Associating a building-polygon with a street

<relation id="??">
  <tag k="type" v="associatedStreet" /> 
  <member type="node" ref="11" role="house" />
  <member type="way" ref="???" role="street" />
</relation>

Associating a series of house-numbers with a street

<relation id="??">
  <tag k="type" v="associatedStreet" /> 
  <member type="way" ref="11" role="house" />
  <member type="way" ref="???" role="street" />
</relation>

Usage

• Some streets in Karlsruhe have their house-numbers tagged this way. Also some other places have such data.
• Traveling Salesman has a commandline-application org.openstreetmap.osm.data.searching.HouseNumberFinderTest to search for street+house-number and get a geolocation of the single house.
• Osmarender is patched to render the house-numbers very pretty: single houses, interpolation
• JOSM has a preset for easily setting addr:* tags
• Potlatch also has such a preset: click the 'preset type' icon until it becomes a postmark, then select 'address'
• The OSM Inspector has a view for showing addresses.
• mkgmap embeds provided addresses info into the POI info. The associatedStreet relation is not supported until now.
• LoroDux will use house numbers to guide blind persons to the right entrance. Please map entrances with house numbers very accurate!
• GpsMid since 0.7.5 has support for navigating to house numbers with associatedStreet relations and addr:street tags. Interpolation is not supported with version 0.7.5.

Algorithm

A possible implementation may work as follows:

1. Load the way into memory
2. Load all nodes and ways related to the way via "type=associatedStreet" -relation.
3. (If step 2 is not guaranteed to return all relevant results) load all nodes and ways with tag "addr:housenumber" or "addr:interpolation" in a bounding-box around the street that have this street as their nearest neigbour.1
4. If any nodes or building-polygons the the exact house-number are found in steps 2 and 3, return them and abort.
5. Iterate over all "addr:interpolation" of step 2 and 3 and determine either the first one or all that may contain the house-number to find.
6. Determine the segment span by 2 housenumbers A and B of the iterpolation-way that the asked for house-number X is between.
7. posNumeric = X / (B - A)
8. If the segment only consists of the nodes tagged A and B, your location is trivial to interpolate.
9. if the segment contains further nodes, determine the segment your location is in using the sum of the segment-lengthes and posNumeric.
10. Determine your location on the segment found by using the length of the segment and the sums of the segments before this segment.

alg1

A reference-implementation of this can be found in the AdvancedAddressDBPlaceFinder of the Traveling Salesman navigator.