{"componentChunkName":"component---src-templates-developers-js","path":"/en/developers/apis/5-realtime-api/vehicle-positions/high-frequency-positioning/","result":{"data":{"childPages":{"edges":[{"node":{"fields":{"slug":"/en/developers/"},"frontmatter":{"title":"For developers","order":null,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/architecture/"},"frontmatter":{"title":"System architecture","order":null,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/api-registration/"},"frontmatter":{"title":"API portal and registration","order":-12,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/changes/"},"frontmatter":{"title":"Changes","order":-10,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/user-interfaces/"},"frontmatter":{"title":"User interfaces","order":null,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/deprecations/"},"frontmatter":{"title":"Deprecations","order":-11,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/docker-guide/"},"frontmatter":{"title":"Docker guide","order":null,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/apis/"},"frontmatter":{"title":"APIs","order":null,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/apis/1-routing-api/"},"frontmatter":{"title":"Routing API","order":null,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/apis/2-routing-data-api/"},"frontmatter":{"title":"Routing data API","order":null,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/apis/4-map-api/"},"frontmatter":{"title":"Map API","order":null,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/architecture/x-apis/"},"frontmatter":{"title":"API architecture","order":null,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/apis/6-api-faq/"},"frontmatter":{"title":"FAQ","order":null,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/apis/5-realtime-api/"},"frontmatter":{"title":"Realtime APIs","order":null,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/apis/3-geocoding-api/"},"frontmatter":{"title":"Geocoding API","order":null,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/apis/7-terms-of-use/"},"frontmatter":{"title":"Terms of use","order":null,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/user-interfaces/1-digitransit-ui/"},"frontmatter":{"title":"Digitransit-ui","order":null,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/apis/1-routing-api/0-graphql/"},"frontmatter":{"title":"GraphQL","order":10,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/apis/1-routing-api/3-realtime-information/"},"frontmatter":{"title":"Real-time information","order":40,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/apis/1-routing-api/2-glossary/"},"frontmatter":{"title":"Glossary","order":30,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/apis/1-routing-api/canceled-trips/"},"frontmatter":{"title":"Canceled trips","order":80,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/apis/1-routing-api/disruption-info/"},"frontmatter":{"title":"Disruption info","order":70,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/apis/1-routing-api/4-translations/"},"frontmatter":{"title":"Translation","order":50,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/apis/1-routing-api/routes/"},"frontmatter":{"title":"Routes","order":100,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/apis/1-routing-api/stops/"},"frontmatter":{"title":"Stops","order":110,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/apis/1-routing-api/bicycles-scooters-cars/"},"frontmatter":{"title":"Bicycles, cars and e-scooters","order":60,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/apis/1-routing-api/itinerary-planning/"},"frontmatter":{"title":"Itinerary planning","order":90,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/architecture/x-apis/1-routing-api/"},"frontmatter":{"title":"Routing API","order":null,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/architecture/x-apis/2-routing-data-api/"},"frontmatter":{"title":"Routing Data","order":null,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/architecture/x-apis/4-map-api/"},"frontmatter":{"title":"Map API","order":null,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/architecture/x-apis/5-realtime-api/"},"frontmatter":{"title":"Real-time APIs","order":null,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/architecture/x-apis/3-geocoding-api/"},"frontmatter":{"title":"Geocoding API","order":null,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/apis/1-routing-api/1-graphiql/"},"frontmatter":{"title":"GraphiQL","order":20,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/apis/4-map-api/background-map/"},"frontmatter":{"title":"Background map","order":null,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/apis/5-realtime-api/1-getting-started/"},"frontmatter":{"title":"Getting started","order":10,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/apis/3-geocoding-api/address-search/"},"frontmatter":{"title":"Address search","order":null,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/apis/3-geocoding-api/autocomplete/"},"frontmatter":{"title":"Autocomplete","order":null,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/apis/5-realtime-api/trip-updates/"},"frontmatter":{"title":"Trip updates","order":30,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/apis/5-realtime-api/service-alerts/"},"frontmatter":{"title":"Service alerts","order":20,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/apis/3-geocoding-api/address-lookup/"},"frontmatter":{"title":"Address lookup","order":null,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/apis/4-map-api/pois/"},"frontmatter":{"title":"Points of interest","order":null,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/apis/5-realtime-api/vehicle-positions/"},"frontmatter":{"title":"Vehicle positions","order":40,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/architecture/x-apis/3-geocoding-api/data-container/"},"frontmatter":{"title":"Data builder and container","order":null,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/architecture/x-apis/3-geocoding-api/api/"},"frontmatter":{"title":"API","order":null,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/apis/5-realtime-api/vehicle-positions/high-frequency-positioning/"},"frontmatter":{"title":"High-frequency positioning","order":20,"redirect":null}}},{"node":{"fields":{"slug":"/en/developers/apis/5-realtime-api/vehicle-positions/digitransit-mqtt/"},"frontmatter":{"title":"Digitransit MQTT broker","order":10,"redirect":null}}}]},"markdownRemark":{"fields":{"slug":"/en/developers/apis/5-realtime-api/vehicle-positions/high-frequency-positioning/"},"frontmatter":{"title":"High-frequency positioning","redirect":null,"toc":true,"description":{"info":"The open HFP API can be used to subscribe to vehicle movements in soft real time.","architecture":"https://raw.githubusercontent.com/HSLdevcom/digitransit-site/master/src/pages/en/developers/apis/5-realtime-api/vehicle-positions/high-frequency-positioning/architecture.xml"},"assets":null,"technologies":null,"docker":null},"html":"

Most of the vehicles in the HSL area should publish their status, including their position, once per second.\nThe devices of the end users, e.g. smartphones, may subscribe to receive the relevant messages based on their context, e.g. filtered on the mode of transport, the route ID, the geographical region etc.\nThe subscription scope is specified by the MQTT topic structure of the API.

\n

Vehicle positions are also available in GTFS-RT format, see HSL GTFS-RT API documentation

\n

Quickstart

\n

Try this example to get an quick idea of what kind of data is available from the API:

\n
    \n
  1. Install MQTT.js command line tools:
    2. \n
\n
npm install -g mqtt
\n
    \n
  1. Use MQTT.js to subscribe to HFP messages:
    2. \n
\n
mqtt subscribe -h mqtt.hsl.fi -p 8883 -l mqtts -v -t \"/hfp/v2/journey/#\"
\n\n

API endpoints

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
URLDescription
mqtts://mqtt.hsl.fi:8883/The bare MQTT protocol with TLS, lightweight.
wss://mqtt.hsl.fi:443/MQTT over WebSockets with TLS, for browsers.
mqtt://mqtt.hsl.fi:1883/The bare MQTT protocol without TLS, lightweight. Prefer the port 8883 to respect the locational privacy of your users.
ws://mqtt.hsl.fi:1883/MQTT over WebSockets without TLS. Prefer the port 443 to respect the locational privacy of your users.
\n

Message format

\n

From a client's point of view, every MQTT message has two parts, the topic and the binary payload.

\n

The topic

\n

The topic looks similar to a file path with levels separated by /.\nWhen subscribing, all values for a level or several levels may be specified with a wildcard.\n+ refers to all values for one level, # refers to all values of the parent level and its child levels.\nSee the advanced examples further below on how to tailor the subscription to your needs.

\n

Here is an example of an HFP message topic:

\n
/hfp/v2/journey/ongoing/vp/bus/0055/01216/1069/1/Malmi/07:20/1130106/2/60;24/19/73/44
\n

It can be split into these parts:

\n
/<prefix>/<version>/<journey_type>/<temporal_type>/<event_type>/<transport_mode>/<operator_id>/<vehicle_number>/<route_id>/<direction_id>/<headsign>/<start_time>/<next_stop>/<geohash_level>/<geohash>/<sid>/#
\n

Topic levels up to vehicle_number are present in all types of topics and levels after vehicle_number are only present with vehicle journey position messages (i.e. when journey_type is journey).

\n

Note: For future proofing your subscription, add wildcard # to the end of the topic. We may change the HFP topic structure by adding new filters to the end without updating the version number.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
AttributeDescription
prefix/hfp/ is the root of the topic tree.
versionv2 is the current version of the HFP topic and the payload format.
journey_typeThe type of the journey. Either journey, deadrun or signoff.
journey refers to a vehicle that is running on a specific public transport journey.
deadrun refers to a vehicle that is not on any specific route, but instead coming from a depot, for example.
signoff is used when the vehicle PC is shut down.

Note: deadrun and signoff messages are only available for authorized users.
temporal_typeThe status of the journey, ongoing or upcoming.
ongoing describes a journey that is currently in operation.
upcoming refers to the next expected journey of the same vehicle. upcoming messages are broadcasted shortly before the start of the next journey. One use of upcoming is to show the relevant vehicle to your users even before the driver has signed on to the journey that your users are interested in.
event_typeOne of vp, due, arr, dep, ars, pde, pas, wait, doo, doc, tlr, tla, da, dout, ba, bout, vja, vjout.
See descriptions for these values below.
transport_modeThe type of the vehicle. One of bus, tram, train, ferry, metro, ubus (used by U-line buses and other vehicles with limited realtime information) or robot (used by robot buses).
operator_idThe unique ID of the operator that owns the vehicle. See the list of operators below.
Note: Operator ids must be exactly 4 digits long in the topic filter, so prefix them with zeroes if needed (e.g. 80 → 0080)
vehicle_numberThe vehicle number that can be seen painted on the side of the vehicle, often next to the front door. Different operators may use overlapping vehicle numbers. operator_id/vehicle_number uniquely identifies the vehicle.
Note: Vehicle numbers must be exactly 5 digits long in the topic filter, so prefix them with zeroes if needed.
route_idThe ID of the route the vehicle is running on. This matches route_id in GTFS (field gtfsId of Route in the routing API).
direction_idThe line direction of the trip, either 1 or 2.
Note: This does not exactly match direction_id in GTFS or the routing API.
Value 1 here is same as 0 in GTFS and the Routing API.
Value 2 here is same as 1 in GTFS and the Routing API.
headsignThe destination name, e.g. Aviapolis. Note: This does NOT match trip_headsign in GTFS exactly.
start_timeThe scheduled start time of the trip, i.e. the scheduled departure time from the first stop of the trip. The format follows HH:mm in 24-hour local time, not the 30-hour overlapping operating days present in GTFS.
next_stopThe ID of next stop or station. Updated on each departure from or passing of a stop. EOL (end of line) after final stop and empty if the vehicle is leaving HSL area. Matches stop_id in GTFS (value of gtfsId field, without HSL: prefix, in Stop type in the routing API).
geohash_levelThe geohash level represents the magnitude of change in the GPS coordinates since the previous message from the same vehicle. More exactly, geohash_level is equal to the minimum of the digit positions of the most significant changed digit in the latitude and the longitude since the previous message. For example, if the previous message has value (60.12345, 25.12345) for (lat, long) and the current message has value (60.12499, 25.12388), then the third digit of the fractional part is the most significant changed digit and geohash_level has value 3.
However, geohash_level value 0 is overloaded. geohash_level is 0 if:
  • the integer part of the latitude or the longitude has changed,
  • the previous or the current message has null for coordinates or
  • the non-location parts of the topic have changed, e.g. when a bus departs from a stop.
By subscribing to specific geohash levels, you can reduce the amount of traffic into the client. By only subscribing to level 0 the client gets the most important status changes. The rough percentages of messages with a specific geohash_level value out of all ongoing messages are:
  • 0: 3 %
  • 1: 0.09 %
  • 2: 0.9 %
  • 3: 8 %
  • 4: 43 %
  • 5: 44 %
geohashThe latitude and the longitude of the vehicle. The digits of the integer parts are separated into their own level in the format <lat>;<long>, e.g. 60;24. The digits of the fractional parts are split and interleaved into a custom format so that e.g. (60.123, 24.789) becomes 60;24/17/28/39. This format enables subscribing to specific geographic boundaries easily.
If the coordinates are missing, geohash_level and geohash have the concatenated value 0////.
This geohash scheme is greatly simplified from the original geohash scheme
sidJunction ID, corresponds to sid in the payload. Only available for tlr and tla event types, empty for other event types.
\n

Event types

\n

The most notable change in HFP 2.0 is introduction of different types of messages. Whereas HFP 1.0 had only vehicle position messages, in HFP 2.0 vehicles also send messages from different types of event happening during the journey (for example, arriving to a stop etc.).

\n

Note: events are not available for metros (metro), U-line buses (ubus), robot buses (robot) and ferries (ferry).

\n

List of possible events:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Event typeDescription
vpVehicle position
dueVehicle will soon arrive to a stop
arrVehicle arrives inside of a stop radius
depVehicle departs from a stop and leaves the stop radius
arsVehicle has arrived to a stop
pdeVehicle is ready to depart from a stop
pasVehicle passes through a stop without stopping
waitVehicle is waiting at a stop
dooDoors of the vehicle are opened
docDoors of the vehicle are closed
tlrVehicle is requesting traffic light priority
tlaVehicle receives a response to traffic light priority request
daDriver signs in to the vehicle
doutDriver signs out of the vehicle
baDriver selects the block that the vehicle will run
boutDriver signs out from the selected block (usually from a depot)
vja  Vehicle signs in to a service journey (i.e. a single public transport journey from location A to location B, also known as trip)
vjoutVehicle signs off from a service journey, after reaching the final stop
\n

The payload

\n

The payload is an UTF-8 encoded, compact JSON string. The JSON contains a single key-value pair where the key is equivalent to the event type of the message and the value is an object describing the event. Fields of the event object depend on event type.

\n

Here is an example of a vehicle position message (with VP key):

\n
{\n  \"VP\": {\n    \"desi\": \"551\",\n    \"dir\": \"1\",\n    \"oper\": 12,\n    \"veh\": 10,\n    \"tst\": \"2019-05-23T14:15:16.000Z\",\n    \"tsi\": 1416308975,\n    \"spd\": 12.5,\n    \"hdg\": 354,\n    \"lat\": 24.9435,\n    \"long\": 60.1967,\n    \"acc\": -12.34,\n    \"dl\": 600,\n    \"odo\": 45.12,\n    \"drst\": 0,\n    \"oday\": \"2019-05-23\",\n    \"jrn\": 1,\n    \"line\": 264,\n    \"start\": \"13:40\",\n    \"loc\": \"GPS\",\n    \"stop\": null,\n    \"route\": \"2551\",\n    \"occu\": 0\n  }\n}
\n

The fields are described below:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldTypeNot available on eventsDescription
desiStringda, dout, ba, bout Route number visible to passengers.
dirStringda, dout, ba, bout Route direction of the trip. After type conversion matches direction_id in GTFS and the topic. Either \"1\" or \"2\".
operInteger Unique ID of the operator running the trip (i.e. this value can be different than the operator ID in the topic, for example if the service has been subcontracted to another operator).
The unique ID does not have prefix zeroes here.
vehInteger Vehicle number that can be seen painted on the side of the vehicle, often next to the front door. Different operators may use overlapping vehicle numbers. Matches vehicle_number in the topic except without the prefix zeroes.
tstStringUTC timestamp with millisecond precision from the vehicle in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZ).
tsiIntegerUnix time in seconds from the vehicle.
spdFloating-point number Speed of the vehicle, in meters per second (m/s).
hdgInteger Heading of the vehicle, in degrees (⁰) starting clockwise from geographic north. Valid values are on the closed interval [0, 360].
latFloating-point numberWGS 84 latitude in degrees.
null if location is unavailable.
longFloating-point numberWGS 84 longitude in degrees.
null if location is unavailable.
accFloating-point number Acceleration (m/s^2), calculated from the speed on this and the previous message. Negative values indicate that the speed of the vehicle is decreasing.
dlIntegerda, dout, ba, boutOffset from the scheduled timetable in seconds (s). Negative values indicate lagging behind the schedule, positive values running ahead of schedule.
odoIntegerThe odometer reading in meters (m) since the start of the trip. Currently the values not very reliable.
drstIntegerDoor status.
0 if all the doors are closed.
1 if any of the doors are open.
odayStringda, doutOperating day of the trip. The exact time when an operating day ends depends on the route. For most routes, the operating day ends at 4:30 AM on the next day. In that case, for example, the final moment of the operating day \"2018-04-05\" would be at 2018-04-06T04:30 local time.
jrnIntegerda, dout, ba, boutInternal journey descriptor, not meant to be useful for external use.
lineIntegerda, dout, ba, bout Internal line descriptor, not meant to be useful for external use.
startStringda, dout, ba, boutScheduled start time of the trip, i.e. the scheduled departure time from the first stop of the trip. The format follows HH:mm in 24-hour local time, not the 30-hour overlapping operating days present in GTFS. Matches start_time in the topic.
locStringLocation source, either GPS, ODO, MAN, DR or N/A.
  • GPS - location is received from GPS
  • ODO - location is calculated based on odometer value
  • MAN - location is specified manually
  • DR - location is calculated using dead reckoning (used in tunnels and other locations without GPS signal)
  • N/A - location is unavailable
stop Stringda, dout, ba, boutID of the stop related to the event (e.g. ID of the stop where the vehicle departed from in case of dep event or the stop where the vehicle currently is in case of vp event).
null if the event is not related to any stop.
route Stringda, dout, ba, boutID of the route the vehicle is currently running on. Matches route_id in the topic.
occuIntegerda, dout, ba, boutInteger describing passenger occupancy level of the vehicle. Valid values are on interval [0, 100].

Currently passenger occupancy level is only available for Suomenlinna ferries as a proof-of-concept. The value will be available shortly after departure when the ferry operator has registered passenger count for the journey.

For other vehicles, currently only values used are 0 (= vehicle has space and is accepting passengers) and 100 (= vehicle is full and might not accept passengers)
 seqIntegerSequence number of the unit when the journey is operated with a vehicle that consists of multiple units (e.g. metros, trains). Sequence number starts from 1.
Note: seq is currently only available for metros.
label StringUser visible label that helps to identify the vehicle. Currently available only for Suomenlinna ferries with values being vessel names.
ttarr Stringvp, da, dout, ba, bout, vja, vjoutUTC timestamp of scheduled arrival time to the stop
ttdep Stringvp, da, dout, ba, bout, vja, vjoutUTC timestamp of scheduled departure time from the stop
 dr-typeIntegerOther than da, dout, ba, bout, vja, vjout Type of the driver, either 0 or 1.
  • 0 = service technician
  • 1 = normal driver
tlp-requestid IntegerOther than tlr, tlaTraffic light priority request ID. Valid values are on interval [0, 255].
tlp-requesttypeStringOther than tlrTraffic light priority request type, either NORMAL, DOOR_CLOSE, DOOR_OPEN or ADVANCE.
tlp-prioritylevelStringOther than tlrPriority level of a traffic light priority request. Either normal, high or norequest.
tlp-reason String Other than tlrReason for not sending a traffic light priority request. Either GLOBAL, AHEAD, LINE or PRIOEXEP.
 tlp-att-seq IntegerOther than tlrTraffic light priority request attempt sequence number
tlp-decisionStringOther than tlaResponse for traffic light priority request. Either ACK or NAK.
\n

Also the following fields are available on traffic light priority request events (event type tlr), but they probably have no use for 3rd party users:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldTypeDescription
sidIntegerJunction ID
signal-groupidIntegerSignal group (a group of traffic lights at a junction) ID
tlp-signalgroupnbrIntegerID of the specific traffic light in a signal group. Possibly negative
tlp-line-configidIntegerID of the line configuration in DOI
tlp-point-configid IntegerPoint configuration ID
tlp-frequencyIntegerFrequency used for traffic light prority request
tlp-protocolStringProtocol used for traffic light priority request. Either MQTT or KAR-MQTT
\n

Operators

\n

The numerical values for the different transit operators are listed below:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
operOperator name
6Oy Pohjolan Liikenne Ab2
12Koiviston Auto Oy
17Tammelundin Liikenne Oy
18Oy Pohjolan Liikenne Ab
20Bus Travel Åbergin Linja Oy
21Bus Travel Oy Reissu Ruoti
22Nobina Finland Oy
30Savonlinja Oy
36Nurmijärven Linja Oy
40HKL-Raitioliikenne
47Taksikuljetus Oy
50HKL-Metroliikenne
51Korsisaari Oy
54V-S Bussipalvelut Oy
58Koillisen Liikennepalvelut Oy
59Tilausliikenne Nikkanen Oy
60Suomenlinnan Liikenne Oy
64Taksikuljetus Harri Vuolle Oy
89Metropolia
90VR Oy
130Matkahuolto1
195Siuntio1
\n

1Multiple smaller operators operate under this operator ID
\n2This value is present only in the oper field of the payload. Operator 6 is the same as 18.

\n

Examples

\n

Topics

\n

The HFP topic format forms a tree.\nBy combining wildcards with several topic filters in one MQTT SUBSCRIBE packet you can carve quite interesting subsets of the tree to serve different use cases.\nAs the MQTT broker handles the resolving of the topic filters, handling messages for complicated subscriptions does not have inherent overhead in the client compared to simple subscriptions.\nGo hog wild.

\n

Command line

\n

Below are sample subscriptions utilizing MQTT.js command line tools.
\nMQTT.js command line tools can be installed with:

\n
npm install -g mqtt
\n

If you insist on using mosquitto, try this for TLS access:

\n
mosquitto_sub --capath \"/etc/ssl/certs/\" -h mqtt.hsl.fi -p 8883 -v -t \"/hfp/v2/journey/#\"
\n

A situational overview

\n

To get just the most significant vehicle position updates, use:

\n
mqtt subscribe -h mqtt.hsl.fi -l mqtts -p 8883 -v \\\n  -t \"/hfp/v2/journey/ongoing/vp/+/+/+/+/+/+/+/+/0/#\"
\n

A route in one direction

\n

To subscribe to all vehicle position messages from vehicles currently on the route 551 (route_short_name in GTFS) going in direction 1, subscribe to the corresponding route_id 2551:

\n
mqtt subscribe -h mqtt.hsl.fi -l mqtts -p 8883 -v \\\n  -t \"/hfp/v2/journey/ongoing/vp/+/+/+/2551/1/#\"
\n

All trams

\n

Subscribe to all vehicle position messages from trams with:

\n
mqtt subscribe -h mqtt.hsl.fi -l mqtts -p 8883 -v \\\n  -t \"/hfp/v2/journey/ongoing/vp/tram/#\"
\n

A certain trip

\n

Subscribe to vehicle position messages of a certain trip, even slightly before the driver has signed onto the trip:

\n
mqtt subscribe -h mqtt.hsl.fi -l mqtts -p 8883 -v \\\n  -t \"/hfp/v2/journey/+/vp/+/+/+/1069/1/+/07:20/#\"
\n

Or if your users would find it confusing to see a vehicle going in the wrong direction, subscribe to the ongoing messages only:

\n
mqtt subscribe -h mqtt.hsl.fi -l mqtts -p 8883 -v \\\n  -t \"/hfp/v2/journey/ongoing/vp/+/+/+/1069/1/+/07:20/#\"
\n

All vehicles arriving to a certain stop

\n

To subscribe to all vehicles arriving to a certain stop, use:

\n
mqtt subscribe -h mqtt.hsl.fi -l mqtts -p 8883 -v \\\n  -t \"/hfp/v2/journey/ongoing/arr/+/+/+/+/+/+/+/1293140/#\"
\n

Note: depending on the current traffic situation, you might have to wait a while to receive data

\n

Door status of a certain vehicle

\n

To subscribe to door status of a certain vehicle, use:

\n
mqtt subscribe -h mqtt.hsl.fi -l mqtts -p 8883 -v \\\n  -t \"/hfp/v2/journey/ongoing/doo/+/0012/01312/#\" \\\n  -t \"/hfp/v2/journey/ongoing/doc/+/0012/01312/#\"
\n

Note: you will have to change operator ID and vehicle number in the topic if vehicle 0012/01312 is not running currently.

\n

A bounding box

\n\n

Let's assume that you wish to subscribe to all action inside the following GeoJSON Polygon:

\n
{\n  \"type\": \"Feature\",\n  \"geometry\": {\n    \"type\": \"Polygon\",\n    \"coordinates\": [\n      [\n        [24.9578905105, 60.1836538254],\n        [24.9646711349, 60.1836538254],\n        [24.9646711349, 60.1894146967],\n        [24.9578905105, 60.1894146967],\n        [24.9578905105, 60.1836538254]\n      ]\n    ]\n  }\n}
\n

The box bounded by the latitude interval [60.18, 60.19[ and the longitude interval [24.95, 24.97[ corresponds with the following HFP subscription:

\n
mqtt subscribe -h mqtt.hsl.fi -l mqtts -p 8883 -v \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/85/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/86/#\"
\n

For the precision of one more digit of latitude and longitude, one would need 56 topic filters for the bounding box:

\n
mqtt subscribe -h mqtt.hsl.fi -l mqtts -p 8883 -v \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/85/37/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/85/38/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/85/39/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/86/30/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/86/31/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/86/32/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/86/33/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/86/34/#\" \\\n  \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/85/47/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/85/48/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/85/49/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/86/40/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/86/41/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/86/42/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/86/43/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/86/44/#\" \\\n  \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/85/57/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/85/58/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/85/59/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/86/50/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/86/51/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/86/52/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/86/53/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/86/54/#\" \\\n  \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/85/67/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/85/68/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/85/69/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/86/60/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/86/61/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/86/62/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/86/63/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/86/64/#\" \\\n  \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/85/77/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/85/78/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/85/79/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/86/70/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/86/71/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/86/72/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/86/73/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/86/74/#\" \\\n  \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/85/87/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/85/88/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/85/89/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/86/80/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/86/81/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/86/82/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/86/83/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/86/84/#\" \\\n  \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/85/97/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/85/98/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/85/99/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/86/90/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/86/91/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/86/92/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/86/93/#\" \\\n  -t \"/hfp/v2/journey/ongoing/+/+/+/+/+/+/+/+/+/+/60;24/19/86/94/#\"
\n

There is no need to restrict yourself to just one rectangle like above, though.

\n

For example, you could try to generate an HFP subscription for all ongoing vehicles in the minimal geographic area encompassing the Kontula borough with the precision of two digits in the fractional part.

\n

Querying a trip corresponding to a vehicle position

\n

The Routing API can be used to query a trip correspoding to a vehicle position message.

\n\n

For example, from the following vehicle position message

\n
{\n  \"VP\": {\n    \"desi\":\"550\",\n    \"dir\":\"1\",\n    \"oper\":12,\n    \"veh\":1306,\n    \"tst\":\"2019-06-28T09:49:01.457Z\",\n    \"tsi\":1561715341,\n    \"spd\":12.29,\n    \"hdg\":47,\n    \"lat\":60.182376,\n    \"long\":24.825781,\n    \"acc\":0.44,\n    \"dl\":-2,\n    \"odo\":24627,\n    \"drst\":0,\n    \"oday\":\"2019-06-28\",\n    \"jrn\":99,\n    \"line\":261,\n    \"start\":\"11:57\",\n    \"loc\":\"GPS\",\n    \"stop\":null,\n    \"route\":\"2550\",\n    \"occu\":0\n  }\n}
\n

it is possible to parse:

\n\n

Note:

\n
    \n
  1. \n

    Vehicle position messages use different direction id than the Routing API

    \n\n
    2. \n
  2. \n

    Departure time must be in seconds

    \n\n
    3. \n
  3. \n

    Due to a bug in the vehicle position API, some route ids don't match the route id in the routing API

    \n\n
    4. \n
\n

For example, the following query checks if the vehicle, which sent the vehicle position message above, is wheelchair accessible:

\n
{\n  fuzzyTrip(route: \"HSL:2550\", direction: 0, date: \"2019-06-28\", time: 43020) {\n    route {\n      shortName\n    }\n    wheelchairAccessible\n  }\n}
\n\n

Further reading

\n","tableOfContents":"","excerpt":"Most of the vehicles in the HSL area should publish their status, including their position, once per second.\nThe devices of the end users, e.g. smartphones, may subscribe to receive the relevant…"}},"pageContext":{"slug":"/en/developers/apis/5-realtime-api/vehicle-positions/high-frequency-positioning/"}},"staticQueryHashes":["3675773199","4050193485"]}