RadarTripLeg

RadarTripLeg represents a single destination within a multi-destination trip. Each leg can have its own destination (geofence, address, or coordinates), status, ETA, and metadata. Trip legs allow you to track progress through a route with multiple stops.

Initializers

initWithDestinationGeofenceTag:destinationGeofenceExternalId:

init(destinationGeofenceTag: String?, 
     destinationGeofenceExternalId: String?)

- (instancetype)initWithDestinationGeofenceTag:(NSString *_Nullable)destinationGeofenceTag
                 destinationGeofenceExternalId:(NSString *_Nullable)destinationGeofenceExternalId;

Initializes a trip leg with a destination geofence identified by tag and external ID.

String

The tag of the destination geofence.

String

The external ID of the destination geofence.

initWithDestinationGeofenceId:

init(destinationGeofenceId: String)

- (instancetype)initWithDestinationGeofenceId:(NSString *_Nonnull)destinationGeofenceId;

Initializes a trip leg with a destination geofence identified by its Radar ID.

String

required

The Radar ID of the destination geofence.

initWithAddress:

init(address: String)

- (instancetype)initWithAddress:(NSString *_Nonnull)address;

Initializes a trip leg with an address destination.

String

required

The address string for the destination.

initWithCoordinates:

init(coordinates: CLLocationCoordinate2D)

- (instancetype)initWithCoordinates:(CLLocationCoordinate2D)coordinates;

Initializes a trip leg with coordinate-based destination.

CLLocationCoordinate2D

required

The coordinates for the destination (latitude and longitude).

Response Properties

These properties are populated from server responses and are read-only.

String

The Radar ID of the leg. Set from server response. Use this ID when calling updateTripLeg or completeTripLeg.

RadarTripLegStatus

The status of the leg. Set from server response.Values:

RadarTripLegStatusUnknown - Unknown status
RadarTripLegStatusPending - Leg is queued but not yet active
RadarTripLegStatusStarted - Device is traveling to this leg’s destination
RadarTripLegStatusApproaching - Device is approaching the destination
RadarTripLegStatusArrived - Device has arrived at the destination
RadarTripLegStatusCompleted - Leg has been completed
RadarTripLegStatusCanceled - Leg has been canceled
RadarTripLegStatusExpired - Leg has expired

RadarTripLegDestinationType

The destination type for this leg. When parsed from a server response, reflects the server’s destination.type. Otherwise, inferred from which properties are set (geofence > address > coordinates).Values:

RadarTripLegDestinationTypeUnknown - Unknown destination type
RadarTripLegDestinationTypeGeofence - Destination is a geofence
RadarTripLegDestinationTypeAddress - Destination is an address
RadarTripLegDestinationTypeCoordinates - Destination is a coordinate pair

NSDate

The date when the leg was created. Set from server response.

NSDate

The date when the leg was last updated. Set from server response.

float

The ETA duration in minutes to this leg’s destination. Set from server response.

float

The ETA distance in meters to this leg’s destination. Set from server response.

Geofence Destination Properties

String

The tag of the destination geofence for this leg. Use with destinationGeofenceExternalId for geofence-based destinations.

String

The external ID of the destination geofence for this leg. Use with destinationGeofenceTag for geofence-based destinations.

String

The Radar ID of the destination geofence for this leg. Alternative to using destinationGeofenceTag + destinationGeofenceExternalId.

Address Destination Properties

String

The address string for the destination of this leg. Use for address-based destinations.

Coordinate Destination Properties

CLLocationCoordinate2D

The coordinates for the destination of this leg. Use for coordinate-based destinations. Set latitude and longitude.

BOOL

Whether coordinates have been explicitly set and are valid.

NSInteger

The arrival radius in meters for coordinate-based destinations. Only used when coordinates are set. Defines how close the device needs to be to the coordinates to be considered arrived.

Common Properties

NSInteger

The stop duration in minutes for this leg. Indicates how long the device should remain at this destination before moving to the next leg.

NSDictionary

An optional set of custom key-value pairs for this leg. Use this to attach any custom data to the leg.

Class Methods

legFromDictionary

class func leg(from dictionary: [AnyHashable : Any]?) -> RadarTripLeg?

+ (RadarTripLeg *_Nullable)legFromDictionary:(NSDictionary *_Nullable)dict;

Creates a RadarTripLeg from a dictionary representation.

NSDictionary

The dictionary containing leg data.

Returns: A RadarTripLeg instance, or nil if the dictionary is invalid.

legsFromArray

class func legs(from array: [Any]?) -> [RadarTripLeg]?

+ (NSArray<RadarTripLeg *> *_Nullable)legsFromArray:(NSArray *_Nullable)array;

Creates an array of RadarTripLeg objects from an array of dictionaries.

NSArray

The array of dictionaries containing leg data.

Returns: An array of RadarTripLeg instances, or nil if the array is invalid.

arrayForLegs

class func array(for legs: [RadarTripLeg]?) -> [[AnyHashable : Any]]?

