Route Matching

> Note: For trajectory recording and correction requirements, we strongly recommend using the AMAP Track SDK or the AMAP Track Service API. Future versions of the Map SDK will gradually discontinue maintenance of the trace correction interface.

Overview

Trace correction helps you simplify, correct, and match recorded trajectory points to roads, providing smooth rendering effects. This feature is supported in 3D Map SDK version 4.3.0 and later.

Trace correction is commonly used in driving distance calculation and trajectory management scenarios.

Important: This feature currently supports only driving scenarios and can only match drifting points to roadways.

Correct Trajectories with Location (Available from v5.2.0)

Step 1: Initialize MATraceManager

Start recording the trajectory. The SDK records a point every 2 seconds and sends a correction request every 5 points, then returns the result via callback.

MATraceManager *manager = [MATraceManager sharedInstance];

Step 2: Start Trace Correction

/**
 * @brief Starts trace positioning. Uses the system CLLocationManager internally.
 *        distanceFilter and desiredAccuracy use system defaults.
 * @param locCallback Location callback. Returns coordinates of type AMapCoordinateTypeGPS.
 */
- (void)startTraceWith:(MATraceLocationCallback)locCallback;

Step 3: Parse the Callback Result

/// Location callback. locations: original points; tracePoints: corrected points (nil if correction fails); distance: distance; error: error info on failure.
typedef void(^MATraceLocationCallback)(NSArray<CLLocation *> *locations, NSArray<MATracePoint *> *tracePoints, double distance, NSError *error);

Step 4: Stop Trace Correction

/**
 * @brief Stops trace positioning.
 */
- (void)stopTrace;

Use Trace Correction

Follow the steps below to smoothly draw your trajectory data on the map.

Step 1: Initialize MATraceManager

MATraceManager *manager = [[MATraceManager alloc] init];

Step 2: Construct the Trajectory Point List

Build the trajectory point list using the MATraceLocation format. Set the properties described in the table below.

Important:

1. Missing required fields causes correction failure. Missing optional fields may affect the final result. Providing as much information as possible ensures the smoothest trajectory. We recommend using location data from the iOS Location SDK, which provides high-accuracy positioning with speed and angle values.

2. All coordinates must be within China. Trace correction does not support coordinates outside China.

Step 3: Perform Trace Correction

Trace correction supports multiple coordinate systems: AMAP, GPS raw coordinates, and Baidu coordinates. Use the following method:

NSOperation *op = [manager queryProcessedTraceWith:mArr type:type processingCallback:^(int index, NSArray<MATracePoint *> *points) {
        [weakSelf addSubTrace:points toMapView:weakSelf.mapView2];
    }  finishCallback:^(NSArray<MATracePoint *> *points, double distance) {
        weakSelf.queryOperation = nil;
        [weakSelf addFullTrace:points toMapView:weakSelf.mapView2];
        
        [weakSelf.resultLabel setHidden:NO];
        weakSelf.resultLabel.text = [NSString stringWithFormat:@"Distance:%.0fm", distance];
        [weakSelf.resultLabel sizeToFit];
        weakSelf.resultLabel.center = CGPointMake(CGRectGetMidX(weakSelf.resultLabel.bounds), weakSelf.mapView2.bounds.size.height -  CGRectGetMidY(weakSelf.resultLabel.bounds));
        if(!weakSelf.resultLabel.superview) {
            [weakSelf.mapView2 addSubview:weakSelf.resultLabel];
        }
    } failedCallback:^(int errorCode, NSString *errorDesc) {
        NSLog(@"Error: %@", errorDesc);
        weakSelf.queryOperation = nil;
    }];

Step 4: Retrieve Corrected Data

1. Finish Callback: If all trajectory points are corrected successfully, the finishCallback is triggered. It returns the corrected results for the entire trajectory and the total distance.

typedef void(^MAFinishCallback)(NSArray<MATracePoint *> *points, double distance);

2. Processing Callback: The SDK processes trajectory data in segments. After each segment is corrected, the processingCallback is triggered. It returns the corrected points for that segment and the segment index (starting from 0).

Using segments offers two advantages:

- Reduces wait time when processing large amounts of trajectory data.

- If some segments fail correction, you can still see results from completed segments via the processing callback.

typedef void(^MAProcessingCallback)(int index, NSArray<MATracePoint *> *points);

3. Failed Callback: Correction fails in the following cases, and the failedCallback is triggered with the error reason:

- No network connection.

- Only one point in the original trajectory data.

typedef void(^MAFailedCallback)(int errorCode, NSString *errorDesc);

Important Notes

1. As a feature of the Map SDK, you must set a valid AMAP Key to use trace correction correctly.

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

a) Use <http://tool.oschina.net/codeformat/json> to convert to standard JSON format.

b) Ensure the field names match the table below. If they differ, rename them accordingly.

c) Submit the file to us via a ticket.