Digitransit

From OpenStreetMap Wiki
Jump to navigation Jump to search

This documentation contains information about the Digitransit project and OpenStreetMap. The documention was created to help editing OpenStreetMap to support routing and geocoding (address search) and understanding these issues specially out of Digitransit's perspective. Obviosly edits made to OpenStreetMap also have an impact on the digitransit background map. These issues aren’t however explained in detail in this document – see section More experienced mappers for further details regarding the used background map style. Notice that when you edit OpenStreetMap, even though your edits are saved immediately to OpenStreetMap, it takes about two days (due to the data loading processes) before your edits have effect on the Digitransit routing & geocoding and about one week (due to different cache settings) before you see them on the background map.

About Digitransit

Digitransit is a collaboration project providing a service platform for a public transport journey planner. The service is based on OpenTripPlanner and has been developed by Helsinki Region Transport (HSL), the Finnish Transport Infrastructure Agency (Väylä) and TVV LMJ Oy. Digitransit has the following running instances in Finland...

Beside these there are also instances of Digitransit running in ...

The norwegian national journey planner also has some common history with Digitransit and still uses the same platform (OpenTripPlanner) as Digitransit for routing.

Allthough this documention was developed mainly by representatives from Helsinki Region Transport, all these finnish running instances follow the same basic priciples explained in this document.

Learning to map

The following sections have various tasks for those interested to improve OpenStreetMap and Digitransit routing or geocoding. The assumption is that you have learned the basics of the OpenStreetMap mapping before doing the following tasks. You can learn about OpenStreetMap and mapping, for example, via Learn OpenStreetMap Step by Step guide by HOT OSM or Learn to map guide by MapGive. If you like, you can also join various OpenStreetMap community events that are advertised, for example, in the OpenStreetMap Finland Facebook group.

Adding your home building(s)

Easy task

Especially, if you are not living in a city it is possible that your home building has not yet been added to OSM.

The National Land Survey's "MML Orthophoto" that is shown by default in the iD editor will probably show the location of the house, but if not, then you can also try other base layers, such as, the topographic or background map from the National Land Survey.

You should draw the contours of the building and choose the correct building type from the left side menu in the iD-editor.

You can also add address information. Add the addr:housenumber=* and addr:street=* tags for the building(s). It's also recommended to add information about the building entrance(s). These should be tagged with either entrance=main or entrance=yes and placed on the building outline (NB unconnected "floating" entrance nodes will not be included in the address search) (*). These are the two digitransit supported entrance tags at the moment. Each building can have only one entrance used for routing. entrance=main is more highly ranked than entrance=yes. If one building has multiple entrances with the same rank then digitransit just choses one of them by chance. Note that the interior of the buildings can also be mapped, eg. large shopping centers.

Roads

Adding roads and paths

Easy task

It is also very possible that your home road has not been added yet. To enable routing to the very next to your home, you can add road leading to your home to OpenStreetMap.

The countryside in Finland is missing many minor roads, not to speak about the tracks and paths. In cities, almost all roads and even paths have already been added but there can always be something to edit.

Way(s) should be drawn where the road is. You can use the national land survey maps from kartat.kapsi.fi mentioned in the previous section to see locations of the roads. See highway=* and the highways page on how roads and paths should be tagged.

highway=path tagged objects are by default added to the routing network and included in the walking and cycling profiles. Sometimes there can be a need to exclude some existing paths from the routing network eg. unofficial paths that cross roads dangerously. This can easily be done by adding the tag informal=yes to the path in question. This setting will exclude the path from the routing network unless the tag foot=yes is used. This foot=yes setting will in turn override the informal=yes setting and again include the path in the routing network. Therefore it's recommended to also use a tag like foot=discouraged to ensure the exlusion of the path.

Small paths were earlier excluded from the routing network by using highway=trail instead of highway=path. This setting excluded the trails from the routing network unless the tag foot=yes was used. So by adding the foot=yes you could earlier include highway=trail objects in the routing network. The highway=trail tagging is however nowadays deprecated so using it is no longer encouraged.