+ (NSArray<NSDictionary *> *_Nullable)arrayForLegs:(NSArray<RadarTripLeg *> *_Nullable)legs;

Converts an array of legs to an array of dictionaries.

NSArray<RadarTripLeg *>

The array of RadarTripLeg instances.

Returns: An array of dictionary representations.

stringForStatus

class func string(for status: RadarTripLegStatus) -> String

+ (NSString *)stringForStatus:(RadarTripLegStatus)status;

Returns the string representation of a trip leg status.

statusForString

class func status(for string: String) -> RadarTripLegStatus

+ (RadarTripLegStatus)statusForString:(NSString *)string;

Returns the trip leg status for a string representation.

stringForDestinationType

class func string(forDestinationType destinationType: RadarTripLegDestinationType) -> String

+ (NSString *)stringForDestinationType:(RadarTripLegDestinationType)destinationType;

Returns the string representation of a trip leg destination type.

destinationTypeForString

class func destinationType(for string: String) -> RadarTripLegDestinationType

+ (RadarTripLegDestinationType)destinationTypeForString:(NSString *)string;

Returns the trip leg destination type for a string representation.

Instance Methods

dictionaryValue

func dictionaryValue() -> [AnyHashable : Any]

- (NSDictionary *)dictionaryValue;

Converts the leg to a dictionary representation for API serialization. Returns: A dictionary representation of the leg.

Usage Examples

Creating Trip Legs with Different Destination Types

// Geofence destination
let leg1 = RadarTripLeg(
    destinationGeofenceTag: "store",
    destinationGeofenceExternalId: "store-123"
)
leg1.stopDuration = 15 // 15 minutes
leg1.metadata = ["orderId": "abc123"]

// Address destination
let leg2 = RadarTripLeg(address: "123 Main St, San Francisco, CA")
leg2.stopDuration = 10

// Coordinate destination
let leg3 = RadarTripLeg(
    coordinates: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194)
)
leg3.arrivalRadius = 100 // 100 meters
leg3.stopDuration = 20

// Geofence destination
RadarTripLeg *leg1 = [[RadarTripLeg alloc]
    initWithDestinationGeofenceTag:@"store"
    destinationGeofenceExternalId:@"store-123"];
leg1.stopDuration = 15; // 15 minutes
leg1.metadata = @{@"orderId": @"abc123"};

// Address destination
RadarTripLeg *leg2 = [[RadarTripLeg alloc]
    initWithAddress:@"123 Main St, San Francisco, CA"];
leg2.stopDuration = 10;

// Coordinate destination
RadarTripLeg *leg3 = [[RadarTripLeg alloc]
    initWithCoordinates:CLLocationCoordinate2DMake(37.7749, -122.4194)];
leg3.arrivalRadius = 100; // 100 meters
leg3.stopDuration = 20;

Creating a Multi-Stop Route

// Create multiple legs for a delivery route
let legs = [
    RadarTripLeg(
        destinationGeofenceTag: "customer",
        destinationGeofenceExternalId: "customer-1"
    ),
    RadarTripLeg(
        destinationGeofenceTag: "customer",
        destinationGeofenceExternalId: "customer-2"
    ),
    RadarTripLeg(
        destinationGeofenceTag: "customer",
        destinationGeofenceExternalId: "customer-3"
    )
]

// Set stop duration for each leg
legs.forEach { $0.stopDuration = 5 }

// Create trip options with legs
let tripOptions = RadarTripOptions(
    externalId: "delivery-route-456",
    destinationGeofenceTag: nil,
    destinationGeofenceExternalId: nil
)
tripOptions.legs = legs
tripOptions.mode = .car

Radar.startTrip(options: tripOptions)

// Create multiple legs for a delivery route
NSArray<RadarTripLeg *> *legs = @[
    [[RadarTripLeg alloc]
        initWithDestinationGeofenceTag:@"customer"
        destinationGeofenceExternalId:@"customer-1"],
    [[RadarTripLeg alloc]
        initWithDestinationGeofenceTag:@"customer"
        destinationGeofenceExternalId:@"customer-2"],
    [[RadarTripLeg alloc]
        initWithDestinationGeofenceTag:@"customer"
        destinationGeofenceExternalId:@"customer-3"]
];

// Set stop duration for each leg
for (RadarTripLeg *leg in legs) {
    leg.stopDuration = 5;
}

// Create trip options with legs
RadarTripOptions *tripOptions = [[RadarTripOptions alloc]
    initWithExternalId:@"delivery-route-456"
    destinationGeofenceTag:nil
    destinationGeofenceExternalId:nil];
tripOptions.legs = legs;
tripOptions.mode = RadarRouteModeCar;

[Radar startTripWithOptions:tripOptions];

Monitoring Leg Progress

