Proposed features/House numbers/Karlsruhe Schema
|This proposal was never voted on but nevertheless gained universal acceptance. The feature page is located at Key:addr|
|Status:||Proposed (under way)|
|Proposed by:||MarcusWolschon (and others)|
|Definition:||Tagging of adresses|
The scheme is (as anything in OSM) subject to change after everyone has gathered experience with tagging house-numbers and interpreting the mapped data.
- 1 Basics
- 2 Tags
- 3 Single house next to the way
- 4 Using interpolation to mark many houses along a way
- 5 Giving hints about the full address (optional)
- 6 Giving hints about the road-access (optional)
- 7 Using relations to associate house and street (optional)
- 8 Usage
- 9 Algorithm
- 10 See also
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).
The following tags are defined and in common use:
||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.
||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).|
||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.|
||optional||string||Postal code of the building/addressed area. Different countries have different length and different characters allowed for postal codes.|
||optional||string||City as used in postal addresses of the building/addressed area.|
||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".|
||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.|
||optional||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). 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.
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).
|type||associatedStreet||(use "associatedStreet" in tagging but in parsing also allow: "street")|
|name||streetname||optional but recommended|
See also Relations/Proposed/Street.
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>
- 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
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.
- 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.
- AddrN widely used extension of Karlsruhe Schema, already supported by some software despite proposal in draft status.