Very small isolated routing sections (so called routing islands) will be totally dropped out of the routing network in order to avoid error messages when routing to or from these sections, so please check the routing network as the first step of troubleshooting when you can't access a certain object of your choise (*).

See also:

Road name tagging

Easy task

In Finland quite many roads have the name=* but Swedish names are missing, so name:sv=* could be added. If the name:fi=* is missing then that can, of course, also be added. The name=* should reflect the name in the major language in each municipality so the language of this tag may vary in different parts of Finland.

See also:

Roundabout tagging

Easy task

To prevent pedestrian routing via a roundabout you should add foot=no to it. For example, this roundabout part (and rest of it) has the tag. However, note that not all roundabouts should have the foot=no added to it. In Finland pedestrians and cyclist are not allowed to use the roundabout if they have their own paths at the junction that have been indicated by the traffic signs[1].

There are also many roundabouts that have not been tagged with the junction=roundabout, so if you are editing one with missing tag(s) then it is a good idea to add this tag also. Finally, if applicable, also the bicycle=use_sidepath tag could be added or the bicycle=no tag if there is a traffic sign that explicitly forbids cycling.

Construction work

Easy task

If a construction work is blocking access via a road, then you should:

  1. add construction=* tag
  2. give the current value of the highway=* for the construction=*
  3. change the value of the highway=* to highway=construction

Eg. before highway=cycleway and after highway=construction + construction=cycleway.

Of course, after the construction work has finished and the road is opened, you should change the value of the highway=* back to the original and remove the construction=* tag.

If the construction work is minor and not blocking access, then you should not change the value of the highway=* but just add construction=minor.

See also:

Road access tagging

Intermediate task

You are strongly suggested to also read the Key:access page.

To prevent routing via a road you should add access=no tag or access=private tag to it. access=no will totally prevent routing and access=private will prevent routing through the private tagged parts and hence make it possible to use private sections as destination or origin. An exception to this rule are the sections which are tagged with both access=private and highway=service. These kind of roads are totally dropped out of the routing network as these often represent no go areas like airfields or other industrial areas with very restricted access. access=yes is the default for highways in OpenStreetMap and does not need to be added. For example, this service road at the Helsinki-Vantaa airport has access=private tag.

If the access restriction is specific for the pedestrians then add the foot=no tag to it. Note, that in Finland law states that pedestrians have to use pedestrian path if one is available[2]. On the other hand, if a road has access=no tag and you want to allow pedestrian routing via it then add foot=yes, foot=designated or foot=permissive tag for the road. If you want to allow bicycle routing via the access=no tagged road then add bicycle=yes, bicycle=designated or bicycle=permissive tag.

You can also use bicycle=use_sidepath to prevent routing for bicycles but in this case remember to tag the sidepath, so that routing for bicycles will work. In practice, this often means adding highway=cycleway tag to the sidepath together with foot=yes or foot=designated tag.

Furthermore, access=destination, access=customers, access=delivery, access=forestry and access=agricultural also affect pedestrian and bicycle routing via the tagged road or path, so if the access is restricted only, for example, to motor vehicles then use the motor_vehicle=* tag instead of the access=* tag for marking the restriction. As for now these more complicated rights to certain modes of transport eg. bicycle=destination will not work in Digitransit. This will however be possible when Digitransit is upgraded to OpenTripPlanner 2.0 (*).

NB. Using a via-point in routing which is within an area with restricted access (eg. access=destination) will create a passage that will fail to route due to the nature of the access=destination as it doesn't really allow passage (*).

Though the Key:access page explains access:conditional=* tag, it is not currently used in OTP nor in Digitransit so, for example, time specific restrictions do not affect routing (*).

See also:

About areas without highway tag

