Proposal:House numbers/Karlsruhe Schema

From OpenStreetMap Wiki
< Proposal:House numbers
Revision as of 11:27, 9 August 2009 by Gernot (talk | contribs) (post-vote cleanup completed, set status to Approved)
Jump to navigation Jump to search

Template:Language-Karlsruhe Schema


Tag:addr:housenumber
Proposal status: Approved (active)
Proposed by: MarcusWolschon
Tagging: addr:housenumber=*
Applies to: node
Definition: Addresses
Statistics:

Rendered as: number
Draft started: 2008-04-19
RFC start: 2008-07-01
Vote start: 2008-12-01
Vote end: 2008-12-31
The Feature Page for the approved proposal addr:housenumber is located at Key:addr

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.

Housenumber-karlsruhe-de.png

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

Simple Case

For the most common case we need to keep the work and entry-barrier for mappers low.

Tags

The following tags are defined and in common use:

Tag required Element-Type Values Description
addr:housenumber or

addr:housename

required node area 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 England instead of a house number.

addr:street optional node area 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.
addr:state optional node area 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 node area string Postal code of the building/addressed area. Different countries have different length and different characters allowed for postal codes.
addr:city optional node area string City as used in postal addresses of the building/addressed area.
addr:country optional node area 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 node area 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 way 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.

Usage

Single house as a node next to the way

NodeNextToRoad.png

<node id="1">
  <tag k="addr:housenumber" v="10" />
</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.)

Single house as a building polygon

HousePolygonNextToRoad.png

<way id="1">
  <tag k="addr:housenumber" v="10" />
  <tag k="building" v="(yes|apartments|...)" /> 
</way>

This case is the same, we just use a polygon for the house. 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

HouseNumbersInterpolation.png

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" /> 
</node>
<node id="02" lat=... lon=...>
  <tag k="addr:housenumber" v="20" /> 
</node>
<node id="03" lat=... lon=...>
  <tag k="addr:housenumber" v="100" /> 
</node>
<way id="??">
  <node ref="01"/>
  <node ref="02"/>
  <node ref="03"/>
  <tag k="addr:interpolation" v="even" />
</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.

Non Integer 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.

Giving hints for choosing the street (optional)

Relations are the preferred way to provide a connection between housenumber and street, as they're easy 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.

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

Case: Selecting the street a house belongs to

HousePolygonNextToRoadWName.png

Street-names (easy for humans)

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

Only ways with a "highway"-tag are called streets. (e.g. this will not associate a numbered house with the polyline of a fence, wood or power-line). Please see the "giving hints"-sections about making this association with a street more robust.

Case: Relations (easy for computers, difficult for humans)

Tags

Key Value Discussion
type associatedStreet (use "associatedStreet" in tagging but in parsing also allow: "street")
name streetname optional but recommend

Members

Way or Node Role Recurrence? Discussion
way street one The associated street
node way 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.

<node id="1" 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.

Case: Selecting the street a house belongs to represented by its building-polygon

HousePolygonNextToRoadWRel.png

<node id="11" lat=... lon=...> 
  <tag k="addr:housenumber" v="10" />
  <tag k="addr:street" v="AStreet" /> 
</node>

or

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

Case: Selecting the street the series of house-numbers belongs to

<node id="1" lat=...lon=...>
  <tag k="addr:housenumber" v="10" /> 
</node>
<node id="2" lat=... lon=...>
  <tag k="addr:housenumber" v="20" /> 
</node>
<node id="3" lat=... lon=...>
  <tag k="addr:housenumber" v="100" /> 
</node>
<way id="11">
  <nref id="1"/>
  <nref id="2"/>
  <nref id="3"/>
  <tag k="addr:interpolation" v="even" />
  <tag k="addr:street" v="AStreet" />
</way>

or

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

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.

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.

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.

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.


  • Note: Step 3 can be completely removed via pre-processing. Apropriate 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.