Route Matching

Note: For track recording and rectification needs, we strongly recommend using the Hunting SDK or Hunting Service API provided by the AMAP Open Platform. The map SDK will gradually discontinue maintenance of the track rectification interface in future versions.

Overview

Track rectification helps you simplify and correct recorded driving track points, matching them to roads for smooth rendering and calculating driving distance (supported in map SDK V3.4.0 and above). It can also record real driving tracks when combined with AMAP positioning (supported in map SDK V5.1.0 and above).

Important: This feature currently only supports correcting driving tracks to roads.

Track Rectification with Positioning (Supported from V5.2.0)

Step 1: Initialize LBSTraceClient

Start recording the track. The SDK records a point every 2 seconds and sends a batch of 5 points for rectification with each request.

LBSTraceClient lbsTraceClient = LBSTraceClient.getInstance(context);

Step 2: Start Track Rectification

lbsTraceClient.startTrace(TraceListener); // Start collecting data. Pass a status callback listener.

Step 3: Parse the Result

void onTraceStatus(List<TraceLocation> locations, List<LatLng> rectifications, String errorInfo);
// locations: Track points from positioning
// rectifications: Corrected track points
// errorInfo: Error information for track rectification

Step 4: Stop Track Rectification

lbsTraceClient.stopTrace(); // Call this method when track rectification is no longer needed (e.g., trip ends)

Track Rectification with Your Own Data

Step 1: Initialize LBSTraceClient

mTraceClient = new LBSTraceClient(this.getApplicationContext());

Step 2: Construct the Track Point List

Build a list of track points using the TraceLocation format. The following table describes the available methods for setting TraceLocation information.

Important:

- Missing required fields will cause rectification to fail. Missing optional fields may affect the final result. Providing as much information as possible is the best way to ensure a smooth track. We recommend using high-accuracy positioning data with speed and bearing values from the Android Location SDK.

- The longitude and latitude points must be within China. Track rectification does not support coordinates outside China.

Step 3: Perform Track Rectification

Track rectification supports multiple coordinate systems (AMAP, GPS raw coordinates, and Baidu) and can process multiple tracks simultaneously.

mTraceClient.queryProcessedTrace(mSequenceLineID, mTraceList, mCoordinateType, this);

Step 4: Retrieve the Corrected Data

1. Implement the TraceListener Interface

Pass the TraceListener as a parameter to the track rectification method. Its callbacks provide the corrected track points and total distance.

2. Track Rectification Completion Callback

The onFinished callback is triggered when all track points have been successfully rectified.

Example:

/**
 * Track rectification completion callback
 */
@Override
public void onFinished(int lineID, List<LatLng> linepoints, int distance, int waitingtime) {
    Log.d(TAG, "onFinished");
    Toast.makeText(this.getApplicationContext(), "onFinished", Toast.LENGTH_SHORT).show();
    if (mOverlayList.containsKey(lineID)) {
        TraceOverlay overlay = mOverlayList.get(lineID);
        overlay.setTraceStatus(TraceOverlay.TRACE_STATUS_FINISH);
        overlay.setDistance(distance);
        overlay.setWaitTime(waitingtime);
        setDistanceWaitInfo(overlay);
    }
}

3. Track Rectification Failure Callback

The onRequestFailed callback is triggered when rectification fails due to parameter errors. Common causes include:

- Network is unavailable.

- The input track contains only one point.

Example:

/**
 * Track rectification failure callback
 */
@Override
public void onRequestFailed(int lineID, String errorInfo) {
    Log.d(TAG, "onRequestFailed");
    Toast.makeText(this.getApplicationContext(), errorInfo, Toast.LENGTH_SHORT).show();
    if (mOverlayList.containsKey(lineID)) {
        TraceOverlay overlay = mOverlayList.get(lineID);
        overlay.setTraceStatus(TraceOverlay.TRACE_STATUS_FAILURE);
        setDistanceWaitInfo(overlay);
    }
}

4. Track Rectification Progress Callback

Track data is processed in segments. The onTraceProcessing callback is triggered after each segment is rectified.

Segment-based processing offers two advantages:

- Reduces waiting time for large amounts of track data.

- Provides partial results even if some segments fail rectification.

Example:

/**
 * Track rectification progress callback
 */
@Override
public void onTraceProcessing(int lineID, int index, List<LatLng> segments) {
    Log.d(TAG, "onTraceProcessing");
    if (segments == null) {
        return;
    }
    if (mOverlayList.containsKey(lineID)) {
        TraceOverlay overlay = mOverlayList.get(lineID);
        overlay.setTraceStatus(TraceOverlay.TRACE_STATUS_PROCESSING);
        overlay.add(segments);
    }
}

Important Notes

1. As a feature of the map SDK, a valid AMAP Key must be set to use track rectification correctly.

2. If you have doubts about the rectification results (e.g., inaccurate distance calculation, incorrect track), convert your track points to a standard JSON file and submit it to us via a ticket. Note: We only accept track point data in a format we can verify.

a. Use http://tool.oschina.net/codeformat/json to format the JSON file.

b. Verify that the field names match the table below. If they differ, rename them accordingly.

c. Submit the file to us via a ticket.