/beginners guide

Mapping

Based in the Coventry & Warwickshire region, most of my mapping is focused in this area. My priorities chop and change depending on how easily I can get out on the ground. Past projects include contributing to Coventry so that it is ready for the licence changeover, adding many turn restrictions based on the feedback provided on MapDust, and adding all sorts of detail to the map. I try to keep an eye on the quality assurance tools.

Wiki

Mapping is important, but I can't do it on my own. I therefore get stuck in with editing the wiki pages on the United Kingdom. Mostly focused on trying to improve their usability, particularly for supporting newcomers.

---

XAPI Compatibility Layer

As requested on SOTM-EU 2011, Overpass API has got a compatibility layer for the most common XAPI queries. Both versions of the map call are supported, where the variant with map has slight performance advantages:

http://www.overpass-api.de/api/xapi?map?bbox=7.1,51.2,7.2,51.3
http://www.overpass-api.de/api/xapi?*[bbox=7.1,51.2,7.2,51.3]

The Overpass compatibility layer differs from XAPI, in that that it does not return relations that contain downloaded elements. Furthermore, it does not deliver changeset, user, version and timestamp data by default (this data is not necessary unless you want to upload changes back to the main server). However, if you want the data to be usable in some tools (e.g. JOSM, Osmosis) you can add [@meta] to your xapi request, and you will get them.

Let us consider the following usage example, and break it down into its separate components:

Example: http://www.overpass-api.de/api/xapi?way[bbox=7.1,51.2,7.2,51.3][name=Wuppertal-Barmen][railway=*][@meta]

Base URL

There are two base URLs - either can be used:

http://overpass.osm.rambler.ru/cgi/xapi?
http://www.overpass-api.de/api/xapi?

Map Features

Choose from node, way, and relation. Alternatively to retrieve any kind of element use the wildcard character, *.

Bounding Box

A bbox, or bounding box, can optionally be included to restrict data retrieval to a rectangular area. The area is defined using latitude and longitude values, with the order of the four numbers being left,bottom,right,top. A way belongs to a bounding box if it has as member node within the bounding box. Similarly, a relation belongs to a boundary box if a member way has in turn a node in the bounding box as member.

Tags

The addition of tags can be used to further restrict the data retrieved. You may either combine arbitrarily many tag search criteria with exactly one or any value:

http://www.overpass-api.de/api/xapi?node[name=Wuppertal-Barmen]
http://www.overpass-api.de/api/xapi?node[name=Wuppertal-Barmen][railway=halt]
http://www.overpass-api.de/api/xapi?node[name=Wuppertal-Barmen][railway=*]

Alternatively you can take at most one search criteria but allow for multiple values (by using '|' to represent the condition 'or'). For example, the following finds any node that has name Wuppertal-Barmen or Wuppertal-Oberbarmen.

http://www.overpass-api.de/api/xapi?node[name=Wuppertal-Barmen|Wuppertal-Oberbarmen]

Meta Data

You can add the directive [@meta] or the endpoint xapi_meta to any query to obtain also meta data in the results. This takes longer, but will allow you to open the results in JOSM.

http://overpass-api.de/api/xapi?node[bbox=7.1,51.2,7.25,51.3][@meta]
http://overpass-api.de/api/xapi_meta?node[bbox=7.1,51.2,7.25,51.3]

Other

You can use [@newer=2011-07-01T00:00:00Z] to restrict the results to elements newer than the given date.

http://overpass-api.de/api/xapi?node[bbox=7.1,51.2,7.25,51.3][@newer=2011-07-01T00:00:00Z]

You can restrict the result to elements touched last by a specific user. In the example, it me Roland Olbricht.

http://overpass-api.de/api/xapi?*[highway=bus_stop][bbox=7.1,51.2,7.25,51.3][@user=Roland Olbricht][@meta]

Or use instead of the user name the user id. It is my user id in the example, 65282.

http://overpass-api.de/api/xapi?*[highway=bus_stop][bbox=7.1,51.2,7.25,51.3][@uid=65282][@meta]

