Proposal:House numbers/Karlsruhe Schema

The proposal Karlsruhe Schema was built without a vote and the tagging is widely established based on this proposal. The Feature Page for the proposal Karlsruhe Schema is located at Key:addr.

Karlsruhe Schema
Proposal status:	Proposals with undefined or invalid status (inactive)
Proposed by:	MarcusWolschon (and others)
Tagging:	`addr:=*`
Applies to:
Definition:	Tagging of adresses
Statistics:
Draft started:	2008-04-19
RFC start:	2008-04-21
Vote start:	-
Vote end:	-

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 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).

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). If a single point for adding a adress is needed and a more suitable point cannot be determined (e.g. 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 is 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)" (Wayback Machine) from 2009-04-15 09:18:48 GMT on German talk-de mailing list).

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 )

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.
Keypad-Mapper 3 provides a highly efficient way to map house numbers and addresses according to the Karlsruhe Schema

Algorithm

A possible implementation may work as follows:

Load the way into memory
Load all nodes and ways related to the way via "type=associatedStreet" -relation.
(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
If any nodes or building-polygons the the exact house-number are found in steps 2 and 3, return them and abort.
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.
Determine the segment span by 2 housenumbers A and B of the iterpolation-way that the asked for house-number X is between.
posNumeric = X / (B - A)
If the segment only consists of the nodes tagged A and B, your location is trivial to interpolate.
if the segment contains further nodes, determine the segment your location is in using the sum of the segment-lengthes and posNumeric.
Determine your location on the segment found by using the length of the segment and the sums of the segments before this segment.

alg1

This can be completely removed via pre-processing. Appropriate pre-processors can be written for the osm-xml format or as a new osmosis-task to be usable by everyone instead of implementing it into each application. With this pre-computation, no more boundary-box queries are required.

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

Tag	Presence	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`	strongly recommended	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 (especially at intersections), so putting the name in here is strongly encouraged (more reliable).
`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`	optional	even/odd/all/alphabetic	How to interpolate the house numbers belonging to the way along the related street. See below.

Proposal:House numbers/Karlsruhe Schema

Contents

Basics

Tags

Single house next to the way

Using interpolation to mark many houses along a way

Non-integral interpolation

Giving hints about the full address (optional)

Giving hints about the road-access (optional)

Using relations to associate house and street (optional)

Tags

Members

Associating a node with a street

Associating a building-polygon with a street

Associating a series of house-numbers with a street

Usage

Algorithm

See also

Navigation menu

Proposal:House numbers/Karlsruhe Schema

Basics

Tags

Single house next to the way

Using interpolation to mark many houses along a way

Non-integral interpolation

Giving hints about the full address (optional)

Giving hints about the road-access (optional)

Using relations to associate house and street (optional)

Tags

Members

Associating a node with a street

Associating a building-polygon with a street

Associating a series of house-numbers with a street

Usage

Algorithm

See also

Navigation menu

Search