@cercalia/sdk
    Preparing search index...

    Class SnapToRoadService

    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.

    • Map Matching: Snap GPS points to the nearest road network
    • Speed Detection: Identify speed violations based on road limits
    • Segment Grouping: Group results by custom attributes
    • Geometry Simplification: Control output complexity with tolerance
    • Fleet vehicle tracking
    • Trip reconstruction from GPS logs
    • Speed violation analysis
    • Road usage statistics
    const snapToRoad = new SnapToRoadService(config);

    // Basic map matching
    const track = [
      { coord: { lat: 41.3851, lng: 2.1734 } },
      { coord: { lat: 41.3870, lng: 2.1700 } },
      { coord: { lat: 41.3890, lng: 2.1680 } }
    ];
    const result = await snapToRoad.match(track);

    // With speed detection
    const trackWithSpeed = [
      { coord: { lat: 41.3851, lng: 2.1734 }, speed: 50 },
      { coord: { lat: 41.3870, lng: 2.1700 }, speed: 120 }, // Possible violation
      { coord: { lat: 41.3890, lng: 2.1680 }, speed: 60 }
    ];
    const result = await snapToRoad.match(trackWithSpeed, { 
      speeding: true,
      speedTolerance: 10 
    });

    https://docs.cercalia.com/docs/cercalia-webservices/geomtrack/

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Properties

    config

    Methods

    match matchSimplified matchWithGroups matchWithSpeedingDetection request

    Constructors

    Properties

    config: CercaliaConfig

    Configuration for the Cercalia API connection.

    Methods

    • 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

      Returns Promise<SnapToRoadResult>

      Matched road segments with distances and optional speeding info

      Error if fewer than 2 points provided or API error

      // Simple track matching
      const result = await service.match([
        { coord: { lat: 41.3851, lng: 2.1734 } },
        { coord: { lat: 41.3870, lng: 2.1700 } }
      ]);

      logger.info(result.totalDistance); // 0.25 km
      logger.info(result.segments[0].wkt); // 'LINESTRING(...)'

      // Track with speed and direction data
      const result = await service.match([
        { coord: { lat: 41.3851, lng: 2.1734 }, speed: 50, compass: 45 },
        { coord: { lat: 41.3870, lng: 2.1700 }, speed: 60, compass: 50 }
      ], {
        speeding: true,
        speedTolerance: 10,
        weight: 'time'
      });

    • 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: SnapToRoadPoint[]

        Array of GPS points

      • tolerance: number = 50

        Simplification tolerance in meters (default: 50)

      Returns Promise<SnapToRoadResult>

      Matched segments with simplified geometries

      // Get simplified track for map display
      const result = await service.matchSimplified(rawGpsPoints, 100);
      // Result will have fewer points, suitable for web display

    • 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

      • points: Coordinate[]

        Array of GPS coordinates

      • groupSize: number = 10

        Number of points per group (default: 10)

      • options: SnapToRoadOptions = {}

        Map matching options

      Returns Promise<SnapToRoadResult>

      Matched segments grouped by attribute

      // Group every 5 points into a segment
      const result = await service.matchWithGroups(trackPoints, 5, {
        speeding: true
      });

      // Each segment will have a unique attribute (A, B, C, ...)
      result.segments.forEach(seg => {
        logger.info(`Segment ${seg.attribute}: ${seg.distance} km`);
      });

    • Match GPS track with speed data for violation detection

      Convenience method that enables speeding detection with sensible defaults.

      Parameters

      • points: SnapToRoadPoint[]

        Array of GPS points with speed data

      • toleranceKmh: number = 10

        Speed tolerance in km/h (default: 10)

      Returns Promise<SnapToRoadResult>

      Matched segments with speeding flags

      const trackWithSpeed = [
        { coord: { lat: 41.38, lng: 2.17 }, speed: 50 },
        { coord: { lat: 41.39, lng: 2.16 }, speed: 130 } // Possible violation
      ];

      const result = await service.matchWithSpeedingDetection(trackWithSpeed, 10);

      const violations = result.segments.filter(s => s.speeding);
      logger.info(`Found ${violations.length} speeding segments`);

    • Executes a generic request to the Cercalia API.

      Type Parameters

      • T

      Parameters

      • params: Record<string, string>

        Query parameters for the API request.

      • operationName: string = 'Cercalia Request'

        Human-readable name for logging and debugging.

      • OptionalbaseUrl: string

        Optional override for the base API URL.

      Returns Promise<T>

      A promise resolving to the parsed API response.

      Error with code '30006' when no results are found.

      Error for HTTP errors or invalid JSON responses.

      const response = await this.request<MyResponse>(
        { cmd: 'cand', adr: 'Gran Via 1' },
        'Geocoding'
      );

    Settings

    Member Visibility

    On This Page

    Key FeaturesUse CasesUsage Examples
    Constructors
    Properties
    Methods