---

Conditional Restrictions

Restrictions are used to limit use of a highway in some way. This may be to prevent use by a sub-group (for example, vehicles over 12 meters in length), or to impose conditions on it's use (for example a maximum speed of 80 km/h). To understand how to tag restrictions it may be helpful to classify the restriction by its level of complexity:

• Simple Restrictions: Long standing tags such access=*, oneway=*. maxweight=*, maxlength=*, maxspeed=*, and so on, are used to easily add basic restrictions to OpenStreetMap.

• Extended Restrictions: If the restriction only applies to certain transportation modes (vehicle category) or directions, the tag key can be extended by appending this information after the restriction type. Examples include oneway:bicycle=* and maxspeed:hgv=* - see more.

• Conditional Restrictions: In some cases restrictions are only valid when certain conditions are fulfilled. Examples may be cars not allowed on Sundays or a lower maxspeed applicable between 6:00 and 20:00.

The tagging scheme described here explains how to add the more complex 'Conditional Restrictions' to OpenStreetMap.

Overview

This tagging scheme can be used for adding complex restrictions that only apply under certain conditions to OpenStreetMap. The schema was introduced in October 2012 after a period of consultation (link). Some of the basic principles that helped this schema to be adopted include:

• No variable parts in the key. This helps to reduce the number of unique keys therefore making it easier to search the database.
• Clear distinction between scope (transportation mode, vehicle class) and condition.
• The syntax is backwards compatible and makes use of established key syntax with an additional qualifier ":conditional".

Tagging

The general syntax of the tag is:

<restriction-type>[:<transportation mode>][:<direction>]:conditional
  = <restriction-value> @ <condition>[;<restriction-value> @ <condition>]

(fields in square brackets [..] are optional).

Key

The key is constructed in the same way as keys for established restriction tags with an additional :conditional suffix.

Restriction type

This can be any type of restriction that may have conditional validity. Common examples are access, maxspeed and oneway restrictions. The restriction type should reflect the main traffic sign. For this sign having an additional sign specifying a condition the type should be access. On the other hand for this sign the restriction type should be maxlength (similar for other max<dimension> signs).

Transportation mode

This key-part specifies the vehicle category or transportation mode to which the restriction applies. E.g. bicycle, motor_vehicle, foot, agricultural. For access restrictions it is allowed to use the abbreviated form by omitting access: in front of the category. E.g. motorcar instead of access:motorcar. Please note that the value agricultural designates the type of vehicle (typically tractors or special machines having a low maximum speed), not the purpose of the highway use.

See Key:access for the full transportation mode hierarchy. However, this proposal differs in one respect from the established transportation mode hierarchy of the access tag. The "By use" modes (hov, emergency, hazmat, disabled) are considered to be true conditions and as such should be used in the values, not in the key.

Direction

Some restrictions are direction dependent. Use forward and backward to indicate in which direction the restriction applies.

Value

The value comprises the actual restriction (e.g. "no") followed by the @ character and the condition. Add spaces before and after the @ character to improve readability.

Normally just one value with a corresponding condition is specified. In exceptional cases it may be necessary to use two or more values. Such value-condition pairs should be separated by a semi-colon. One situation may be a certain speed limit at certain times of day but a different (lower) speed limit in case of wet conditions. See Conflicting Restrictions below how to order multiple value-condition pairs.

Restriction-value

The actual value of the restriction, e.g. yes, private, 80, 55 mph. The restriction can be absolute (yes, no, permissive and other values that apply to everybody), according to the purpose of the highway use (destination, delivery, customer, forestry, agricultural etc) or according to an explicit permission (private, permit_holder).

Condition

This field specifies the condition for which the restriction is valid. Various kinds of conditions can be distinguished.

