Package com.cercalia.sdk.services

Class SnapToRoadService

java.lang.Object
com.cercalia.sdk.CercaliaClient
com.cercalia.sdk.services.SnapToRoadService
public class SnapToRoadService extends CercaliaClient
SnapToRoadService - GPS Track Map Matching using Cercalia Geomtrack API.

This service matches raw GPS coordinates to the road network, providing "snapped" geometries that follow actual roads. Essential for fleet management, vehicle tracking, and trip analysis applications. 


 SnapToRoadService service = new SnapToRoadService(config);
 
 // 1. Basic map matching
 List<SnapToRoadPoint> track = Arrays.asList(
     SnapToRoadPoint.of(41.3851, 2.1734),
     SnapToRoadPoint.of(41.3870, 2.1700),
     SnapToRoadPoint.of(41.3890, 2.1680)
 );
 SnapToRoadResult result = service.match(track, SnapToRoadOptions.defaults());
 
 // 2. With speeding detection
 SnapToRoadOptions options = SnapToRoadOptions.builder()
     .speeding(true)
     .speedTolerance(10) // km/h
     .build();
 SnapToRoadResult speedingResult = service.match(track, options);
See Also:

  • Constructor Details

    • SnapToRoadService

      public SnapToRoadService(@NotNull @NotNull CercaliaConfig config)
      Creates a new SnapToRoadService with the specified configuration.
      Parameters:
      config - the Cercalia configuration

  • Method Details

    • match

      @NotNull public @NotNull SnapToRoadResult match(@NotNull @NotNull List<SnapToRoadPoint> points, @NotNull @NotNull SnapToRoadOptions options)
      Match GPS track points to the road network.

      Takes an array of GPS points and returns road-matched geometries. Points should be in temporal order for best matching results.

      Parameters:
      points - array of GPS track points (minimum 2 required)
      options - map matching options
      Returns:
      matched road segments with distances and optional speeding info
      Throws:
      CercaliaException - if fewer than 2 points provided or API error

    • matchAsync

      @NotNull public @NotNull CompletableFuture<SnapToRoadResult> matchAsync(@NotNull @NotNull List<SnapToRoadPoint> points, @NotNull @NotNull SnapToRoadOptions options)
      Match GPS track points to the road network asynchronously.
      Parameters:
      points - array of GPS track points (minimum 2 required)
      options - map matching options
      Returns:
      CompletableFuture with matched road segments

    • matchWithGroups

      @NotNull public @NotNull SnapToRoadResult matchWithGroups(@NotNull @NotNull List<Coordinate> coords, int groupSize, @NotNull @NotNull SnapToRoadOptions options)
      Match GPS track with automatic segment grouping by attribute.

      Convenience method that automatically assigns attributes to points for segment grouping. Useful for identifying distinct trip legs.

      Parameters:
      coords - array of GPS coordinates
      groupSize - number of points per group (default: 10)
      options - map matching options
      Returns:
      matched segments grouped by attribute

    • matchWithGroupsAsync

      @NotNull public @NotNull CompletableFuture<SnapToRoadResult> matchWithGroupsAsync(@NotNull @NotNull List<Coordinate> coords, int groupSize, @NotNull @NotNull SnapToRoadOptions options)
      Match GPS track with automatic segment grouping by attribute asynchronously.
      Parameters:
      coords - array of GPS coordinates
      groupSize - number of points per group
      options - map matching options
      Returns:
      CompletableFuture with matched segments grouped by attribute

    • matchWithSpeedingDetection

      @NotNull public @NotNull SnapToRoadResult matchWithSpeedingDetection(@NotNull @NotNull List<SnapToRoadPoint> points, int toleranceKmh)
      Match GPS track with speed data for violation detection.

      Convenience method that enables speeding detection with sensible defaults.

      Parameters:
      points - array of GPS points with speed data
      toleranceKmh - speed tolerance in km/h (default: 10)
      Returns:
      matched segments with speeding flags

    • matchWithSpeedingDetectionAsync

      @NotNull public @NotNull CompletableFuture<SnapToRoadResult> matchWithSpeedingDetectionAsync(@NotNull @NotNull List<SnapToRoadPoint> points, int toleranceKmh)
      Match GPS track with speed data for violation detection asynchronously.
      Parameters:
      points - array of GPS points with speed data
      toleranceKmh - speed tolerance in km/h
      Returns:
      CompletableFuture with matched segments with speeding flags

    • matchSimplified

      @NotNull public @NotNull SnapToRoadResult matchSimplified(@NotNull @NotNull List<SnapToRoadPoint> points, int tolerance)
      Get a simplified/generalized track matching.

      Convenience method for getting a simplified geometry suitable for display. Higher tolerance values produce simpler geometries with fewer points.

      Parameters:
      points - array of GPS points
      tolerance - simplification tolerance in meters (default: 50)
      Returns:
      matched segments with simplified geometries

    • matchSimplifiedAsync

      @NotNull public @NotNull CompletableFuture<SnapToRoadResult> matchSimplifiedAsync(@NotNull @NotNull List<SnapToRoadPoint> points, int tolerance)
      Get a simplified/generalized track matching asynchronously.
      Parameters:
      points - array of GPS points
      tolerance - simplification tolerance in meters
      Returns:
      CompletableFuture with matched segments with simplified geometries