Create Trip (iOS)

Explore how to create a trip on iOS with Trips v2.

To create a trip, you need to create a trip object and assign it with the RoamTrip() class. Below are the parameters and their descriptions for the trip object.

Parameter	Type	Description	Optional
metadata	dictionary	A set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
tripName	string	The trip name
tripDescription	string	The trip’s description
isLocal	boolean	The value determining if the trip is a local trip.
user	string	The user object
stops	array	The list of stop object

When you create a trip, you can add stop locations which are nothing but locations where the user taking the trip will receive events for entry and exit. To create and assign stops to a trip, create objects for a single or multiple stops and assign them with the RoamTripStops() class. Below are the parameters and their descriptions for the stop object.

Parameter	Type	Description	Optional
metadata	dictionary	A set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
stopName	string	The stop name
stopDescription	string	The stop description
geometryRadius	number	The stop radius
geometryCoordinates	array	Coordinates with longitude, latitude.
address	string	The stop address

Below is an example code for creating a trip with two stops. Let's create our stop objects.

Swift

let stop = RoamTripStop()
        
stop.address = "address"
stop.metadata = ["key":"value"]
stop.stopName = "name"
stop.stopDescription = "description"
stop.geometryRadius = 100
// logitude , latitude
stop.geometryCoordinates = [10.1,10.1]

Objective-C

    RoamTripStop *stop = [[RoamTripStop alloc] init];
    [stop setAddress:@"address"];
    [stop setMetadata:@{@"key": @"value"}];
    [stop setStopDescription:@"description"];
    [stop setGeometryRadius:@100];
    // logitude , latitude
    [stop setGeometryCoordinates:@[@10.1,@10.1]];

Now, let's create a trip object and update the parameters along with the stop created above.

Swift

let trip = RoamTrip()
        
trip.user = "userId"
trip.metadata = ["key":"value"]
trip.tripName = "name"
trip.tripDescription = "description"
trip.isLocal = true
trip.stops = [stop]

Objective-C

  RoamTrip *trip = [[RoamTrip alloc] init];
  [trip setMetadata:@{@"key": @"value"}];
  [trip setTripName:@"name"];
  [trip setTripDescription:@"description"];
  [trip setIsLocal:true];
  [trip setStops:@[stop]];

Now, with the trip and stop objects created, let's create the trip with Roam.createTrip() method.

Swift

Roam.createTrip(trip) {response,error in
            // Access status
            // response?.code
            // response?.message
            
            // To access trip details
            let tripDetails = response?.trip
            // Access trip details parameter with tripDetails object
            
            // To access trip user details
            let user = tripDetails?.user
            // Access trip user details parameter with user object
            
            // To access stop details
            let stops = tripDetails?.stops
            //  Access trip stop details parameter with stops array
    
}

Objective-C

[Roam createTrip:trip handler:^(RoamTripResponse * response, RoamTripError * error) {
            // Access status
            // response?.code
            // response?.message
            
            // To access trip details
            RoamTrip  *tripDetails = response.trip;
            // Access trip details parameter with tripDetails object
            
            // To access trip user details
            RoamUser * user = tripDetails.user
            // Access trip user details parameter with user object
            
            // To access stop details
            RoamTripStop *stops = tripDetails.stops;
            //  Access trip stop details parameter with stops array

}];

The list of responses, error parameters and their description is given below.

To access status parameters:

Parameter	Type	Description
response?.code	number	The response code of the method.
response?.message	string	The response message of the method.

To access trip response:

Parameter	Type	Description
tripDetails?.tripId	number	Unique identifier for the trip object.
tripDetails?.metadata	dictionary	A set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
tripDetails?.tripName	string	The trip name
tripDetails?.tripDescription	string	The trip description
tripDetails?.tripState	string	The current state of the trip, created, started, or ended.
tripDetails?.isLocal	boolean	Value determining if the trip is a local trip.
tripDetails?.totalDistance	number	The total distance covered by the user for this trip.
tripDetails?.totalDuration	number	The total duration taken by the user for this trip.
tripDetails?.totalElevationGain	number	The total elevation gain covered by the user for this trip.
tripDetails?.createdAt	string	Timestamp of when the trip was created
tripDetails?.updatedAt	string	Timestamp of when the trip was updated
tripDetails?.startedAt	string	Timestamp when the trip was started by the user
tripDetails?.endedAt	string	Timestamp when the trip was ended by the user

To access user details:

Parameter	Type	Description
user?.userId	string	Unique identifier for the user object.
user?.metadata	dictionary	A set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
user?.userDescription	string	User description
user?.userName	string	User's full name

To access stop details:

Parameter	Type	Description
stops?[i].stopName	string	The stop name
stops?[i].stopDescription	string	The stop description
stops?[i].metadata	dictionary	A set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
stops?[i].geometryRadius	string	The stop radius
stops?[i].geometryCoordinates	array	Coordinates with longitude , latitude.
stops?[i].arrivedAt	string	Timestamp of when the user arrived at the stop
stops?[i].departedAt	string	Timestamp of when the user departed from the stop
stops?[i].address	string	The stop address

To access the error details:

Parameter	Type	Description
error?.code	number	The error response code of the method.
error?.message	string	The error response message of the method.
error?.errorDescription	string	The error response description of the method.
errorDetails?[i].message	string	The message for error details.
errorDetails?[i].field	string	The field for error details.