Radar.getLocation { (status, location, user, events) in
    guard let trip = user?.trip, let legs = trip.legs else { return }
    
    for (index, leg) in legs.enumerated() {
        print("Leg \(index + 1): \(RadarTripLeg.string(for: leg.status))")
        
        // Check if this is the current active leg
        if leg._id == trip.currentLegId {
            print("  Current leg - ETA: \(leg.etaDuration) min, Distance: \(leg.etaDistance) m")
            
            switch leg.status {
            case .started:
                print("  En route to destination")
            case .approaching:
                print("  Approaching destination")
            case .arrived:
                print("  Arrived! Completing leg...")
                if let legId = leg._id {
                    Radar.completeTripLeg(legId: legId)
                }
            case .completed:
                print("  Leg completed")
            default:
                break
            }
        }
    }
}

[Radar getLocationWithCompletionHandler:^(RadarStatus status, CLLocation *location, RadarUser *user, NSArray<RadarEvent *> *events) {
    if (!user.trip || !user.trip.legs) {
        return;
    }
    
    for (NSInteger i = 0; i < user.trip.legs.count; i++) {
        RadarTripLeg *leg = user.trip.legs[i];
        NSLog(@"Leg %ld: %@", (long)(i + 1), [RadarTripLeg stringForStatus:leg.status]);
        
        // Check if this is the current active leg
        if ([leg._id isEqualToString:user.trip.currentLegId]) {
            NSLog(@"  Current leg - ETA: %.1f min, Distance: %.1f m", leg.etaDuration, leg.etaDistance);
            
            switch (leg.status) {
                case RadarTripLegStatusStarted:
                    NSLog(@"  En route to destination");
                    break;
                case RadarTripLegStatusApproaching:
                    NSLog(@"  Approaching destination");
                    break;
                case RadarTripLegStatusArrived:
                    NSLog(@"  Arrived! Completing leg...");
                    if (leg._id) {
                        [Radar completeTripLegWithLegId:leg._id];
                    }
                    break;
                case RadarTripLegStatusCompleted:
                    NSLog(@"  Leg completed");
                    break;
                default:
                    break;
            }
        }
    }
}];

Updating a Trip Leg

// Update leg metadata or properties
if let currentLegId = user?.trip?.currentLegId {
    let updatedMetadata = ["status": "delayed", "reason": "traffic"]
    Radar.updateTripLeg(
        legId: currentLegId,
        metadata: updatedMetadata
    ) { (status, user, events) in
        if status == .success {
            print("Leg updated successfully")
        }
    }
}

// Update leg metadata or properties
if (user.trip.currentLegId) {
    NSDictionary *updatedMetadata = @{@"status": @"delayed", @"reason": @"traffic"};
    [Radar updateTripLegWithLegId:user.trip.currentLegId
                          metadata:updatedMetadata
                 completionHandler:^(RadarStatus status, RadarUser *user, NSArray<RadarEvent *> *events) {
        if (status == RadarStatusSuccess) {
            NSLog(@"Leg updated successfully");
        }
    }];
}

RadarTripOptions - Configure trips with multiple legs
RadarTrip - The parent trip object containing legs
Trip Tracking Guide - Complete guide to trip tracking

Core

Tracking

Events & Context

Geofences & Places

Location Data

Fraud & Verification

Extensions

Initializers

initWithDestinationGeofenceTag:destinationGeofenceExternalId:

initWithDestinationGeofenceId:

initWithAddress:

initWithCoordinates:

Response Properties

Geofence Destination Properties

Address Destination Properties

Coordinate Destination Properties

Common Properties

Class Methods

legFromDictionary

legsFromArray

arrayForLegs

stringForStatus

statusForString

stringForDestinationType

destinationTypeForString

Instance Methods

dictionaryValue

Usage Examples

Creating Trip Legs with Different Destination Types

Creating a Multi-Stop Route

Monitoring Leg Progress

Updating a Trip Leg

​Initializers

​initWithDestinationGeofenceTag:destinationGeofenceExternalId:

​initWithDestinationGeofenceId:

​initWithAddress:

​initWithCoordinates:

​Response Properties

​Geofence Destination Properties

​Address Destination Properties

​Coordinate Destination Properties

​Common Properties

​Class Methods

​legFromDictionary

​legsFromArray

​arrayForLegs

​stringForStatus

​statusForString

​stringForDestinationType

​destinationTypeForString

​Instance Methods

​dictionaryValue

​Usage Examples

​Creating Trip Legs with Different Destination Types

​Creating a Multi-Stop Route

​Monitoring Leg Progress

​Updating a Trip Leg

​Related

Initializers

initWithDestinationGeofenceTag:destinationGeofenceExternalId:

initWithDestinationGeofenceId:

initWithAddress:

initWithCoordinates:

Response Properties

Geofence Destination Properties

Address Destination Properties

Coordinate Destination Properties

Common Properties

Class Methods

legFromDictionary

legsFromArray

arrayForLegs

stringForStatus

statusForString

stringForDestinationType

destinationTypeForString

Instance Methods

dictionaryValue

Usage Examples

Creating Trip Legs with Different Destination Types

Creating a Multi-Stop Route

Monitoring Leg Progress

Updating a Trip Leg

Related