Routing is done via areas that have the highway=* tag eg. highway=pedestrian for pedestrian street & squares. The routing network for such an area is created by connecting nodes with each other with straight lines (where this can be done eg. where there's no obctacles in the way) and thus creating a network of diagonals that can be used in routing. An area that has the amenity=parking but no highway=* tag is not taken into account in routing. In these cases you should always add a way with highway=service together with service=parking_aisle tag inside the parking area in order to enable routing via these ways. The same goes for place=square which won't be routable as such without highway=*.

NB. area:highway=* areas are suposed to describe the non-routable, detailed shape of a (typically linear) highway and thes will not be included in the routing network either.

Some examples

Various tasks

Bus stops

Adding a bus stop

Easy task

Not all bus stops have been added to OpenStreetMap. You should add a node and add tags public_transport=platform, bus=yes and highway=bus_stop to it. It would be good to have an as accurate position as possible for the bus stop. Therefore you should either know the exact position or you could survey it by visiting the bus stop location. You should also add ref and name tags to it as described in the next task. In addition, you can add other tags such as shelter=*. The tag public_transport=stop_position is not currently used by Digitransit.

The next step in the process is to connect the bus stop to the OSM walking network. This is done to guarantee accurate routing to and from the bus stop. This is either done by connecting the node physically to a highway -object (road or platform) or by creating a relation which contains the bus stop. Here's a number of examples of bus stops connected to different types of highway nodes.

Here an example of a stop that is part of a stop relation.

Adding ref and name

Easy task

There are bus stops that have been added to OpenStreetMap but lack ref=* and name tags name=*, name:fi=* and name:sv=*. Adding the ref tag will improve accuracy of the bus stop location and routing in Digitransit since this will make it possible to connect the OSM stop (ref) to the stop provided by the GTFS files (stop_code) by the transport authority. When this connection has been established digitransit will use the OSM stop geometry when presenting or refering to the stop. There a two possible limitations for this connection between OSM and GTFS based stops. They have to be under 200 meters apart and the OSM stop has to be topologically connected to the OSM walking network.

You can find the correct ref and name tags from the actual physical bus stop, at least in Helsinki. In addition, you can find them from the Digitransit web map, at least in the HSL journey planner. Clicking the bus stop will show the information (though bus stop location can be inaccurate).

Note, that Digiroad data also contains bus stop ids for the whole of Finland and the Finnish transport agency has issued a permission to incorporate this CC-BY 4.0 licenced data into OpenStreetMap, so this data could also be used when providing bus stops with refs and names. When adding Digiroad bus stop data to the OpenStreetMap, the Digiroad national stop id should be added using ref:findr=* tag

See also:

Creating and tagging elevators

Intermediate task

Elevators are used in routing when they are connected to the rest of the roads and paths and they are especially important to the people using wheelchairs and also people pushing prams use them a lot.

You should add node that is tagged with the highway=elevator and connect the node at the each level=* to the rest of the routing network. For example, this elevator at the Koivukylä railway station is connected in three levels. Please, notice that there is also the wheelchair=yes tag. Of course, more tags could be added if applicable.

See also:

Adding names for places

Intermediate task

Though OSM-road names ( highway=*) are not included in the place name search (you can think of it as address search), Digitransit uses data from the OSM-levels for the place name searches.

If a node, way, or area has one of the following tags then the value of the name=* and many of it's variations are included in the searches:

The name=* tag variations that are used together with the above tags are:

NB You can also add a language suffix (:fi :en or :sv) to any of the name tags above. Then that name will also be included in the name searches, for example like this :

In addition, if you add addr:street=* and addr:housenumber=* tags for the node, way or area then the address is shown together with the name when searched. This is always useful but especially when there exists many places with the same name.

Please, note that even if a building has the addr:street=* and addr:housenumber=* tags a place node inside the building should also have those tags to be shown together with the place name when searched or to make it possible to find the place node with just the address.

This prociple of course creates a lot of duplicates in the sence of address search. There's no prioritizing between nodes and ways with the same address except that buildings that are tagged building=barn, building=cabin, building=shed, building=garage, building=hut or building=carbage_shed get a lower score and are thus avoided in the address search. Addresses with entrance=* or gate=* tags are prioritized to lead search results to entrances of shopping centers (instead of separate POI's) and to gates leading to eg closed areas.

