Pass-Through Detection API

Pass-Through detection Need to recognize when a vehicle passes a specific location? Or want to be notified when a vehicle enters or leaves a defined zone?

The Kapsch Pass-Through detection API matches a given set of GPS points to the road network and detects when a vehicle passes a predefined location. The API is capable of detecting passage through individual locations but can also be set up to create geofences – virtual borders around a geographical zone. Vehicle direction is considered which allows users to differentiate between exit and entry events. Corridor fencing enables notifications whenever a vehicle leaves a predefined route.

Detecting the passage of virtual barriers allows you to:
  • Detect rental vehicles from going outside the agreed-upon areas
  • Alert customers that their delivery is approaching
  • Notify drivers when they are approaching a toll section
  • Charge toll based on vehicle passage
  • Warn vehicle owners of possible theft or unauthorized usage

Our Pass-Through Detection API is based on the Open Street Map road network - the most accurate, up-to-date, and feature-rich open-source geodata source, with over 1.5 million contributors across the world.

The API is based on Map Matching location data to the road network. As a result, the API:
  • Creates a very accurate representation of where a vehicle has driven.
  • Provides an exact timestamp, speed, and direction of each passage.
  • Returns both a map matched result of the route and a passage position report.
  • Offers the capability to retain vehicle route context between API calls.

You want to know what's new? See API changelog

Get started!

Base URL address:{device_id}
Use POST method on above endpoint and send data as shown in request example below.

Endpoint requires authentication. Account provided to you by Kapsch TrafficCom needs to be used for access. Contact Kapsch TrafficCom to acquire the required credentials and the identity platform URL.

OAuth 2.0 authentication method is supported. For reference how to use OAuth 2.0 please refer to the Identity platform and OAuth 2.0 Resource Owner Password Credentials documentation.

Following parameter can be used:

  • URL path parameter "device_id" (required) - Is a unique identifier for a device
  • query parameter "include_shape" - Whether the response includes route and mapped points shape in the response for visualization or debugging. For production use this should be set to false or omitted.
  • query parameter "return_link_identifiers" - Set this to true if client is interested in road network identifiers.

Request Body

  • "gnss_positions" (required) - GNSS track to be matched. Provide at least 3 and maximum 250 positions.
    • "point/lat" - latitude of GNSS reading
    • "point/lon" - longitude of GNSS reading
    • "heading" - heading of GNSS reading in degrees (0.0-359.9)
    • "timestamp" - UTC time. Conforms to ISO 8601 specification for date/time representation.
    • "speed" - vehicle speed at the time of GNSS reading in meters per second (mps)
    • "accuracy" - horizontal accuracy of every GNSS position in meters. E.g. value of 3m means that position is within 9m radius with 99.73% probability. This value is not to be confused with HDOP. If horizontal accuracy is not available from GNSS device, please set this value to 0 or omit the field for every position to disable horizontal accuracy in the pass-through detection algorithm.
  • "passage_position_definitions" (required) - List of passage point definitions (point on a road where device passage needs to be detected).
    • "custom_id" - set your external ID you would like to get back to identify the passage of this position mapped to a road
    • "point/lat" - latitude of the position to be mapped to the road for passage detection
    • "point/lon" - longitude of the position to be mapped to the road for passage detection
    • "heading" - the approximately direction/heading of vehicle passage to be detected. If bi-directional detection is needed please define two passage positions - one for each direction
  • "device_context" - Device context from previous API call to continue the route matching from previous already matched route for the same device.
  • "flush_device" - Returns matched positions even if the confidence level is low. Set this to 'false' if you want to store and return device context at client.

Response Body

  • "map_version" - the GLP map version that is currently used. If you see the same value between responses this means that link IDs have not changed
  • "device_context" - encoded device context. Send this string as 'device_context' in the next request to this API to keep the x-batching device context
  • "matched_points" - the list of map matched points from the input GNSS vehicle track
    • "accuracy" - horizontal accuracy in meters provided by GNSS device
    • "confidence" - level of confidence of map matching, from 0 to 1
    • "point/lat" - latitude of original position
    • "point/lon" - longitude of original position
    • "matched_point/lat" - latitude of original position
    • "matched_point/lon" - longitude of original position
    • "matched_link_id" - road link ID to which the position was matched to. If road way doesn't change in geometry the link ID is persistent between road network versions
    • "match_offset_on_link" - how far into the link the matched position was matched to this road link
    • "timestamp" - timestamp of original position
    • "warning_code" - warning code for map matching
  • "matched_route_shape" - geometry of the matched vehicle route in line_string format representation
  • "passage_position_reports" - the report of the detected and not detected vehicle passages of the defined passage positions
    • "mapping_confidence" - the confidence of the mapping of the original passage position definition to the road network (0.0-1.0). The higher the number the less likely is that the passage position was incorrectly mapped to a road link.
    • "custom_id" - the custom ID that was provided in the request
    • "mapped_link_id" - the ID of the road link to which the passage position was mapped to
    • "mapped_link_offset" - the offset on the road link to which the passage position was mapped to
    • "mapped_point/lat" - the latitude of the mapped position on the road link
    • "mapped_point/lon" - the longitude of the mapped position on the road link
    • "passed" - true/false in case the passage was detected
    • "passed_at" - interpolated time of the exact vehicle passage based on map matched vehicle route
    • "pass_confidence" - the confidence of vehicle passage
    • "mapped_link_shape" - the mapped link geometry in line_string format

Request example

Use HTTP POST method
and send below request body. Multiple intermediate points are supported.

Response example