• Time: Use the standard syntax of the Opening hours tag. If the time condition includes the character ";" the condition must be enclosed by brackets. E.g. (Mo-Fr 7:00-19:00) or (sunrise-sunset).
• Road condition: E.g. wet
• Vehicle property: Some examples of properties are weight, axleload, length, width, height and draught. Use relative operators (<, >, =, <=, >=) to define the condition. E.g. (weight<7.5)
• Vehicle usage: The restriction depends on how the vehicle is used, such as the number of occupants or the load. E.g. (occupants>2) or hazmat.
• User group: The restriction relates to a specific user group, e.g. doctor, disabled, emergency, female.
• Purpose of access: For restriction types expecting a numerical restriction value such as maxweight the condition may be a purpose-of-access condition (destination, delivery, customer, agriculture, forestry) or permission type condition (private, permit_holder). Example: maxweight=2.5 + maxweight:conditional=none @ destination.

Except for very simple conditions like "wet" or "Su" it is recommended to enclose the condition in brackets.

Combined conditions: AND

Two or more partial conditions may be combined using the operator AND. It is recommended to use the uppercase form to improve readability. AND means that both partial conditions must be fulfilled for the condition to apply. Example access:conditional=destination @ (Sa-Su AND weight>7)

Default restrictions

It is not always clear which restriction applies when the condition is not fulfilled. In such cases the default restriction should also be specified. E.g maxspeed=120 + maxspeed:conditional=100 @ (20:00-06:00). In some cases a default restriction can be assumed and need not be explicitly tagged. For many highway classes like unclassified an implicit access=yes is assumed. See Access restrictions for default access restrictions to different highway classes.

Evaluation of conflicting restrictions

When an object has two or more different restrictions both matching the given traffic and conditions the following algorithm determines which one is valid.

1. A restriction having a more specific transportation mode overrules a less specific transportation mode. E.g. a tag for "psv" overrules a tag for "motor_vehicle" in case of a public service vehicle. See Key:access for the transport mode hierarchy.
2. A directional restriction overrules a non-directional restriction of the same transportation mode
3. A conditional restriction overrules a non-conditional restriction of the same transportation mode and direction
4. In case of multiple matching value-condition pairs in the same tag the last matching value becomes the effective restriction value. Therefore it is important to put the more general restriction first and the more specific restriction last. Some examples:
   • (access=yes) + access:conditional=no @ (9:00-17:00); destination @ (9:00-17:00 AND disabled) will allow destination traffic for disabled persons (the last match) while all other traffic isn't allowed 9am-5pm. The time condition needs to be repeated in the second value, otherwise disabled persons would only have destination access 17:00-9:00 while all other traffic would have general access.
   • (maxspeed=none) + maxspeed:conditional=120 @ (06:00-20:00); 80 @ wet: Here the 80 at wet will overrule the time based restriction in case of wet conditions.
   • (access=no) + access:conditional=delivery @ (7:00-11:00); customer @ (7:00-17:00): Here is actually no conflict as only one value can match (the purpose of access must match in case of destination, customer, delivery, agricultural and forestry).

Examples

Tagging	Interpretation
maxspeed=120 maxspeed:conditional=80 @ wet	Maxspeed is 120 km/h under normal conditions, but 80 km/h when the road is wet.
maxspeed=50 maxspeed:conditional=30 @ (Mo-Fr 07:00-17:00)	Maxspeed limited to 30 on 7am - 5pm weekdays, but 50 otherwise.
maxspeed=none maxspeed:conditional=120 @ (6:00-20:00); 100 @ (22:00-6:00)	Two conditional maxspeed values valid at different times of day (this example apparently exists in real somewhere in Germany).
bicycle=yes bicycle:conditional=no @ (10:00-18:00)	Bicycles are permitted to use this street outside 10am-6pm.
access:conditional=destination @ (weight>5.5)	Vehicles over 5.5t are only allowed for destination traffic.
motor_vehicle:conditional=no @ (10:00-18:00 AND length>5)	Vehicles longer than 5 meter not allowed 10am - 6pm
overtaking:hgv:conditional=no @ (6:00-9:00, 15:00-18:00)	Overtaking not permitted for heavy goods vehicles during rush hours
oneway:conditional=yes @ Su oneway:bicycle=no	Street is oneway on Sundays but bicycles may use it in both directions at all times.