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: https://api.geo-location-platform.com/roadnetwork/europe/v1/pass-through-detection/{device_id}
Use POST method on above endpoint and send data as shown in request example below.
Endpoint requires authentication. API_KEY needs to be provided to you by Kapsch TrafficCom. Please contact us for API usage conditions and to acquire your API_KEY. Usage of 'demo' API_KEY in examples on this page is not allowed for your productive systems.

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 https://api.geo-location-platform.com/roadnetwork/europe/v1/pass-through-detection/2963dcf0-62a3-4f7d-8753-5d29b627db41?include_shape=true&return_link_identifiers=true
and send below request body. Multiple intermediate points are supported.

Response example