OpenStreetMap place names are a fundamental part of Digitransit geocoder dataset and thus choosing appropriate names for nodes can affect the geocoding results and user experience greatly. There are few principles that should be followed to improve the geocoding user experience:

  • Central transportation locations and terminals should be tagged with one of the tags above and named according to its official name (e.g. "Rovaniemen linja-autoasema" or "Oulu" for the railway station)
  • The name of the city or area of the central transportation terminals should be added as alt_name in its nominative form (or similar) for the central transportation terminals in OpenStreetMap. (e.g "Rovaniemi linja-autoasema" has alt_name "Rovaniemi").
  • Special care should be taken when naming and placing airport areas and terminals to ensure that the geocoder can suggest a feature reachable by walking near or at the actual airport terminal instead of the airport area centroid.

To ensure that no relevant objects will be left out of the name search just because they don't have a name - objects with the following tags are brought into the name search even if they don't have names.

See also:

  • Geocoding Data on Digitransit.fi pages for more details on how the search works and what data sources are utilized in it

Editing railway platforms

Tagging the platforms

Advanced task

For example, the railway station at the Helsinki-Vantaa airport has two platforms, one for the I train and one for the P train (see the HSL journey plannes search results).

One possible solution, probably not a good one because it doesn't use the public_transport=stop_position and it differs from practice eg. in Germany, in this case would be to create a public_transport=stop_area_group relation that has two public_transport=stop_area relations and each of these two relations has the ref=* tag that has the "short id" of the stop as the value. For example, for the Helsinki-Vantaa airport case the ref values would be V0531 and V0536. As an example, see V0531 public_transport=stop_area relation.

In some cases many platforms can have the same short id. In these cases you could still add separate public_transport=stop_area relations and give the same ref value for them.

To add the number of the platform you could use the ref=* tag or maybe local_ref=* for the area object that has public_transport=platform tag. For the Helsinki-Vantaa airport railway station case the values are 1 and 2. See http://www.openstreetmap.org/way/461307443 as an example of the public_transport=platform area.

To see more information on the public_transport tagging and relations, please see:

Dividing single platform to multiple parts

Advanced task

The train stop location are currently taken from GTFS. Routing currently happens via railway platform area borders and not over the area unless the area is divided to multiple parts (or there is a highway tagged way going from the border of the area to some other border).

The above facts mean that routing can give unnecessary long routes going from a point on a side of the platform to end of the platform and to the point (near the train stop) on the other side of the platform. This issue can be solved by diving the platform to parts on the locations where a highway is connected to the platform.

