Create Trip (Android)

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

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

Parameter	Type	Description	Optional
metadata	JSONObject	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 name of the trip
tripDescription	String	The description for the trip
isLocal	boolean	Value determining if the trip is a local trip.
user	String	The user ID
Stops	List <RoamTripStops>	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	JSONObject	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	Double	The stop radius
geometry	List<Double>	The coordinates list with longitude and latitude.
address	String	The stop address

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

Java

JSONObject metadata = new JSONObject();
        metadata.put("Key", "value");
      
List<Double> geometry1 = new ArrayList<>();
        geometry1.add(23.5155215);
        geometry1.add(85.30614739);

List<Double> geometry2 = new ArrayList<>();
        geometry2.add(12.9716);
        geometry2.add(77.5946);

RoamTripStops stop1 = new RoamTripStops();
        stop1.setMetadata(metadata);
        stop1.setStopDescription("description");
        stop1.setStopName("name");
        stop1.setAddress("address");
        stop1.setGeometryRadius(100.0);
        stop1.setGeometry(geometry1);

 RoamTripStops stop2 =new RoamTripStops();
        stop2.setStopId("");
        stop2.setMetadata(metadata);
        stop2.setStopDescription("description");
        stop2.setStopName("name");
        stop2.setAddress("address");
        stop2.setGeometryRadius(600.0);
        stop2.setGeometry(geometry2);

 List<RoamTripStops> stop = new ArrayList<>();
        stop.add(stop1);
        stop.add(stop2);

Kotlin

   val metadata = JSONObject()
        metadata.put("Key", "value")

        val geometry1: MutableList<Double> = ArrayList()
        geometry1.add(23.5155215)
        geometry1.add(85.30614739)

        val geometry2: MutableList<Double> = ArrayList()
        geometry2.add(12.9716)
        geometry2.add(77.5946)

        val stop1 = RoamTripStops()
        stop1.setMetadata(metadata)
        stop1.setStopDescription("description")
        stop1.setStopName("name")
        stop1.setAddress("address")
        stop1.setGeometryRadius(100.0)
        stop1.setGeometry(geometry1)

        val stop2 = RoamTripStops()
        stop2.setStopId("")
        stop2.setMetadata(metadata)
        stop2.setStopDescription("description")
        stop2.setStopName("name")
        stop2.setAddress("address")
        stop2.setGeometryRadius(600.0)
        stop2.setGeometry(geometry2)

        val stop: MutableList<RoamTripStops> = ArrayList()
        stop.add(stop1)
        stop.add(stop2)

Now, let's create an object for the trip and update the parameters along with stop which was created above.

Java

RoamTrip trip = new RoamTrip.Builder()
                .setUserId("userId")
                .setMetadata(metadata)
                .setTripDescription("description")
                .setTripName("name")
                .setIsLocal(true)
                .setStop(stop)
                .build();

Kotlin

val trip: RoamTrip? = RoamTrip.Builder()
            .setUserId("userId")
            .setMetadata(metadata)
            .setTripDescription("description")
            .setTripName("name")
            .setIsLocal(true)
            .setStop(stop)
            .build()

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

Java

Roam.createTrip(trip, new RoamTripCallback() {
            @Override
            public void onSuccess(RoamTripResponse response) {
              //get trip details
            }

            @Override
            public void onError(Error error) {
               //get error details
            }
        });

Kotlin

Roam.createTrip(trip, object : RoamTripCallback {
            override fun onSuccess(response: RoamTripResponse) {
                //get trip details
            }

            override fun onError(error: Error?) {
                //get error details
            }

        })t

The list of responses and error parameters are given below with their descriptions.

To access the status parameters:

Parameter	Type	Description
response.getCode()	Integer	The response code of the method.
response.getMessage()	String	The response message of the method.

To access the trip response:

Parameter	Type	Description
getTripDetails().getTripId()	String	Unique identifier for the object.
getTripDetails().getMetadata()	Object	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.
getTripDetails().getTripName()	String	The name of the trip
getTripDetails().getTripDescription()	String	The trip’s description
getTripDetails().getTripState()	String	The current state of the trip is either created, started, or ended.
getTripDetails().getIsLocal()	boolean	Value determining if the trip is a local trip.
getTripDetails().getTotalDistance()	double	The total distance covered by the user for this trip.
getTripDetails().getTotalDuration()	double	The total duration taken by the user for this trip.
getTripDetails().getTotalElevationGain()	double	The total elevation gain covered by the user for this trip.
getTripDetails().createdAt()	String	Timestamp of when the trip was created
getTripDetails().updatedAt()	String	Timestamp of when the trip was updated
getTripDetails().startedAt()	String	Timestamp of when the trip was started by the user
getTripDetails().endedAt()	String	Timestamp of when the trip was ended by the user

To access user details:

Parameter	Type	Description
getUser().getId()	String	Unique identifier for the object.
getUser().getMetadata()	Object	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.
getUser().getDescription()	String	User description
getUser().getName()	String	The user's full name

To access stop details:

Parameter	Type	Description
getStops().get(i).getStopName()	String	The stop name
getStops().get(i).getStopDescription()	String	The stop description
getStops().get(i).getMetadata()	Object	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.
getStops().get(i).getGeometryRadius()	double	The stop radius.
getStops().get(i).getGeometry()	Object	The coordinates list with longitude and latitude.
getStops().get(i).getArrivedAt()	String	The timestamp when the user arrived at the stop.
getStops().get(i).getDepartedAt()	String	The timestamp when the user departed from the stop.
getStops().get(i).getAddress()	String	The stop address .

To access error details:

Parameter	Type	Description
error.getErrorCode()	Integer	The error response code of the method.
error.getErrorMessage()	String	The error response message of the method.
error.getErrorDescription()	String	The error response description of the method.
error.getErrors().get(i).getMessage()	String	The message for error detail.
error.getErrors.get(i).getField()	String	The field for error detail.