For example, an Espoo railway station platform is divided to two parts (https://www.openstreetmap.org/way/479453500 and https://www.openstreetmap.org/way/34007202) on nodes https://www.openstreetmap.org/node/669330256 and https://www.openstreetmap.org/node/4725484001. Note that there is a way tagged highway=footway (https://www.openstreetmap.org/way/40168456) and two ways tagged highway=steps (https://www.openstreetmap.org/way/34007204 and https://www.openstreetmap.org/way/462035339) connected to the platform on this location. If the platform was not divided to two parts then the route from the footway to the south side of the platform would happen via the end of the platform.

Editing two platforms next to each other

Advanced task

Often there is a platform area between two railway tracks that is physically one platform but has two platform numbers or letters, one for each track. For example, at the Helsinki central railway station the platform 5 and platform 6 are physically same area.

Sometimes to make the two platforms separate, you can simply divide the existing area in the OSM from the middle to two areas. However, quite often the existing platform in OSM is not an area but a way or there is, for example, an elevator building or highway=steps leading to tunnel below platforms in the middle of the area. Also, in the latter case the area has often been defined as Relation:multipolygon where there are inner areas for example, for the highway=steps. In this case you cannot simply divide the multipolygon two two areas, one for each platform.

The process to create two separate platforms from an multipolygon in the JOSM editor that has the UtilsPlugin2 installed is as follows:

  1. Add a way through the middle of the outer area (long axis) from border to border
  2. Select the outer area and the nodes at the ends of the way you added
  3. Split the outer area (alt+X)
  4. Select the two new areas and the inner area of your preference
  5. Add nodes at the intersections (shift+I)
  6. Select one of the new areas and the nodes at the intersection
  7. Split the way (P), select the new way inside the inner area and delete it.
  8. Repeat the previous two steps with the other new area.
  9. Select the inner area and the nodes in the middle of it's border and split the way (P)
  10. Select one of the new ways that were created from the inner area
  11. Select the way of the old outer area on the same side as the selected way of the old inner area
  12. Combine the ways (C), in the conflict dialog keep all the tag values and the public_transport relation (if one exists)
  13. Repeat the three previous steps for the other side of the old inner and outer area
  14. If needed you can add an building that shares the nodes of the old inner area
  15. Repeat steps from 4 to 14 for the rest of the inner areas

Miscellaneous notes

  • As long as there is a connection between, for example, two ways via a node then Key:layer and Key:level do not affect routing.
  • Currently only cycling routing utilizes weights in the OpenTripPlanner (routing in the Digitransit is based on the OTP).
  • If you would like to see the OTP route graph (=routing network) of the Helsinki area as a base layer in your OSM editor (iD, JOSM, ...) then you can add it as a TMS layer: HSL - tms[21]:http://api.digitransit.fi/routing/v1/routers/hsl/inspector/tile/traversal/{z}/{x}/{y}.png, Waltti regions - tms[21]:http://api.digitransit.fi/routing/v1/routers/waltti/inspector/tile/traversal/{z}/{x}/{y}.png, and Finland - tms[21]:http://api.digitransit.fi/routing/v1/routers/finland/inspector/tile/traversal/{z}/{x}/{y}.png

One other option is to add the text ?debugTiles in the web browser at the end of the journey planner URL eg. reittiopas.fi/etusivu?debugTiles. This will place the route graph as the background layer in your journey planner. This works for all the different Digitransit -instances (HSL, matka.fi etc.).

  • Also the HSL background map is available as a TMS layer: tms[21]:http://api.digitransit.fi/map/v1/hsl-map/{z}/{x}/{y}.png

Known issues

  • Using a via-point in routing which is within an area with restricted access (eg. access=destination) will create a passage that will fail to route due to the nature of the access=destination as it doesn't really allow passage.
  • Time dependant routing with access:conditional=* isn't yet supported eg. through graveyards or shopping centers that have their gates or doors open only certain hours of the day or through ice roads that are only open during parts of the year in winter time. Ways that have limited access eg. paths that are used as skiing tracks or just aren't maintained (snowplowing=no) during winter time belong to this same category. As for now it's either open or closed all the time in these cases. Routing at certain hours of the day became theoretically possible when the routing engine version was changed from OTP1 to OTP2 (March 2023) but this is a really complex problem to solve and will require a really extensive work with the routing engine.
  • opening_date=* isn't supported so you can't issue (at least to Digitransit) when a certain road segment will be opened in advance using this tag.
  • Very small isolated routing networks (so called routing islands) eg. islands will drop out of the routing network and there is no tagging syntax or procedure to guarantee that these will be included in the routing network.
  • Entrance nodes which aren't connected to any building outlines (building:part -doesn't count either) will drop out of the address search eg. this one.

See also

Especially for beginners

All mappers

More experienced mappers

References

  1. ↑ Kiertoliittymä ja miten siinä ajetaan, Tiehallinto, http://alk.tiehallinto.fi/kiertol/kiertol.htm
  2. ↑ Tieliikennelaki, 3.4.1981/267, Finlex, Oikeusministeriö, ylläpito Edita Publishing Oy, http://www.finlex.fi/fi/laki/ajantasa/1981/19810267
Retrieved from "https://wiki.openstreetmap.org/w/index.php?title=Digitransit&oldid=2787093"