1 of 100

Roam v1

Introduction

Our Roam Docs contain instructions on how to integrate and use our location SDKs and APIs. Each section walks you through the step-by-step process with source code, examples, and references.

SDKs

Roam SDK is a convenient Software Development Kit that helps you easily add location tracking to your app without the complexity of REST API calls. Our main product offers accuracy, battery efficiency, and customizable location tracking with the following additional features:

Always-on location tracking to track users’ location at all times regardless of the application state (foreground, background, terminated)
Offline location tracking to track users’ location when they are not connected to the internet.
Location spoofing prevention prevents your users from faking their location.
Location tracking modes to customize the setup and optimize battery usage and data collection frequency.

APIs

Our REST APIs allow you to go beyond simple location tracking:

Geofencing - static and moving geofences with events.
Insights - detailed location information about your users' patterns.
Trips - full trip management for mobility and on-demand services.
Nearby - find nearby users and geofences.

Getting Started

Learn how to easily implement Roam location technology.

1. Create a Roam Account

Get started with Roam by creating a The account gives you access to all our location products, project creation and dashboard with a full overview of your usage and spending.

2. Try our example app

During the signup process, download the Roam Test App. It’s our demo application for Android and iOS that showcases the basic functionality of Roam location technology.

3. Start integrating

Read our Roam Docs for Android and iOS for instructions about how to effectively integrate and use our location SDKs and APIs.

4. Get support

To get more information about our products read our or contact our support team.

Key Concepts

Learn more about the key concepts of Roam location technology.

Location update

The fundamental component of Roam location tracking. It is a package of data collected about a users’ location that includes latitude, longitude, altitude, speed, direction, activity, and .

Location module

The Location module defines the desired data flow of a location update. Depending on what you intend to do with the location update we distinguish four different location modules: Tracker, Publisher, Listener, and Processor.

Location Tracker

The location update is collected by the GPS via Roam SDK and stored locally on the mobile device. You may use it if you want simple location tracking and store the location data yourself.

Location Publisher

The location update is collected by the GPS via Roam SDK, sent from the mobile device to the backend server, and stored in the Roam database. You may use it if you want to store the data on Roam servers and go beyond simple location tracking by accessing other Roam products.

Location Listener

The location listener updates the changes in the location through the server to the mobile device.

Location Processor

The Location Processor processes the location updates stored in the database according to the API calls.

Location tracking mode

Location tracking mode allows you to customize your location tracking with varying frequencies of updates and levels of battery drain insights. We differentiate three default modes: Active, Reactive, Passive, and one fully customizable.

Frameworks

Android

Explore all documentation for Android.

SDK Methods (Android)

Explore all of Roam's Android SDK methods.

Get Current Location (Android)

Call this method to get the current location of the user at your desired accuracy level.

Current Location

Get the current location of the user. You can set the accuracy between 5 and 100 meters (default is 10). This method has two outputs.

Callback Method which returns the current location with a faster response time. However, the accuracy depends on the current GPS connectivity.
Location Receiver which returns the next two location updates which will have higher accuracy compared to the callback and takes time from a few hundred milliseconds to a couple of seconds based on the GPS and network connectivity.

Roam.getCurrentLocation(accuracy)

Roam.getCurrentLocation(accuracy);

To listen to location updates, create a class that extends RoamReceiver. Then register the receiver by adding a receiver element to the application element in your manifest.

<application>
        ...
     <receiver android:name=".LocationReceiver"
                    android:enabled="true"
                    android:exported="false">
         <intent-filter>
         <action android:name="com.roam.android.RECEIVED"/>
         </intent-filter>
     </receiver>
         ...
</application>

Add the code to the receiver.

class LocationReceiver : RoamReceiver() {
      override fun onLocationUpdated(context: Context?, roamLocation: RoamLocation?) {
            // receive own location updates here
            // do something with location data using location
      }
}

public class LocationReceiver extends RoamReceiver {

    @Override
    public void onLocationUpdated(Context context, RoamLocation roamLocation) {
        // receive own location updates here
		    // do something with location data using location
    }
}

To get the current location of the user in the callback, use the following code:

Roam.getCurrentLocation(DesiredAccuracy, accuracy, object : RoamLocationCallback {
            override fun location(location: Location?) {
                // Access location data here
            }
            override fun onFailure(roamError: RoamError) {
                // Access Error code and message here
                // roamError.code
                // roamError.message
            }
})

Roam.getCurrentLocation(DesiredAccuracy, accuracy, new RoamLocationCallback(){
    @Override
    public void location(Location location) {
            // Access location data here
    }
    @Override
    public void onFailure(RoamError roamError) {
            // Access Error code and message here
            // roamError.getCode();
            // roamError.getMessage(); 
    }
});

Parameter

Description

DesiredAccuracy

RoamTrackingMode.DesiredAccuracy.HIGH RoamTrackingMode.DesiredAccuracy.MEDIUM RoamTrackingMode.DesiredAccuracy.LOW

Update Current Location (Android)

Call this method to update the current location of a user.

Using the updateCurrentLocation method, you can update the users' current location. You can set the accuracy between 5 to 100 meters (default is 10).

You can now send custom meta-data json values along with updateCurrentLocation method.

This method should be used only if you need to update the current location of the device with better accuracy. Using this method consistently will consume more battery. The higher the accuracy, the longer the response time. In some cases, it can take up to 30 seconds depending on the GPS signal strength.

Update Location When Stationary (Android)

Call this method to periodically pick up a user's location when they are stationary. Customize the time interval in seconds.

By using this method updateLocationWhenStationary, location will update every x seconds when the device goes into a stationary state.

Except for time-based custom tracking, this will operate in all tracking modes, including active, passive, balance, and distance based custom tracking.

Trip v2 SDK Methods (Android)

Explore the Trips v2 SDK Methods for Android

Update Trip (Android)

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

The Update Trip method allows you to update your trip details at any point in time. However, you can update the stop locations as long as the trip has not started. You need to create a new object or update the existing trip, assign it with the RoamTrip() class and pass the trip object to Roam.updateTrip(trip).

Since the updateTrip method updates the existing trip, you need to pass the tripId to the trip object where the tripId is the unique identifier for your trip.

The trip response and its parameters are similar to those of the createTrip() method.

There's no need to exclusively specify if the trip is local using a boolean value. The updateTrip() method will check that for you and update the trip details accordingly.

Start Trip (Android)

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

The Start Trip method allows you to start a planned trip with the previously created tripID.

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

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

The trip response and its parameters are similar to those of the createTrip() method.

End Trip (Android)

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

the End Trip method allows you to end the trip with the previously created tripID. If you want to stop tracking, then you can pass stopTracking as true or false.

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

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

 Roam.endTrip("tripId", true, object : RoamTripCallback {
            override fun onSuccess(response: RoamTripResponse) {
                //get trip details
            }

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

The trip response and its parameters are similar to those of the createTrip method.

Pause Trip (Android)

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

The pause trip method allows you to pause the trip with the previously created tripID.

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

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

The trip response and its parameters are similar to those of the createTrip method.

Resume Trip (Android)

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

The Resume Trip method allows you to resume the trip with the previously paused tripID.

The trip response and its parameters are similar to those of the createTrip method.

Sync Trip (Android)

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

Sync Trip allows you to sync a local trip to the server by using tripID.

 Roam.syncTrip("tripId", new RoamSyncTripCallback() {
            @Override
            public void onSuccess(RoamSyncTripResponse response) {
              //get sync trip details
            }

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

You can access the sync trip response parameters below:

Parameter

Type

Description

response.getCode()

Integer

The success response code of the method.

response.getMessage()

String

The success response message of the method.

response.getDescription()

String

The error response description of the method.

response.getData().getTripId()

String

Unique identifier for the object.

response..getData().getIsSynced()

boolean

The boolean value to determine if the trip is synced.

Get Trip (Android)

Explore how to get the details of a trip on Android with Trips v2.

To get the details of the trip anytime, you can use the Roam.getTrip("tripId") method by passing the tripID.

RoamTrackingMode roamTrackingMode = new RoamTrackingMode.Builder(distanceFilter, stopDuration)
                        .setDesiredAccuracy(RoamTrackingMode.DesiredAccuracy.HIGH)
                        .build();
                        
Roam.getTrip("tripId", new RoamTripCallback() {
                    @Override
                    public void onSuccess(RoamTripResponse response) {
                       //get trip details
                    }

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

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

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

The trip response and its parameters are similar to those of the createTrip method.

There's no need to exclusively specify if the trip is local or not using a boolean value. The getTrip() method will check that for you and update the trip details accordingly.

Get Active Trips (Android)

Explore how to get a user's active trips on Android with Trips v2.

To get the users' active trips, you can use the Roam.getActiveTrips(isLocal) method where the value of isLocal is boolean. The value being true returns all the local trips and value being false, returns all active trips created on the server side.

Roam.getActiveTrips(isLocal,new RoamActiveTripsCallback() {
           @Override
           public void onSuccess(RoamActiveTripsResponse response) {
             //get active trips details
           }

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

Roam.getActiveTrips(isLocal, object : RoamActiveTripsCallback {

           override fun onSuccess(response: RoamActiveTripsResponse?) {
                //get active trips details
            }

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

The Get Active trips method returns all the trips in the form of a list. The parameters and responses are similar to those of the createTrip() method.

Get Trip Summary (Android)

Explore how to get the summary of a trip on Android with Trips v2.

To get a summary of the trip anytime, you can use the Roam.getTripSummary("tripId") method by passing the tripID.

The trip response and its parameters are similar to those of the createTrip() method.

You don't need to mention if the trip is local trip with a boolean value. The getTripSummary() method will check that for you and return the trip details accordingly.

Delete Trip (Android)

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

You can delete the trip irrespective of any trip state. To delete the trip, you need to use the tripID with Roam.deleteTrip("tripId") method.

You can access the delete trip response parameters below:

Parameter

Type

Description

Troubleshooting (Android)

Troubleshooting documentation, proguard rules.

Proguard rules

If you enable code shrinking, obfuscation, and optimization in your project's release build type minifyEnabled true, add the below line to your proguard-rules.pro.

-keep class com.amazonaws.**

iOS

Explore all documentation for iOS

SDK Configuration (iOS)

The first step is to configure the iOS SDK.

Set Tracking in AppState

[Roam setTrackingInAppState:STATE];

Parameter

Description

STATE

RoamTrackingState.Foreground (or) RoamTrackingState.Background (or)

RoamTrackingState.AlwaysOn

Offline Location Tracking

[Roam offlineLocationTracking];

Parameter

Description

Bool

true (default) -- Offline location enabled. false -- Offline location disabled.

Accuracy Engine

For enabling accuracy engine for Passive, Active, and Balanced tracking,

Roam.enableAccuracyEngine()

For Custom tracking modes, you can pass the desired accuracy values in integers ranging from 1-150m.

Roam.enableAccuracyEngine("DESIRED-ACCURACY-VALUE")

For disabling accuracy engine,

Roam.disableAccuracyEngine()

Get Current Location (iOS)

Call the method to get the current location of the user at your desired accuracy level.

This method gets the current location of the user. You can set the accuracy between 5 and 100 meters (default is 10).

 [Roam getCurrentLocation:accuracy handler:^(CLLocation * location, RoamError * error) {
          //  location?.coordinate.latitude           
          //  location?.coordinate.longitude       
          //  location?.altitude
          //  error?.code
          //  error?.message 
    }];

Update Current Location (iOS)

Call the method to update the current location of a user.

Using the updateCurrentLocation method, you can update the user's current location. You can set the accuracy between 5 and 100 meters (default is 10).

You can now send custom meta-data JSON values along with updateCurrentLocation method.

// update current location without meta-data
[Roam updateCurrentLocation:accuracy];

// update current location with meta-data
// Declare meta-data
RoamPublish *publish = [[RoamPublish alloc] init];
NSDictionary *metaData = @{ "key" : "value"};
publish.meta_data = metaData
[Roam updateCurrentLocation:accuracy :publish];

Update Location When Stationary (iOS)

Call the method to periodically pick up a user's location when they are stationary. Customize the time interval in seconds.

By using this method updateLocationWhenStationary , location will update every x seconds when the device goes into a stationary state.

Except for time-based custom tracking, this will operate in all tracking modes, including active, passive, balance, and distance based custom tracking.

Trips v2 SDK Methods (iOS)

Explore the Trips v2 SDK Methods for iOS.

Update Trip (iOS)

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

Since the updateTrip method updates the existing trip, you need to pass the tripID to the trip object where the tripID is the unique identifier for your trip.

Roam.updateTrip(trip) { response, error in
    // Access trip response and error here            
}

[Roam updateTrip handler:^(RoamTripResponse * response, RoamTripError * error) {
       // Access trip response and error here            
}];

The trip response and its parameters are similar to those of the createTrip() method.

There's no need to exclusively specify if the trip is local using a boolean value. The updateTrip() method will check that for you and update the trip details accordingly.

Start Trip (iOS)

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

To start a planned trip, you need to pass the tripID with theRoam.endTrip("tripId") method.

[Roam startTrip:@"tripId" :false handler:^(RoamTripResponse * response, RoamTripError * error) {
  // Access end trip response    
}];

The trip response and its parameters are similar to those of the createTrip()method.

End Trip (iOS)

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

To end the trip, you need to pass the tripID with the Roam.endTrip("tripId") method.

[Roam endTrip:@"tripId" :false handler:^(RoamTripResponse * response, RoamTripError * error) {
  // Access end trip response    
}];

The trip response and its parameters are similar to those of the createTrip() method.

Pause Trip (iOS)

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

To pause the trip, you need to pass the tripID with the Roam.pauseTrip("tripId") method.

[Roam pauseTrip:@"tripId" handler:^(RoamTripResponse * response, RoamTripError * error) {
     // Access resume trip response   
}];

The trip response and its parameters are similar to those of the createTrip() method.

Resume Trip (iOS)

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

To resume the trip, you need to pass the tripID with the Roam.resumeTrip("tripId") method.

The trip response and its parameters are similar to those of the createTrip() method.

Sync Trip (iOS)

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

To sync a trip, you need to pass the tripID with the Roam.syncTrip("tripId") method.

Roam.syncTrip("tripId") { response, error in
  // Access sync trip response
}

[Roam syncTrip:@"" handler:^(RoamTripSync * response, RoamTripError * error) {
 // Access sync trip response
}];

You can access the sync trip response parameters below:

Parameter

Type

Description

response?.code

number

The success response code of the method.

response?.message

string

The success response message of the method.

response?.messageDescription

string

Error response description of the method.

response?.tripId

string

Unique identifier for the trip object.

response?.isSynced

boolean

Boolean value to determine if the trip is synced.

Get Trip (iOS)

Explore how to get the details of a trip on iOS with Trips v2.

To get the details of the trip anytime, you can use the Roam.getTrip("tripId") method by passing the tripId.

[Roam getTrip:@"tripId" handler:^(RoamTripResponse * response, RoamTripError * error) {
      // Access trip response and error here
}];

The trip response and its parameters are similar to those of the createTrip() method.

There's no need to exclusively specify if the trip is local or not using a boolean value. The getTrip()method will check that for you and update the trip details accordingly.

Get Active Trips (iOS)

Explore how to get a user's active trips on iOS with Trips v2.

[Roam getActiveTrips:true handler:^(RoamActiveTripResponse * _Nullable, RoamTripError * _Nullable) {
        // Access trip response and error here         
}];

The Get Active trips method returns all the trips in the form of a list. The parameters and responses are similar to those of the createTrip() method.

Get Trip Summary (iOS)

Explore how to get the summary of a trip on iOS with Trips v2.

To get a summary of the trip anytime, you can use the Roam.getTripSummary("tripId") method and pass the tripID.

[Roam getTripSummary:@"tripId" handler:^(RoamTripResponse * response, RoamTripError * error) {
      // Access trip response and error here
}];

The trip response and its parameters are similar to those of the createTrip()method.

Subscribe Trip (iOS)

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

For you to subscribe to a trip, you need to pass the tripID with the Roam.subscribeTrip("tripId") method.

Roam.subscribeTrip("tripId")

[Roam subscribeTrip:@"tripId"];

Once you subscribe to the trip, you will receive real time trip data in the listener methods

In order to subscribe to the trips with the listener method, you need to make sure the below is implemented.

To listen to location updates, create a class that implements RoamDeleagate and then call Roam.delegate.

Set your RoamDelegate in a code path that will be initialized and executed in the background. For example, ensure that your AppDelegate and not the ViewController implements RoamDelegate. The reason being, AppDelegate will be initialized in the background, whereas a ViewController may not be.

Note: For tracking without user sessions, i.e., self tracking, you can only listen to location, errors and offline trip status data since the locations are not being sent to our servers for event processing.

import UIKit
import Roam
import CoreLocation

@main
class AppDelegate: UIResponder, UIApplicationDelegate, RoamDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        Roam.delegate = self
        Roam.initialize("YOUR-SDK-KEY-GOES-HERE")
        return true
    }
    func didUpdateLocation(_ location: RoamLocation) {
        // Do something with the user location
        // location.userId
        // location.activity 
        // location.timezoneOffset  
        // location.recordedAt  
        // location.batteryRemaining
        // location.networkStatus 
        // location.metaData 
        // location.location.speed 
        // location.location.horizontalAccuracy
        // location.location.verticalAccuracy 
        // location.location.altitude  
        // location.location.course       
        // location.location.coordinate.latitude
        // location.location.coordinate.longitude 
    }
    func onReceiveTrip(_ response: RoamTripStatus) {
        // Access subscribeTrip response
    }

- (void)onReceiveTrip:(RoamTripStatus *)tripStatus {
// Access subscribeTrip response
}

You can access the subscribed trip response parameters below:

Parameter

Type

Description

response.tripId

string

Unique identifier for trip objects.

response.speed

double

Current speed of the subscribed trip

response.distance

double

Current distance covered of the subscribed trip

response.duration

double

Current duration taken of the subscribed trip

response.startedTime

string

Timestamp of when the trip was started by the user

response.pace

double

The current pace of the subscribed trip

response.latitude

double

Current latitude coordinates of the subscribed trip

response.longitude

double

Current longitude coordinates of the subscribed trip

You can unsubscribe from trips using the tripID.

Roam.unsubscribeTrip("tripId")

[Roam unsubscribeTrip:@"tripId"];

Delete Trip (iOS)

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

You can delete the trip irrespective of any trip state. To delete the trip, you need to use the tripID with the Roam.deleteTrip("tripId") method.

You can access the delete trip response parameters below:

Parameter

Type

Description

Utility Methods (iOS)

Explore the iOS utility methods related to location permissions.

Set DeviceToken

The Roam SDK is capable of sending push notifications to your users. to get the device token.

Check Location Permission

Check if the location permissions for the app are enabled.

Location Permission Status

By using the locationPermissionStatus method you can check the location permission status.

notDetermined = 0

restricted = 1

denied = 2

authorizedAlways = 3

authorizedWhenInUse = 4

Request Location Permission

Application request for the user location.

Check Location Tracking

Check whether location tracking has started or not. This method returns a boolean value.

Notification Opened Handler

By using this method inside the Notification delegate method you can track the campaign's impressions and counts.

Troubleshooting (iOS)

Troubleshooting documentation for iOS.

PRODUCTS

APIs

Authorization

This page describes the Roam authentication model, API endpoints, and error handling while using Roam APIs.

Base URL

All URLs referenced in the API documentation will have the following base:

https://api.roam.ai/v1/

REST APIs are served over HTTPS. To ensure data privacy, Roam discourages using unencrypted HTTP requests.

API Use Cases

Here are some popular use cases with Roam APIs:

Can be used to view and do much more with your user data.
- Enables you to view user count per project.
- Enables you to determine the device (iOS/Android) and application from which the hits are coming.
Can create, update, and delete Geofences, and trigger events on the fly
- Use geofences to create virtual fences for your structural properties on maps.
- Track your users as they enter and exit geofences.
- Understand user behavior and usage, as well as visit patterns.
Provides Location APIs to track your users' movement and activities.
- Know the users' location in real-time by just calling Roam APIs.
Trips APIs can be used to view your user trips and routes
- Track the trip of the user.
- Fetch path of the trips along with the routes, mode of transportation, stop points, and offline status.

Authentication

Roam uses an API Key based authentication passed using a custom headerApi-Keyfor the APIs taking into consideration the safety of your API secret keys. We provide APIs on a per-project basis so that the projects are independent of each other's APIs.

API Endpoints

Once your application is integrated with the Roam SDK, an account for each user will be created using your app. Information about these users can be tracked through Roam APIs.

Here are the API endpoints available to interact with the user profile data:

Users API

Explore the documentation for Roam's Users API.

Create User API

The Create User API creates users corresponding to the project secret API key provided.

Create User API

POST https://api.roam.ai/v1/api/user/

The Create User API creates user who are using your app corresponding to the project secret API key provided.

Headers

Name

Type

Description

Api-key*

string

Auth-key E.g.- 33223kjhdcscijhb5sdbsdmjsdcbj5f

Request Body

Name

Type

Description

app_type*

number

Either 1 or 2 where 1 is for Android and 2 is for iOS

device_token*

string

Device token (can be dummy value initially), the same will be updated once the user is logged in from an actual device.

description

string

The description of the user.

metadata

array

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.

{
   "status":true,
   "msg":"User tracking initiated successfully.",
   "code":201,
   "data":{
      "user_id":"62135419cc5d8960bf735b3f",
      "app_id":"61dfb41b06f8a05d35522133_1",
      "description":null,
      "geofence_events":false,
      "location_events":false,
      "trips_events":false,
      "nearby_events":false,
      "location_listener":false,
      "event_listener":false,
      "metadata":null,
      "sdk_version":"0",
      "project_id":"61dfb41b06f8a05d35522133",
      "account_id":"61dfb4030dc55a46ac091ad0"
   }
}

Sample Request

curl --location --request POST 'https://api.roam.ai/v1/api/user/' \
--header 'Api-Key: <YOUR-API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "app_type": 1,
    "device_token": "your-device-token",
    "description": "device description",
    "metadata": { }
}'

Update User API

This API lets you update the details of a user.

Update User API

PUT https://api.roam.ai/v1/api/user/

Headers

Name

Type

Description

Api-key

string

Auth-key E.g.- 33223kjhdcscijhb5sdbsdmjsdcbj5f

Request Body

Name

Type

Description

user_id

string

Enable or disable events data for the given user_id. E.g.- 5d9450ace47bae6d70064a9b

description

string

Update user description. E.g.- “test user”

geofence_events

boolean

Enable or disable geofence_events. E.g.- true

trips_events

boolean

Enable or disable trips_events. E.g.- true

location_events

boolean

Enable or disable location_events. E.g.- true

nearby_events

boolean

Enable or disable nearby_events. E.g.- true

event_listener

boolean

Enable or disable event_listener. E.g.- true

location_listener

boolean

Enable or disable location_listener. E.g.- true

{
    "status": true,
    "msg": "Success.",
    "code": 200,
    "data": {
        "id": "60b90dd651efb070950db2e9",
        "account_id": "60af304c51efb03cdde65042",
        "app_id": "60af306a8ce7db2392eb7a75_1",
        "device_token": "d1_nRSCRgMI:APA91bFgVQ8BJqVJsuGF7CbFDfyiMSLgL6c0mW_GHVfeBcjEraRA6lJfreGqKSMzsvNE7ARJn-8V8_mbyL_Bwyy0ScKtjauarg84MyZlgRahszRVPr69-FgdvSx5xi699YGcXz8nfTnb",
        "device_uuid": null,
        "description": "ROAM111",
        "brand": "xiaomi",
        "model": "Redmi Note 7",
        "group_id": null,
        "os_version": "28",
        "sdk_version": "3.1.6",
        "device_arn": "arn:aws:sns:us-east-1:218937252071:endpoint/GCM/app_60af306a8ce7db2392eb7a75_1_a678d41d-a66f-442b-90e5-1564b6c88c34/5b73758f-cc96-373a-a2dc-400d8c8f5685",
        "geofence_events": false,
        "motion_events": false,
        "location_events": false,
        "trips_events": false,
        "nearby_events": false,
        "location_listener": false,
        "event_listener": false,
        "metadata": {
            "name": "ROAM123"
        },
        "is_deleted": false,
        "created_at": "2021-06-03T17:13:58.830",
        "updated_at": "2021-07-02T07:44:38.781"
    }
}

Sample Request

curl --location --request PUT 'https://api.roam.ai/v1/api/user/' \
--header 'Content-Type: application/json' \
--header 'APi-Key: 63598c5b3aa84f14914013709402bbc9' \
--data-raw '{
  "user_id": "60b90dd651efb070950db2e0",
  "description": "ROAM111",
  "metadata" :{"name": "ROAM123" },
  "geofence_events": false,
  "motion_events": false,
  "location_events": false,
  "trips_events": false,
  "nearby_events": false,
  "location_listener": false,
  "event_listener": false
}'

Locations API

Explore the documentation for Roam's Locations API.

Get Stop Locations API

Coming Soon. Request for beta access if you'd like to try it out.

Insights API

Insights APIs are on demand for our enterprise customers. In case you want us to process your location data to know your users Home, Work and POIs, please reach out to our customer support.

Get User Home Location API

This API will provide a list of insights with boundary coordinates of the location, last visit details, type and confidence for the user's home.

Get Home Insight API

GET https://api.roam.ai/v1/api/insights/home/

Query Parameters

Name

Type

Description

Headers

Name

Type

Description

Sample Request

Trips v1 API

Explore Roam's Trips v1 API documentation.

Create Trip API v1

The Create Trip API helps you to create a new trip with an origin, destination, and user.

Create Trip API

POST https://api.roam.ai/v1/api/trips/

Headers

Name

Type

Description

Api-key

string

Auth-key E.g.- 33223kjhdcscijhb5sdbsdmjsdcbj5f

Request Body

Name

Type

Description

user_id

string

User-id for which the trip needs to be assigned E.g.- 5d9450ace47bae6d70064a9b

origins

array

Single or multiple origin locations in [long, lat] format. E.g.- [[77.677270, 12.914131]]

destinations

array

Single or multiple destination locations in [long, lat] format. E.g.- [[77.700475, 12.957005]]

{
    "status": true,
    "msg": "Success.",
    "code": 201,
    "data": [
        {
            "id": "<ID>",
            "origins": [
                {
                    "id": "<ID>",
                    "trip_id": "<TRIP-ID>",
                    "created_at": "2020-09-22T06:00:34.264",
                    "updated_at": "2020-09-22T06:00:34.269",
                    "coordinates": {
                        "type": "Point",
                        "coordinates": [
                            77.622977,
                            12.917042
                        ]
                    },
                    "loc_type": "origin"
                }
            ],
            "destinations": [
                {
                    "id": "<ID>",
                    "trip_id": "<TRIP-ID>",
                    "created_at": "2020-09-22T06:00:34.272",
                    "updated_at": "2020-09-22T06:00:34.275",
                    "coordinates": {
                        "type": "Point",
                        "coordinates": [
                            77.650239,
                            12.924304
                        ]
                    },
                    "loc_type": "destination"
                },
                {
                    "id": "<ID>",
                    "trip_id": "<TRIP-ID>",
                    "created_at": "2020-09-22T06:00:34.278",
                    "updated_at": "2020-09-22T06:00:34.281",
                    "coordinates": {
                        "type": "Point",
                        "coordinates": [
                            77.697418,
                            12.959172
                        ]
                    },
                    "loc_type": "destination"
                }
            ],
            "events": [],
            "user_id": "<USER-ID>",
            "is_started": false,
            "is_ended": false,
            "is_deleted": false,
            "created_at": "2021-06-22T06:00:34.261",
            "updated_at": "2021-06-22T06:00:34.261",
            "trip_tracking_url": "https://trips.gs/NWY2OTkzMDI5NzI0MjIwNThmY2ZjYTFlfHNmZHNnZHNh"
        }
    ]
}

curl --location --request POST 'https://api.roam.ai/v1/api/trips/' \
--header 'Api-key: <API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
	"user_id": "<USER-ID>",
	"origins": [[77.622977 ,12.917042]],
    "destinations":[[77.650239 ,12.924304], [77.697418 ,12.959172]]
}'

Update Trip API v1

This API allows you to update the origin, destination or user_id for a given trip_id before starting the trip.

Update Trip API

PUT https://api.roam.ai/v1/api/trips/

Headers

Name

Type

Description

Api-key

string

Auth-key E.g.- 33223kjhdcscijhb5sdbsdmjsdcbj5f

Request Body

Name

Type

Description

user_id

string

user_id to which the trip is to be reassigned E.g.- 5d9450ace47bae6d70064a9q

trip_id

string

Trip id which needs to be modified. E.g.- 5d9450ace47bae6d70064a9b

origins

array

Origin location in [long, lat] format. E.g.- [[77.677270, 12.914131]]

destinations

array

Destination location in [long, lat] format. E.g.- [[77.700475, 12.957005]]

{
    "status": true,
    "msg": "Success.",
    "code": 201,
    "data": [
        {
            "id": "<ID>",
            "origins": [
                {
                    "id": "<ID>",
                    "trip_id": "<TRIP-ID>",
                    "created_at": "2021-06-22T06:00:34.264",
                    "updated_at": "2021-06-22T06:00:34.269",
                    "coordinates": {
                        "type": "Point",
                        "coordinates": [
                            77.622977,
                            12.917042
                        ]
                    },
                    "loc_type": "origin"
                }
            ],
            "destinations": [
                {
                    "id": "<ID>",
                    "trip_id": "<TRIP-ID>",
                    "created_at": "2021-06-22T06:01:44.680",
                    "updated_at": "2021-06-22T06:01:44.687",
                    "coordinates": {
                        "type": "Point",
                        "coordinates": [
                            77.700475,
                            12.957005
                        ]
                    },
                    "loc_type": "destination"
                }
            ],
            "events": [
                {
                    "id": "<ID>",
                    "trip_id": "<TRIP-ID>",
                    "user_id": "<USER-ID>",
                    "event_type": "motion:trip:created",
                    "created_at": "2021-06-22T06:00:35.210",
                    "is_deleted": false,
                    "event_source": "motion:trip",
                    "event_version": "1.0"
                },
                {
                    "id": "<ID>",
                    "trip_id": "<TRIP-ID>",
                    "user_id": "<USER-ID>",
                    "event_type": "motion:trip:created",
                    "created_at": "2021-06-22T06:01:42.606",
                    "is_deleted": false,
                    "event_source": "motion:trip",
                    "event_version": "1.0"
                }
            ],
            "user_id": "<USER-ID>",
            "is_started": false,
            "is_ended": false,
            "is_deleted": false,
            "created_at": "2021-06-22T06:00:34.261",
            "updated_at": "2021-06-22T06:01:44.699"
        }
    ]
}

Sample Request

curl --location --request PUT 'https://api.roam.ai/v1/api/trips/' \
--header 'Api-key: <API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
	"trip_id": "<TRIP-ID>",
	"destinations": [[77.700475, 12.957005]]
}'

Delete Trip API v1

This API helps you to delete an existing trip.

Delete Trip API

DELETE https://api.roam.ai/v1/api/trips/

Query Parameters

Name

Type

Description

Headers

Name

Type

Description

Sample Request

Export Trip Summary as GPX

This API helps you to export trip data in the .gpx format.

Export Trip Summary as GPX

GET https://api.roam.ai/v1/api/trips/export/

Query Parameters

Name

Type

Description

trip_id

string

trip_id required to export its data in gpx format. E.g.- 5fdc5470203bda0000abacc0

type

string

format to be given in which data need to be exported. E.g.- gpx

Headers

Name

Type

Description

Api-key

string

Auth-key E.g.- 083591a3392c483e838f66ac788126eb

{
    "status": true,
    "msg": "Success.",
    "code": 200,
    "data": {
        "download_url": "https://geospark-gpx-files.s3.amazonaws.com/5fdc5470203bda0000abacc0.gpx"
    }
}

Sample Request

curl --location --request GET 'https://api.roam.ai/v1/api/trips/export/?trip_id=5f44a2fce289b825457e5497&type=gpx' \
--header 'Api-key: <API-KEY>'

Trips v2 API

Explore Roam's Trip v2 API documentation

Get Single Trip API

Explore how to get a single trip with our Trip API

Get Trip

GET https://api.roam.ai/v2/trips/:id

Returns the trip with the given ID.

Path Parameters

Name

Type

Description

id*

String

Retrieves the trip with the given ID.

Headers

Name

Type

Description

Authorization*

String

Bearer <API-KEY>

{
   "code": 200,
   "message": "trip_object",
   "description": "The details of trip for requested id.",
   "has_more": false,
   "trips":
       {
           "id": "620f26ad9ba7360496bc1be7",
           "name": "Test Delivery",
           "description": "item pickup for test users",
           "trip_state": "created",
           "total_distance": 0,
           "total_duration": 0,
           "total_elevation_gain": 0,
           "metadata": {
               "_id": 21,
               "order_id": "1123"
           },
           "start_location": {},
           "end_location": {},
           "user": {
               "id": "61ffb486d2c69840ee518073",
               "name": "",
               "description": "1200",
               "metadata": {
                   "Mobile": "1234567890",
                   "Name": "Nikhil"
               }
           },
           "started_at": null,
           "ended_at": null,
           "created_at": "2022-02-18T04:55:09.660",
           "updated_at": "2022-02-18T04:55:09.660",
           "events": [],
           "stops": [
               {
                   "id": "620f26ad9ba7360496bc1be5",
                   "name": "Delivery",
                   "description": "test Pickup for Johan",
                   "metadata": {
                       "order_id": "1120"
                   },
                   "address": "Flat NO 121 MG road ",
                   "geometry_radius": 20,
                   "geometry": {
                       "type": "Point",
                       "coordinates": [
                           77.6879689,
                           27.4072289
                       ]
                   },
                   "created_at": "2022-02-18T04:55:09.658",
                   "updated_at": "2022-02-18T04:55:09.658",
                   "arrived_at": null,
                   "departed_at": null
               },
               {
                   "id": "620f26ad9ba7360496bc1be6",
                   "name": "Delivery",
                   "description": "another tester Pickup for Johan",
                   "metadata": {
                       "order_id": "1129"
                   },
                   "address": "teacher colony ",
                   "geometry_radius": 200,
                   "geometry": {
                       "type": "Point",
                       "coordinates": [
                           77.6925657818137,
                           27.422398561298454
                       ]
                   },
                   "created_at": "2022-02-18T04:55:09.659",
                   "updated_at": "2022-02-18T04:55:09.659",
                   "arrived_at": null,
                   "departed_at": null
               }
           ]
       }
}

{
  "code" : 400,
  "message" : "invalid_request_error",
  "description": "The request was unacceptable, due to missing a required parameter or invalid parameter.",
  "errors" : [
    {
      "field" : "id",
      "message" : "This field should be a valid trip id"
    }
  ]
}

Example

curl --location --request GET 'https://api.roam.ai/v2/trips/620f26ad9ba7360496bc1be7' \
--header 'Authorization: Bearer dfbbf5d5ff6b41ecb1166147b87c0544'

Export Trip API

Explore how to export a trip with our Trip API

Export Trip

GET https://api.roam.ai/v2/trips/:id/export

Export the trip summary of the given trip id as gpx/json/csv/geojson file.

Path Parameters

Name

Type

Description

Query Parameters

Name

Type

Description

Headers

Name

Type

Description

Example

Delete Trip API

Explore how to delete a trip with our Trip API

Delete Trip

DELETE https://api.roam.ai/v2/trips/:id

You can delete the trip via this API. Deleting a trip does not affect any users who have already completed the trip; however the user can't start a previously created trip if it is deleted.

Path Parameters

Name

Type

Description

Headers

Name

Type

Description

Example

Geofencing API

Explore the documentation for our Geofencing API

CREATE Geofence API

The create Geofence API is responsible for creating geofences for project, users or groups.

Create Geofence API

POST https://api.roam.ai/v1/api/geofence/

Headers

Name

Type

Description

Request Body

Name

Type

Description

Sample Request

GET Geofence API

This API gives you the filtered list of geofences.

GET Geofence API

GET https://api.roam.ai/v1/api/geofence/

Query Parameters

Name

Type

Description

Headers

Name

Type

Description

Sample Request

UPDATE Geofence API

Use this API to update details for an existing geofence of any specific project.

Update Geofence API

PUT https://api.roam.ai/v1/api/geofence/

Headers

Name

Type

Description

Request Body

Name

Type

Description

Sample Request

DELETE Geofence API

Delete Geofence API allows you to delete already existing geofences for a project.

You can delete the geofence by two options below:

Query Parameters: This can accept only one geofence_id which can be deleted.
Body Parameters: If you want to delete more than one geofence, you can use the body parameters with upto 200 geofence_id at a time.

Delete Geofence API

DELETE https://api.roam.ai/v1/api/geofence

Query Parameters

Name

Type

Description

geofence_id

string

Delete geofence for this id. E.g.- 5f73326ce5fc231ba4b253eb

Headers

Name

Type

Description

Api-key

string

Auth-key E.g.-33223kjhdcscijhb5sdbsdmjsdcbj5f

Request Body

Name

Type

Description

geofence_id

array

Array of geofence_id to be deleted.

E.g- ["5f73326ce5fc231ba4b253eb", "5f73326ce5fc231ba4b2534f"]

{
    "status": true,
    "msg": "Geofence deleted successfully.",
    "code": 200,
    "data": {}
}

Sample Request

Single Delete

curl --location --request DELETE 'https://api.roam.ai/v1/api/geofence/?geofence_id=5f73326ce5fc231ba4b253eb' \
--header 'Api-Key: e566c098cc6b441a9c3453b6fcf76e88' \
--header 'Content-Type: application/json'

Bulk Delete

curl --location --request DELETE '{{host}}/v3/api/geofence/' \
--header 'Api-key: xxxxxxxxxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data-raw '{
   "geofence_id": ["615c6cef8ce7db3886f21550", "615c6ce351efb0120dcea364"]
}'

Events API

Events APIs are used to fetch the list of events generated by the users with ability to filter the results based on various parameters.

Changelog (iOS)

Keep yourself updated on any iOS changes.

0.1.19 - (Dec 05, 2023)

We're pleased to announce Roam iOS SDK version 0.1.19, primarily focused on resolving issues related to crashes occurring with Core Data and AWS IoT during location tracking in the background state and other rare scenarios. In this update, we've made the following fixes:

Core Data and AWS-IoT Crash Fixes: Addressed crashes occurring during location tracking in the background state and other infrequent scenarios related to Core Data and AWS IoT integrations. Users can now expect improved stability and reliability when utilizing these features.

These fixes aim to enhance the overall stability of the SDK, ensuring a smoother experience for developers and users alike. We're committed to providing a robust and dependable SDK. If you encounter any further issues or have feedback to share, please reach out to our support team. We're here to assist you promptly.

0.1.18 - (Nov 17, 2023)

We're excited to introduce Roam iOS SDK version 0.1.18, focusing on enhancing our network module and refining tracking logics. In this update, we've made the following improvements:

Enhanced Connectivity during Location Tracking: We've revamped the network module to handle few edge-cases on connectivity during location tracking. Expect smoother and more reliable communication between your app and Roam's services, ensuring a seamless experience for users even in challenging network conditions.
Minor Improvements to Tracking Logics: We've implemented minor refinements to our tracking logics. These subtle enhancements aim to fine-tune the tracking mechanisms, resulting in improved accuracy and efficiency when capturing and processing location data.

These improvements are geared towards providing a more robust and consistent experience for developers and users alike. We're dedicated to optimizing your tracking capabilities and ensuring a smoother operational experience. Should you have any inquiries or feedback, our support team is readily available to assist you.

0.1.17 - (Nov 02, 2023)

We're thrilled to present Roam iOS SDK version 0.1.17, focusing on bolstering our security module. In this update, we've made significant improvements to enhance the security of location data. Here's what's new:

Efficient Spoofed Location Detection: Our security algorithm has been refined to efficiently discard spoofed locations during the initial location fix. This enhancement ensures that only genuine and accurate location data is captured, enhancing the authenticity of the information gathered.
Addressing False Negatives: We've tackled false negatives during location tracking, ensuring that true locations are not mistakenly identified as spoofed locations. This refinement enhances the precision of location tracking, providing you with reliable and accurate data.

These security enhancements are designed to safeguard your data and ensure the integrity of the location information collected by the Roam iOS SDK. Your security is our priority, and we're committed to providing you with a secure and trustworthy experience. If you have any questions, concerns, or feedback, our support team is always here to assist you.

0.1.16 - (Oct 15, 2023)

We're excited to introduce Roam iOS SDK version 0.1.16, focusing on refining connectivity and enhancing tracking performance. In this update, we've made the following improvements:

Enhanced Connectivity: We've optimized the SDK's connectivity, ensuring smoother communication between your app and Roam's services. This enhancement leads to a more stable and reliable connection experience.
Improved Tracking Performance: Our team has worked diligently to enhance the overall tracking performance of the Roam iOS SDK. Expect better accuracy, responsiveness, and efficiency when tracking user data, providing a seamless experience for your users.

These improvements are designed to elevate your tracking capabilities and provide a more robust experience for both you and your users. As always, your feedback is invaluable to us. For any inquiries, support, or to share your feedback, don't hesitate to reach out to our dedicated support team. We're here to assist you every step of the way.

0.1.15 - (Sep 29, 2023)

We're thrilled to announce the release of Roam iOS SDK version 0.1.15, bringing powerful enhancements and simplified integration. Here's what's new:

Callback Integration: We've added callbacks to essential methods like startTracking, stopTracking, subscribe, unSubscribe, publishAndSave, and stopPublishing. These callbacks provide clear onSuccess and onError methods, ensuring you have complete control and real-time feedback for every SDK action.
Simplified Initialization: Now, initializing the Roam SDK is easier than ever. Simply place your publishable key in the .plist file, streamlining the setup process and getting you up and running swiftly.

Your feedback has been invaluable in shaping these improvements. For any queries, assistance, or to share your experiences, our support team is here to help.

0.1.14 - (Aug 29, 2023)

We're excited to announce the latest release of the Roam iOS SDK version 0.1.14. This update brings a significant enhancement that contributes to heightened security and user control. Read on to discover the key highlights of this release:

New Feature: Motion Detection Security With Roam iOS SDK v0.1.14, we introduce an innovative security feature—Motion Detection. This cutting-edge capability adds an extra layer of protection to your application's tracking experience. By enabling the verifyMotion parameter in the toggleSecurity() method, developers can now leverage motion patterns to enhance security. This empowers you to monitor and respond to unusual motion activities, ensuring a safer and more reliable tracking environment. As always, we appreciate your feedback and contributions in helping us refine and enhance the Roam iOS SDK. Please feel free to reach out to our support team if you have any questions, concerns, or suggestions. Stay tuned for more updates as we continue to improve the SDK's capabilities and features.

0.1.13 - (Aug 23, 2023)

We're excited to introduce Roam iOS SDK version 0.1.13, which includes a significant enhancement aimed at strengthening security within the SDK. Here's a breakdown of the latest changes:

New Security Module: Roam We've incorporated an advanced security module named Roam into the SDK. With this release, developers can take advantage of the toggleSecurity() method provided by Roam. This addition allows for seamless enabling and disabling of enhanced security measures. Protecting sensitive data is of paramount importance, and the Roam security module provides a streamlined way to fortify your application's defenses. As always, we appreciate your feedback and contributions in helping us refine and enhance the Roam iOS SDK. Please feel free to reach out to our support team if you have any questions, concerns, or suggestions. Stay tuned for more updates as we continue to improve the SDK's capabilities and features.

0.1.12 - (May 31, 2023)

Fixed the tracking issue during terminated state for SDK only tracking.

0.1.11 - (May 3, 2023)

Fixed multiple users creating when calling setDeviceToken method.

0.1.10 - (Mar 27, 2023)

Added few support for new error codes and messages in on didError delegate.

0.1.9 - (Mar 17, 2023)

Fixed a number of crashes that occurred while tracking in specific scenarios, improving the overall stability of the SDK.
Cleared console warnings to improve the developer experience.
Improved user subscription process for a smoother and more streamlined experience.
Improved location tracking logic to improve the accuracy and reliability of the SDK.
Overall performance and stability of the SDK have been improved.

0.1.8 - (Feb 24, 2023)

Activity recognition permission issues fixed.

0.1.7 - (Feb 13, 2023)

In this release, we have made the following improvements to enhance the user experience of our Roam iOS SDK:

Activity recognition methods: We have added activity recognition methods to the Roam iOS SDK to provide a more accurate and reliable determination of the user's current activity. This will improve the accuracy of location tracking, especially when the user is in motion.
Improved tracking logic: To further improve battery consumption, we have made some changes to our tracking logic. These changes are aimed at ensuring that the Roam SDK is as efficient as possible in terms of energy usage, while still providing accurate location tracking. We are confident that these changes will improve the overall experience of our Roam iOS SDK and we hope you enjoy these enhancements. If you have any questions or concerns, please feel free to reach out to us.

0.1.13 - (Aug 23, 2023)

We're excited to introduce Roam iOS SDK version 0.1.13, which includes a significant enhancement aimed at strengthening security within the SDK. Here's a breakdown of the latest changes:

New Security Module: Roam We've incorporated an advanced security module named Roam into the SDK. With this release, developers can take advantage of the toggleSecurity() method provided by Roam. This addition allows for seamless enabling and disabling of enhanced security measures. Protecting sensitive data is of paramount importance, and the Roam security module provides a streamlined way to fortify your application's defences.

As always, we appreciate your feedback and contributions in helping us refine and enhance the Roam iOS SDK. Please feel free to reach out to our support team if you have any questions, concerns, or suggestions. Stay tuned for more updates as we continue to improve the SDK's capabilities and features.

0.1.12 - (May 31, 2023)

Fixed the tracking issue during terminated state for SDK only tracking.

0.1.11 - (May 3, 2023)

Fixed mutiple users creating when calling setDeviceToken method.

0.1.10 - (Mar 27, 2023)

Added a few support for new error codes and messages on the didError delegate.

0.1.9 - (Mar 17, 2023)

Fixed a number of crashes that occurred while tracking in specific scenarios, improving the overall stability of the SDK.
Cleared console warnings to improve the developer experience.
Improved user subscription process for a smoother and more streamlined experience.
Improved location tracking logic to improve the accuracy and reliability of the SDK.
Overall performance and stability of the SDK have been improved.

0.1.8 - (Feb 24, 2023)

Activity recognition permission issue fixed.

0.1.7 - (Feb 13, 2023)

In this release, we have made the following improvements to enhance the user experience of our Roam iOS SDK:

Activity recognition methods: We have added activity recognition methods to the Roam iOS SDK to provide a more accurate and reliable determination of the user's current activity. This will improve the accuracy of location tracking, especially when the user is in motion.
Improved tracking logic: To further improve battery consumption, we have made some changes to our tracking logic. These changes are aimed at ensuring that the Roam SDK is as efficient as possible in terms of energy usage, while still providing accurate location tracking.

We are confident that these changes will improve the overall experience of our Roam iOS SDK and we hope you enjoy these enhancements. If you have any questions or concerns, please feel free to reach out to us.

0.1.6 - (Jan 20, 2023)

Tweaked the tracking algorithm for efficient battery consumption: We have made changes to our tracking algorithm to optimize battery consumption. The new algorithm is designed to reduce battery usage while maintaining the same level of accuracy and reliability.

0.1.5 - (Jan 20, 2023)

Added basic ingest publish topic for AWS cost optimization.
Fixed drift issue for distance-based tracking.

0.0.37 - (Jan 5, 2023)

Fixed drift issue for distance-based tracking.

0.1.4 - (Dec 25, 2022)

Fixed total elevation issue in sync trip.

0.1.3 - (Dec 16, 2022)

Added:

Added elevation gain parameter to trip listener.
Added speed parameter to location listener.

Fixed:

Location calibration when used along with accuracy config and time-based tracking.
Tracking config issue for time-based tracking.
Fixed crash when user received other user location.
Removed blue bar on user logout without stop tracking.
Fixed distance calculation logic for individual route points in RoamTripsSummary.

0.0.36 - (Nov 21, 2022)

Added a new Roam.requestAlwaysAuthorization() method for location permission control.

0.0.35 - (Nov 10, 2022)

Making SDK backwards compatible to support Xcode 13.X with Swift v5.6.1.

0.0.34 - (Nov 4, 2022)

Location calibration when used along with accuracy config and time-based tracking.
Added elevation gain parameter to trip listener.
Added speed parameter to location listener.

0.0.33 - (Oct 14, 2022)

Added support for Roam.initialize() with custom configurations.

0.0.32 - (Sept 29, 2022)

Made the SDK backwards compatible to support Xcode 14.x with Swift v5.7 along with the fix for crash issues while receiving other user locations.

0.0.31 - (Sept 28, 2022)

Made the SDK backwards compatible to support Xcode 13.x with Swift v5.6.1 along with the fix for the crash issues while receiving other user locations.

0.0.30 - (Sept 27, 2022)

Tracking config issue for time-based tracking.
Fixed crash when user received other user location.
Removed blue bar on user logout without stopping tracking.

0.1.2 - (August 25, 2022)

Added:

Added accuracy config methods for Roam.getCurrentLocation(), Roam.updateCurrentLocation() and Time based custom tracking.
Added timestamps to the trip listener data.
Added option to unsubscribe from all the trips in the method Roam.unsubscribeTripStatus()
Added new methods for batch configurations in trips data receiver.
Trips data in a trip receiver is changed from a single object to a list of updates.
Added new methods for batch configurations in location receiver.

Fixed:

Fixed crashing behavior while changing location permission.
Fixed blue bar issue for custom tracking modes.
Fixed location tracking issue when location permission is changed.
The fixed trip listener works independently of the location listener.
Fixes core data for location and trips.

0.1.1 - (May 12, 2022)

Fixed:

Crash when Roam.getTrip() is called without starting the trip.

Modified:

Removed user id validation for offline trips.
Create trip without user id. ie. optional
Support to update trip based on trip state.

Added:

Speed parameter to the routes in the trips summary.
Subscribe to online trips.

0.1.0 - (February 25, 2022)

Modified:

Updated new trip v2 methods. Refer Migration guide for more details.

0.0.29 - (August 30, 2022)

Fixed:

Fixed distance calculation logic for individual route points in RoamTripsSummary.

0.0.28 - (July 22, 2022)

Fixed:

Fixed crashing behavior while changing location permission.

0.0.27- (July 05, 2022)

Fixed:

Fixed build issues with v0.0.26.

0.0.26 - (July 04, 2022)

Added:

Added accuracy config methods for Roam.getCurrentLocation(), Roam.updateCurrentLocation() and Time based custom tracking.

Fixed:

Fixed blue bar issue for custom tracking modes.
Fixed location tracking issue when location permission is changed.

0.0.25 - (June 15, 2022)

Fixes:

Fix for #31 and #32

0.0.24 - (June 14, 2022)

Added:

Added timestamps to the trip listener data.
Created option to unsubscribe from all the trips in the method Roam.unsubscribeTripStatus().
The fixed trip listener works independently of the location listener.

0.0.23 - (May 25, 2022)

Added:

Added new methods for batch configurations in trips data receiver.
Trip data in a trip receiver is changed from a single object to a list of updates.

Fixed:

Fixes core data for location and trips.

0.0.22 - (May 6, 2022)

Added:

Added callbacks to Roam.resetBatchReceiverConfig method to return default config values.

0.0.21 - (April 29, 2022)

Added:

Added new methods for batch configurations in location receiver.
Updated trip error codes.

0.0.20 - (April 18, 2022)

Fixed:

Fixed calculation for distance and duration for individual location data in trip summary route.

0.0.19 - (April 14, 2022)

Added:

Added individual distance, duration, and elevation gain for location data inside trip routes for local trips.
Trip summary response for the local trip will have the route sorted by recorded timestamp.

Fixed:

Fixed background location tracking for time-based tracking mode when location permission is given as 'Allow while using'

0.0.18 - (April 1, 2022)

Fixed:

Fixed the coordinates arrangement for Roam.getTripSummary() on local trips.

0.0.17 - (February 7, 2022)

Fixed:

Removed the blue bar that was being displayed during active tracking.

0.0.16 - (January 19, 2022)

Modified:

Added an option in Roam.unSubscribe() which will now unsubscribe all users if user_id is passed as null or empty.
Added battery and network details as part of the location in the location receiver.

0.0.15 - (January 4, 2022)

Fixed:

Issues in tracking location when the application is forced to terminate by the user. The SDK will now restart the tracking automatically.

0.0.14 - (December 3, 2021)

Fixed:

Improved Roam.getCurrentLocation() to return the location faster.

0.0.13 - (November 15, 2021)

Fixed:

Location activity was getting updated as stationary for all location points during the terminated state.

0.0.12 - (November 15, 2021)

Modified:

Custom tracking options will now work in the terminated state. (SDK will wait for a significant change in the device location to restart the tracking again in the background)

0.0.11 - (October 20, 2021)

Added:

Support to listen to location updates of users from different projects which are in the same account.

Fixed:

Multiple location updates are recorded when the user is stationary while tracking.

0.0.10 - (August 20, 2021)

Modified:

#28 Made startTrip independent by combining it with startTracking and createTrip methods

Added:

metadata support for users and trips were added

0.0.9 - (August 2, 2021)

Modified:

#19 Allowed meta-data support for updating location, i.e., updateCurrentLocation method.

Removed:

#20 Combined startTracking and startSelfTracking methods.

Added:

#21 Updated location when a user becomes stationary.

0.0.8 - (July 23, 2021)

Fixed #23 - Tracking stops working after new getUser() or createUser() session

0.0.7 - (June 29, 2021)

#13 In order to support Apple Silicon M1 Macs, we added arm64 to iOS simulator builds.

0.0.6 - (June 29, 2021)

#5 Added support for XCFrameworks
#4 Added support for Swift Package Manager
#11 Updated the docs to support the SPM integration steps

0.0.5 - (June 25, 2021)

Updated dependency frameworks for XCFramworks to avoid build issues during manual integration.

0.0.4 - (June 24, 2021)

Refactored the current framework to support dependencies from local XCFrameworks.

0.0.3 - (June 24, 2021)

Added the total elevation gain parameter to the already existing elevation gain, distance, and duration parameters in the trip summary.
Added support new compiler version for Xcode 12.5.1 with Swift v5.4.2
Fix for #1 and #2

0.0.2 - (June 10, 2021)

Added:

isTripSync() Method

Fixed:

Fixed Location Id generation for Offline Trips

Modified:

Replaced AWSIOT with CocoaMQTT

0.0.1 - (April 12, 2021)

The first version of Roam iOS SDK

Quickstart (iOS)

The Roam iOS SDK makes it quick and easy to build a location tracker for your iOS app. We provide powerful and customizable tracking modes and features that can be used to collect your users’ location

Requirements

To use the Roam SDK, the following things are required:

Get yourself a free Roam Account. No credit card required.
Create a project and add an iOS app to the project.
You need the SDK_KEY (available in your project settings) to initialize the SDK.

You’re now ready to integrate the SDK into your iOS application.

The Roam iOS SDK requires Xcode 10.0 or later and is compatible with apps targeting iOS version 10 and above.

Run the example application

The Roam Example repository on GitHub includes example apps that demonstrate the use of the v3 Roam SDK for iOS.

See Swift's example app in Example/.

To run an example app, clone this repository, add your publishable YOUR-PUBLISHABLE-KEY key in AppDelegate.swift, and build the app.

Make sure the bundle_id is the same as the one registered on our Roam Playground dashboard.

Xcode Setup

To integrate the Roam SDK, you need a Roam account.

Go to Xcode > File > New Project
Configure the information property list file Info.plist with an XML snippet that contains data about your app. You need to add strings for NSLocationWhenInUseUsageDescription in the Info.plist file to prompt the user during location permissions for foreground location tracking. For background location tracking, you also need to add a string for NSLocationAlwaysUsageDescription and NSLocationAlwaysAndWhenInUseUsageDescription in the same Info.plist file.
```
<key>NSLocationWhenInUseUsageDescription</key>
<string>Add description for foreground only location usage.</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>Add description for background location usage. iOS 10 and below"</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Add description for background location usage. iOS 11 and above</string>
```

Next, you need to enableBackground fetch and Location updates under Project Setting > Capabilities > Background Modes.

SDK Installation

There are several ways to integrate the Roam Mobile SDK for iOS into your own project:

Swift Package Manager
CocoaPods
Carthage (Will be added soon)
Dynamic Frameworks

Swift Package Manager Installation

Swift Package Manager is distributed with Xcode. To start adding the AWS SDK to your iOS project, open your project in Xcode and select File > Swift Packages > Add Package Dependency.

Enter the URL for the Roam SDK for iOS Swift Package Manager GitHub repo (https://github.com/roam-ai/roam-ios) into the search bar and click Next.

You'll see the repository rules for which version of the SDK you want the Swift Package Manager to install. Choose the first rule, Version, and select Up to Next Minor as it will use the latest compatible version of the dependency that can be detected from the main branch, then click Next.

Select roam-ios, then click Finish.

You can always go back and modify which SPM packages are included in your project by opening the Swift Packages tab for your project: Click on the Project file in the Xcode navigator, then click on your project's icon, then select the Swift Packages tab.

CocoaPods Installation

Follow the steps below to add the SDK to the project using CocoaPods. Add the below to the Podfile

pod 'roam-ios'

Then run pod install.

This will add the Roam SDK and its dependencies to your project. The Roam SDK depends on CoreLocation, AWSMobileClient and AWSIoT for fetching locations and its transmission to our servers. The SDK supports iOS 10 and above.

Manual Installation

If you’re not familiar with using Cocoapods or prefer manual installation, we’ve added a ZIP file to the SDK. Use this link to download the Roam.zip file.

Unzip the file and add the Roam Roam.framework to your Xcode project by dragging the file into your Project Navigator.

You can do this by selecting the project file in the navigator on the left side of the Xcode window, and then navigating to the Linked Frameworks and Libraries section. From there, click the “+” button to add the Roam framework. You will also want to add the following frameworks from this link.

AWSAuthCore.xcframework
AWSCognitoIdentityProvider.xcframework
AWSCognitoIdentityProviderASF.xcframework
AWSCore.xcframework
AWSIoT.xcframework
AWSMobileClientXCF.xcframework

Make sure the the added frameworks under Linked Frameworks and Libraries section are selected as Embed & Sign

Initialize SDK

Roam SDK offers a flexible method of initialization, allowing developers to seamlessly integrate our services into their applications. With our latest update, we've introduced a new initialization approach using property list files (plist). This method provides an effortless way to set up your Roam SDK without the need for additional code.

Using Property List (plist) Initialization:

Optional Parameter: Publish Key
- The publishKey parameter in the initialization method is now optional.
- If you've added your Roam publish key to your project's .plist file, there's no need to pass the publishKey parameter during initialization.
Configure Your .plist File:
- In your info.plist file, declare your Roam publish key as follows:
```
<key>ROAM_PUBLISH_KEY</key>
<string>$(ROAM_PUBLISH_KEY)</string>
```
- Replace "$(ROAM_PUBLISH_KEY)" with your actual Roam publish key.
Using XCConfig File (Optional):
- Alternatively, you can use an XCConfig file to feed the Roam publish key to the plist file.
- In your XCConfig file, add the following line, replacing XXXXXXXXXXXXXX with your Roam publish key:
```
ROAM_PUBLISH_KEY = XXXXXXXXXXXXXX
```
Initialization Code:
- Initialize Roam SDK in your application as follows:
```
Roam.initialize("")
// OR
Roam.initialize(nil)
```
- If the publish key is added to the plist, the initialize method can be called without passing any parameters.

By following these steps, you can seamlessly initialize Roam SDK using property list files, simplifying the integration process and saving valuable development time.

Using AppDelegate Initialization:

Add the following code to AppDelegate file. This code imports the SDK and allows the SDK to use other methods.

import Roam

After import, add the below code underapplication(_:didFinishLaunchingWithOptions:) in your AppDelegate file. The SDK must be initialized before calling any of the other SDK methods using your project's publishable key.

Roam.initialize("YOUR-SDK-KEY-GOES-HERE")

Request Permissions

Before you start location tracking, you need to get permission from the user for your application to access locations.

Import CoreLocation at the top of the AppDelegate file.
```
import CoreLocation
```
Make the below class declaration for Location Manager and add this line before the return statement in application(_:didFinishLaunchingWithOptions:) With this line, you ask users to allow the app to access location data both in the background and the foreground.
```
let locationManager = CLLocationManager()
locationManager.requestLocation()
```

Location Tracking

Start Tracking

Roam.startTracking(TrackingMode){ status, error in

}

Use one of the tracking modes while you use the Roam.startTracking method.

Stop Tracking

To stop the tracking use the below method.

Roam.stopTracking(){ status, error in

}

Tracking Modes

Adaptive Tracking

Roam has three default tracking modes along with a custom version. They are different based on the frequency of location updates and battery consumption. The higher the frequency, the higher the battery consumption.

Mode

Battery usage

Updates every

Optimised for/advised for

Active

6% - 12%

25 ~ 250 meters

Ride Hailing / Sharing

Balanced

3% - 6%

50 ~ 500 meters

On Demand Services

Passive

0% - 1%

100 ~ 1000 meters

Social Apps

//active tracking
Roam.startTracking(RoamTrackingMode.active){ status, error in

}
// balanced tracking
Roam.startTracking(RoamTrackingMode.balanced){ status, error in

}
// passive tracking
Roam.startTracking(RoamTrackingMode.passive){ status, error in

}

Distance Interval Tracking

The SDK also provides a custom tracking mode which allows you to customize and build your own tracking mode as per your requirement.

Type

Unit

Unit Range

Distance Interval

Meters

1m ~ 2500m

Distance between location updates example code:

// Define a custom tracking method
let distanceTrackingMethod = RoamTrackingCustomMethods()

// Update the settings for the created method as per need
distanceTrackingMethod.activityType = .fitness
distanceTrackingMethod.pausesLocationUpdatesAutomatically = true
distanceTrackingMethod.showsBackgroundLocationIndicator = true
distanceTrackingMethod.useSignificant = false
distanceTrackingMethod.useRegionMonitoring = false
distanceTrackingMethod.useVisits = false
distanceTrackingMethod.accuracyFilter = 10
distanceTrackingMethod.desiredAccuracy = .kCLLocationAccuracyNearestTenMeters

// Update the distance intervel as per the use case in meters
distanceTrackingMethod.distanceFilter = 10

// Start the tracking with the above created custom tracking method
Roam.startTracking(.custom, options: distanceTrackingMethod){ status, error in

}

Time Interval Tracking

Type

Unit

Unit Range

Time Interval

seconds

1s - 10000s

Time between location updates example code:

// Define a custom tracking method
let timeTrackingMethod = RoamTrackingCustomMethods()

// Update the settings for the created method as per need
timeTrackingMethod.activityType = .fitness
timeTrackingMethod.pausesLocationUpdatesAutomatically = true
timeTrackingMethod.showsBackgroundLocationIndicator = true
timeTrackingMethod.useSignificant = false
timeTrackingMethod.useRegionMonitoring = false
timeTrackingMethod.useVisits = false
timeTrackingMethod.accuracyFilter = 10
timeTrackingMethod.desiredAccuracy = .kCLLocationAccuracyNearestTenMeters

// Update the time intervel as per the use case in seconds
timeTrackingMethod.updateInterval = 10

// Start the tracking with the above created custom tracking method
Roam.startTracking(.custom, options: timeTrackingMethod){ status, error in

}

Location Listener

To listen to location updates, create a class that implements RoamDeleagate and then call Roam.delegate.

Set your RoamDeleagate in a code path that will be initialized and executed in the background. For example, make your AppDelegate implement RoamDeleagate, not a ViewController. AppDelegate will be initialized in the background, whereas a ViewController may not be.

Note: In the case of tracking without user session ie. self-ttracking, you can listen to only location, error and offline trips status data since the locations are not being sent to our servers for processing events.

import UIKit
import Roam
import CoreLocation

@main
class AppDelegate: UIResponder, UIApplicationDelegate, RoamDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        Roam.delegate = self
        Roam.initialize("YOUR-SDK-KEY-GOES-HERE")
        return true
    }
    func didUpdateLocation(_ location: RoamLocation) {
        // Do something with the user location
        // location.userId
        // location.activity 
        // location.timezoneOffset  
        // location.recordedAt  
        // location.batteryRemaining
        // location.networkStatus 
        // location.metaData 
        // location.location.speed 
        // location.location.horizontalAccuracy
        // location.location.verticalAccuracy 
        // location.location.altitude  
        // location.location.course       
        // location.location.coordinate.latitude
        // location.location.coordinate.longitude 
    }

Batch Configuration

Batch configuration lets you control the number of location data updates being received in the location listener with the desired frequency and window.

Set Batch Configuration

As the name suggests, this method sets the configuration parameters.

The networkState indicates the state in which the updates are to be received. It can either be set to online, offline, or both.
The batchCount indicates the size of the location batch.
The batchWindow indicates the time interval for every consecutive update (frequency of updates).

By default, the batch configuration values for both batch count and window are set to 1 and 0 respectively.

// let networkState:RoamNetworkState = .Both
// batchCount: number of location updated
// batchWindow : frequency of location updates.
Roam.setBatchReceiverConfig(networkState: networkState, batchCount: batchCount, 
batchWindow: batchWindow) { config, error in
      // error?.code
      // error?.message
                                                                                       
               
      // config?.batchCount
      // config?.batchWindow
      // config?.networkState
 }

[Roam setBatchReceiverConfigWithNetworkState: networkState batchCount:batchCount 
batchWindow:batchWindow handler:^(RoamBatchConfig * config, RoamError * error) {
      // error?.code
      // error?.message
                                                                                       
               
      // config?.batchCount
      // config?.batchWindow
      // config?.networkState
  }];

Consider the following call,

Roam.setBatchConfig("networkState.Both", 5 , 60)

The batch count value is the number of location updates sent in a batch. In the above case, the value is set to 5. Ideally, the SDK sends 5 updates per batch and the batch window (in the above case, 60) specifies the number of seconds the SDK waits to receive five location updates.

If the SDK receives 5 location updates in less than 60 seconds, the updates are pushed to the listener. If not, it waits for 60 seconds and pushes the location updates regardless of the batch count value.

Success Callback - We receive a list of BatchReceiveConfig objects.

Example response:

[{"batchCount":5,"batchWindow":10,"networkState":"offline"}, {"batchCount":5,"batchWindow":10,"networkState":"online"}]

Error Callback: We receive a RoamError object in the error callback.

The available details to get from the RoamError object are: error.getMessage() and error.getCode()

Get Batch Configuration

The get receiver config method allows the user to get the current batch configuration for the location listener.

Roam.getBatchReceiverConfig { config, error in
      // error?.code
      // error?.message
                                                                                       
               
      // config?.batchCount
      // config?.batchWindow
      // config?.networkState
 }swif

[Roam getBatchReceiverConfigWithHandler:^(RoamBatchConfig * config, RoamError * error) 
{
      // error?.code
      // error?.message
                                                                                       
               
      // config?.batchCount
      // config?.batchWindow
      // config?.networkState
}];

obj

Reset Batch Configuration

The Reset Batch Configuration method allows the user to reset the batch config for the location listener.

Roam.resetBatchReceiverConfig { config, error in
      // error?.code
      // error?.message
                                                                                       
               
      // config?.batchCount
      // config?.batchWindow
      // config?.networkState
 }

[Roam resetBatchReceiverConfigHandler:^(RoamBatchConfig * config, RoamError * error) 
{
      // error?.code
      // error?.message
                                                                                       
               
      // config?.batchCount
      // config?.batchWindow
      // config?.networkState
}];

Changelog (Android)

Keep yourself updated on any Android changes.

0.1.23 - (Dec 20, 2023)

We're excited to introduce Roam Android SDK version 0.1.23, focusing on refining our location filters to improve accuracy during location tracking. In this update, we've made the following improvement:

Enhanced Location Filtering: We've refined our location filters to effectively discard drifts and noises during location tracking. This enhancement aims to improve the accuracy and reliability of location data, ensuring a more precise representation of user movement.

These improvements are geared towards providing a more accurate and dependable location tracking experience for developers and users. We're dedicated to enhancing your tracking capabilities and ensuring a smoother operational experience. Should you have any inquiries or feedback, our support team is readily available to assist you.

0.1.22 - (Dec 08, 2023)

We're excited to introduce Roam Android SDK version 0.1.22, focusing on refining our location filters to improve accuracy during location tracking. In this update, we've made the following improvement:

Enhanced Location Filtering: We've refined our location filters to effectively discard drifts and noises during location tracking. This enhancement aims to improve the accuracy and reliability of location data, ensuring a more precise representation of user movement.

0.1.21 - (Oct 27, 2023)

We're thrilled to present Roam Android SDK version 0.1.21, focusing on bolstering our security module. In this update, we've made significant improvements to enhance the security module of location tracking. Here's what's new:

Efficient Spoofed Location Detection: Our security algorithm has been refined to efficiently discard spoofed locations during the initial location fix. This enhancement ensures that only genuine and accurate location data is captured, enhancing the authenticity of the information gathered.
Addressing False Negatives: We've tackled false negatives during location tracking, ensuring that true locations are not mistakenly identified as spoofed locations. This refinement enhances the precision of location tracking, providing you with reliable and accurate data.

These security enhancements are designed to safeguard your data and ensure the integrity of the location information collected by the Roam Android SDK. Your security is our priority, and we're committed to providing you with a secure and trustworthy experience. If you have any questions, concerns, or feedback, our support team is always here to assist you.

0.1.20 - (Sep 30, 2023)

We are thrilled to introduce Roam Android SDK version 0.1.20, a significant step forward in enhancing your tracking experience. Here's what's new:

New Callbacks for Enhanced Control: With added success and error callbacks to methods like startTracking, stopTracking, subscribe, unSubscribe, publishAndSave, and stopPublishing, you now have precise control and real-time feedback for every SDK action.
Extended Security Checks: We've expanded the toggleSecurity() method with two vital parameters. Now, you can check for connected external accessories and Bluetooth status, bolstering security measures for your application. Your feedback has played a pivotal role in shaping these enhancements. Should you have any questions, encounter issues, or want to share your experiences, our dedicated support team is here to assist you.

0.1.19 - (Aug 29, 2023)

We're excited to announce the latest release of the Roam Android SDK, version 0.1.19. This update brings a significant enhancement that contributes to heightened security and user control. Read on to discover the key highlights of this release:

New Feature: Motion Detection Security With Roam Android SDK v0.1.19, we introduce an innovative security feature—Motion Detection. This cutting-edge capability adds an extra layer of protection to your application's tracking experience. By enabling the verifyMotion parameter in the toggleSecurity() method, developers can now leverage motion patterns to enhance security. This empowers you to monitor and respond to unusual motion activities, ensuring a safer and more reliable tracking environment. Your feedback and insights have been instrumental in shaping the Roam Android SDK, and we're grateful for your ongoing support. If you have any questions, suggestions, or need assistance, please don't hesitate to contact our support team. As we strive to continually refine and enhance the SDK, look forward to more updates on the horizon.

0.1.18 - (Aug 23, 2023)

We're pleased to unveil Roam Android SDK version 0.1.18, showcasing an exciting new feature that enhances security and user control. Here's an overview of the latest updates:

New Security Module: Roam In this release, we introduce the Roam Security Module, a powerful addition to the SDK's arsenal. With the Roam module, developers now have access to the toggleSecurity() method, a versatile tool that allows the seamless activation and deactivation of advanced security mechanisms. Prioritizing data security is vital, and the Roam Security Module empowers developers to safeguard sensitive information more effectively.

Your feedback and insights have been instrumental in shaping the Roam Android SDK, and we're grateful for your ongoing support. If you have any questions, suggestions, or need assistance, please don't hesitate to contact our support team. As we strive to continually refine and enhance the SDK, look forward to more updates on the horizon.

0.1.17 - (Jul 3, 2023)

Added a new feature to get publish key from local.properties gradle file.
Fixed order of callbacks for create and get user methods and MQTT connection.

0.1.16 - (Jun 14, 2023)

Added stationary duration for all tracking modes except time base.

0.1.15 - (Jun 7, 2023)

Fixed noise and duplicate locations update.
Improved location accuracy.

0.1.14 - (May 17, 2023)

Added post notification support for android 13.
Removed work manager concept from SDK.

0.1.13 - (Mar 23, 2023)

Fixed work manager dependency version for react native SDK support.

0.1.12 - (Mar 16, 2023)

Fixed dynamic distance filter logic.
Fixed location update gap in time base tracking.
Added noise filter in time base tracking.

0.1.11 - (Feb 24, 2023)

Fixed batch location update issue.
Fixed trip sync issue.
Fixed multiple location update and speed inconsistent issue.

0.0.36 - (Feb 22, 2023)

Fixed multiple callback issue for trip methods.

0.1.10 - (Feb 10, 2023)

Added activity recognition to reduce battery consumption for default tracking modes.

0.1.9 - (Jan 20, 2023)

Added basic ingest publish topic for aws cost optimisation.

0.1.8 - (Jan 12, 2023)

Fixed deprecated code and time out error for get current location method.

0.0.35 - (Jan 5, 2023)

Fixed deprecated code and time out error for get current location method.

0.1.7 - (Dec 24, 2022)

Fixed get current location method.

0.1.6 - (Dec 16, 2022)

Removed isTripSynced method (no longer required).
Fixed updateCurrentLocation method, RoamPublish param can be null.
Fixed getActiveTrip method, if isLocal is true then get offline trips in response and vice-versa.
Fixed getActiveTrip method, trip stops point should be in response.
Fixed updateTrip method, isLocal param should not be required to update a trip.
Added SDK installation support for android 13.

0.0.34 - (Dec 13, 2022)

Added hourly location count feature.
Fixed the Roam SDK installation support for android 13.

0.1.5 - (Dec 1, 2022)

Added magnetic bearing support.
Added meta data support for setDescription method.
Added tracking config feature.
Added app service class parameter to setForegroundNotification method.

0.0.33 - (Nov 24, 2022)

Added magnetic bearing feature in SDK.

0.0.32 - (Nov 4, 2022)

Added metadata support for the setDescription() method.

0.0.31 - (Oct 14, 2022)

Added custom configuration support for Roam.initialize() method .

0.1.4 - (Oct 11, 2022)

Fixed the noise location update for distance-based tracking and stationary location update.

0.0.30 - (Sept 22, 2022)

Fixed the execution order of MQTT connection callback and createUser/getUser method's callback.

0.0.29 - (Sept 13, 2022)

Fixed location update gap in stationary location update.
Fixed location update when the device gets restarted.
Fixed tracking config logic for time base tracking.

0.1.3 - (Aug 26, 2022)

Added:

There should be a locations count field.
Batch update support for the trip listener.
Batch update support for location listener.
Network listener method for connectivity change.

Modified:

Create trip method should support creating trips without a user id.
Subscribe trip method should support the online trip.
Update trip method should be based on trip state.
Sync trip should have speed parameter.
Roam trip status should have trip state as parameter.
Unsubscribe trip method support for multiple trips.
Update time stamp field in trip listener.
Trip status code for control trip .

Fixed:

Offline trip reached_stop and left stop event are not getting called.
Drift issue fix.

0.1.2 - (Aug 02, 2022)

Added course field for offline trip

0.0.28 - (July 26, 2022)

Fixed:

Fixed location update gap in distance-based tracking.
Fixed stationary noise locations update when device gets stationary.

0.0.27 - (July 05, 2022)

Fixed:

Fixed Timestamp of offline trip events.

0.0.26 - (June 29, 2022)

Added:

Tracking configuration method for location accuracy improvement.

0.0.25 - (June 06, 2022)

Added:

Unsubscribe trip method for multiple trips ID.
Added timestamp field in the trip status listener.

0.1.1 - (May 30, 2022)

Fixed quick trip response.

0.0.24 - (May 24, 2022)

Fixed:

Location drift issue.
Receiver intent leaking issue

0.0.23 - (May 19, 2022)

Added:

Batch location update feature for trips.

Fixed:

Location listener and connectivity change listener issue.

0.0.22 - (May 14, 2022)

Added:

Network listener method for connectivity change.

0.0.21 - (April 29, 2022)

Added:

Batch location update feature.
Location count field for trips.

Modified:

Trip errors response.

0.0.20 - (April 21, 2022)

Fixed:

Fixed time-based tracking issue.

0.0.19 - (April 14, 2022)

Modified:

RoamPublish parameter as optional in updateCurrentLocation method.

0.0.18 - (April 6, 2022)

Fixed:

Removed noise locations update when the device gets idle during tracking.

0.1.0 - (Feb 25, 2022)

Updated new trip V2 methods. Refer to the Migration guide.

0.0.17 - (February 25, 2022)

Fixed:

Connection configuration for security and performance.

0.0.16 - (February 24, 2022)

Fixed:

Fixed stationary location update issue.

0.0.15 - (January 20, 2022)

Fixed:

Fixed logical error in the calculation of elevation gain in trips summary.

0.0.14 - (January 20, 2021)

Fixed:

Added option in Roam.unSubscribe() which will now unsubscribe all users if user_id is passed as null or empty.
Added battery and network details as part of location in location receiver. Fixed invalid location update data.

0.0.13 - (December 28, 2021)

Fixed:

Foreground notification method support for android 12.

0.0.12 - (December 10, 2021)

Fixed:

SDK installation support for Android 12.

0.0.11 - (November 26, 2021)

Modified:

Removed location permission status frequent updates.

Added:

Added "initialize validation" for each method.

0.0.10 - (November 16, 2021)

Modified:

Removed user-id validation for offline trips in the createTrip method.

0.0.9 - (November 8, 2021)

Added:

Added foreground service notification in SDK.
Added elevation gain support for offline trips.
Removed user-id validation for offline trips.

0.0.8 - (October 21, 2021)

Added:

Implemented location permission status.

0.0.7 - (October 7, 2021)

Added:

Support location subscription for cross-project within the same Account.

0.0.6 - (August 25, 2021)

Fixed:

Issue fixed on the location receiver method.

0.0.5 - (August 23, 2021)

Modified:

Make startTrip independent by combining it with startTracking and createTrip methods

Added:

metadata support for users and trips were added

0.0.4 - (August 6, 2021)

Modified:

Resolves #11 Allow meta-data support for updating location ie. updateCurrentLocation method Removed:
Resolves #9 Combine startTracking and startSelfTracking methods

Removed:

Resolved #9 Combined startTracking and startSelfTracking methods

0.0.3 - (June 24, 2021)

Added:

Added the total elevation gain parameter to the already existing elevation gain, distance, and duration parameters in the trip summary.

0.0.2 - (June 18, 2021)

Fixed:

Fixed location receiver callbacks.

0.0.1 - (April 28, 2021)

The first version of Roam Android SDK

Trips

Explore Roam's Trips documentation.

Trips allow you to manage broadly defined trips. Whether it's a taxi driver, food/parcel delivery, outdoor run, or anyone who needs to move from location A to B, Roam.ai location technology helps manage the process.

Trips use a combination of REST APIs and SDK Methods for the creation and management of trips. Trips can be tracked in real-time using our SDK listener methods, webhooks, and our tracking portal track.roam.ai.

Quick Trips

Quick Trips lets you track journeys from point A to B in real-time using the startTrip and endTrip SDK methods.

Quick Trips are ideal for:

Fitness Tracking while on a run/ride.
Mileage tracking for employees, riders, etc.
Distance tracking for automobile rentals.
Micro mobility apps for short distance tracking.

Quick Trips Workflow

Planned Trips

Planned trips lets you plan trips ahead of time where a user can visit a single location or stop at multiple locations as part of the journey from point A to B to C to N. Start by creating a trip using createTrip including stop_locations where you can specify this location using coordinates of locations.

The best use cases for planned trips are:

Ridesharing and hailing
Food and Grocery delivery
Last-mile delivery
Logistics

Planned Trips Workflow

SDK Methods and APIs

Trips require you to use a combination of SDK Methods and APIs to achieve real-time tracking features.

Trip SDK Methods

Interaction with the Trip SDK Methods may require you to use user_id or trip_id while calling the methods.

Method Name

Description

Trip APIs

The Roam API is organized around . Our API has predictable resource-oriented URLs, accepts request bodies, returns responses, and uses standard HTTP response codes, authentication, and verbs.

Authentication

The Roam API uses API keys to authenticate requests. You can view and manage your API keys in the Roam Dashboard.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth. Authentication to the API is performed via a custom header Api-Key. Provide your API key as the value for the header Api-Key

All API requests must be made over . Calls made over plain HTTP and API requests without authentication will fail.

API Endpoint

Description

API Objects

Trip Object

Attributes

Description

User Object

Attributes

Description

Event Object

Attributes

Description

Stop Object

Attributes

Description

The end-user can initiate different actions depending on the requirement. This is facilitated by the Roam SDK.

For example, when the end-user clicks on the Start Tracking icon on the frontend, the client-side requests to start tracking the user's location.

To use our Roam SDK on the server-side, the SDK object is instantiated using a private API key. The client request is made using the API which connects to the web server and retrieves the necessary data.

The following sections consist of code to instantiate the SDKs on the client side both on iOS and Android and the API requests corresponding to the actions.

Start Quick Trip

As the name suggests, a Quick Trip creates and starts the trip immediately. The user need not define the locations of travel and can track their journey from point A to point B using the startTrip and endTrip SDK methods on their application.

Refer to the following sections to instantiate the Start Quick Trip method on iOS and Android.

Update Trip

Update Trip allows you to update the name, description and the stop locations for a trip.

Consider a scenario where a trip is created with stop locations A, B, and C. If you wish to update the trip with a new stop location D, all the previously created stops need to be passed along with the co ordinates for point D.

If you wish to delete a stop location, you can do so by omitting the co ordinates for that point while updating the trip. However, you can only do so as long as the user has not reached that stop location.

Only stop locations that have not been reached yet can be deleted.

Refer to the following sections for the Update Trip API and SDK methods.

Create Trip

The Create Trip API, specifically used for planned trips, allows you to create new trips with start and stop locations. You can define the geometry radius for these locations which will help capture the entry and exit events.

To instantiate the Create Trip SDK, refer to the following section.

The following section consists of a sample request along with the responses for the Create Trip API.

Control Trip

Once the trip is created, the users can perform various actions to control it. The following sections consist of information on how to integrate the SDKs on iOS and Android devices and the APIs.

Start Trip

The Start Trip method allows you to start a Quick Trip or a planned trip with pre-defined stop locations.

To instantiate the Start Trip SDK method on Android and iOS, refer to the following sections.

The Start Trip API starts the trip for the specified Trip ID.

End Trip

The End Trip method is used to end an ongoing trip. The ended trip could be previously started, paused, and/or resumed.

Refer to the following section for information on how to instantiate the End Trip SDK on Android and iOS.

The End Trip API is used to end the trip for the given ID.

Pause Trip

The Pause Trip method allows the user to pause a previously created trip.

To instantiate the Pause Trip SDK on Android and iOS, refer to the following sections:

Pause Trip API pauses the trip for the given ID.

Resume Trip

The Resume Trip method is used to resume a previously paused trip.

The following section gives information on the Resume Trip SDK method for Android and iOS.

Resume trip API resumes the trip for the given Trip ID.

Sync Trip

The Sync Trip method syncs an offline trip (with locally stored data) to the servers.

The section below shows the code to instantiate the Sync Trip method on Android and iOS.

Get Trips

The Get Trips API fetches the trip details for the given Trip ID. The information will include the Trip ID, name, description, state, stop locations, entry and exit timestamps at the stop locations and so on.

Get Single Trip

As the name suggests, Get Single Trip is used to fetch details for a single Trip ID. Refer to the following sections to instantiate the Get Single Trip SDK method on iOS and Android.

Get Single Trip API fetches the trip details for the provided Trip ID.

Get Multiple Trips

Get Multiple Trips API will fetch multiple trip details. You can use different parameters to filter out the data to be fetched. For detailed information, refer to the section below.

Get Active Trips

A trip is active when it is started and not yet ended. The Get Active Trips method returns all the trips that have been started by the user.

Below are the Get Active Trips methods for Android and iOS.

Get Trip Summary

This method helps get the Trip Summary for the specified trip ID. To instantiate the Get Trip Summary method, refer the following section.

The Get Trip Summary API gives information about the entire trip with the start locations, end location stops, events, routes taken, etc.

Refer to the following section for detailed information about the API.

The Subscribe Trip method helps get real-time location data for trips. This method provides location data for both online and offline trips.

For more information on the Subscribe Trip method, refer to the following section.

To subscribe to trip events about end users, you configure Webhooks for your applications. A Webhook registers the notification URL that Roam sends notifications to.

To use the Developer Dashboard to subscribe to event notifications, refer to the following section.

There are several backend libraries you can subscribe to to receive user trips event data. We provide three libraries for location and events subscription.

For detailed information on how to integrate our JavaScript, Go and Python libraries, refer to the following sections.

Export Trip

The Export trip API call consolidates the trip summary in a readable format and exports the data to your system.

The different formats supported by Roam are csv, gpx, json and geojson. Refer to the following section for the API.

Delete Trip

The Delete Trip method deletes the trip regardless of its state.

To instantiate the Delete Trip method on Android and iOS, refer the following section.

The Delete Trip API makes a soft delete of the trip for the given trip ID.

Error Codes

The following are some of the commonly found codes indicating client errors.

Code

Message

Description

Live Tracking Link

Now that you know how to instantiate our SDK methods and how the APIs function, you can create, start and control the trips using the same. You can publish location updates and also subscribe to the trip using our Roam SDK. To receive real-time location updates, we have made a provision to subscribe to Webhooks and Backend libraries. However, you can also track the trip using our Roam .

The Roam Tracking dashboard is a fully responsive, platform compatible, and an easy-to-use interface that helps track the end-user location during a trip.

You can either provide the UserID or the TripID to start tracking. You can also create a new user with an existing API Key.

The Tracking dashboard shows the following:

The number of stops in the created trip.
The total distance traveled from the start to the end location.
The duration taken to travel the distance.
The arrival and departure timestamps for the entry and exit events at each stop location.
ID of the end-user who traversed the distance.

In the above example, we have created a trip with three stop locations. Once the trip is created and started, the stop locations are visible on the tracking dashboard in yellow.

Check out the video below for a short demo of the tracking dashboard.

Once the trip is ended, you can see the start point indicated in green, stop locations in yellow, and the endpoint in red.

Quickstart (Android)

The Roam Android SDK makes it quick and easy to build a location tracker for your Android app. We provide powerful and customizable tracking modes and features.

Requirements

To use the Roam SDK,

Get yourself a free Roam Account. No credit card is required.
Create a project and add an Android app to the project.
You need the PUBLISHABLE_KEY (available in your project settings) to initialize the SDK.

Now, you’re ready to integrate the SDK into your Android application.

Roam Android SDK requires Android Studio 2.0 or later and is compatible with apps targeting Android SDK Version 16 or above.

Run the example application

The Roam Example repository on GitHub includes sample applications that demonstrate the use of the v3 Roam SDK for Android.

To run an example app, clone this repository, navigate to the example app in paths Example/ , add your publishable YOUR-PUBLISHABLE-KEY key in MainApplication.java, and run the app.

Make sure the package name is the same as the one registered on our Roam dashboard.

Android Studio Setup

To use the Android SDK in a project, add the SDK as a build dependency and sync the project.

Go to Android Studio > New Project > Minimum SDK
Select API 16: Android 4.1.0 (Jelly Bean) or higher and create a project
After you create a new project, open Gradle Scripts > build.gradle (Project: <your_project>) and do the following:
1. Add the following to the build script {repositories {}} section of the build.gradle (Project)file:
  mavenCentral()

Sync and close build.gradle (Project: <your_project>)

SDK Installation

Gradle Installation

To install the SDK for your project via Gradle in Android Studio, add the maven below to your project build.gradle file.

repositories {
    maven {
        url 'https://com-roam-android.s3.amazonaws.com/'
    }
}

add the dependencies below to your app build.gradle file.

dependencies {
 implementation 'com.roam.sdk:roam-android:0.1.20'
}

Then sync Gradle.

Manual Installation

Download and unzip the Roam SDK.

Open Android Studio and add the SDK Roam.aar as a module using File > New > New Module > Import .JAR/.AAR Package.
Once Gradle is finished, click File > Project Structure again.
Click on the Dependencies tab > click App > click the “+” icon in the top left of the Declared Dependencies section > select Module Dependency > click on Roam-release > press Ok and wait for Gradle to sync again.
Make sure to include the dependencies separately and sync your project.

dependencies {
    implementation 'com.google.android.gms:play-services-location:17.0.0'
    implementation 'com.squareup.retrofit2:retrofit:2.6.2'
    implementation 'com.squareup.retrofit2:converter-gson:2.1.0'
    implementation 'org.eclipse.paho:org.eclipse.paho.client.mqttv3:1.2.4'
    implementation 'org.eclipse.paho:org.eclipse.paho.android.service:1.1.1'
}

Initialize the SDK

Roam SDK offers a flexible method of initialization, allowing developers to seamlessly integrate our services into their applications. With our latest update, we've introduced a new initialization approach using Manifest file. This method provides an effortless way to set up your Roam SDK without the need for additional code.

Using Manifest file Initialization:

Optional Parameter: Publish Key
- The publishKey parameter in the initialization method is now optional.
- If you've added your Roam publish key to your project's Manifest file, there's no need to pass the publishKey parameter during initialization.
Configure Your Manifest File:
- In your Manifest file, declare your Roam publish key as follows:
```
<meta-data
 android:name="com.roam.lib.sdk.PUBLISH_KEY"
 android:value="${ROAM_PUBLISH_KEY}" />
```
- Replace ${ROAM_PUBLISH_KEY} with your actual Roam publish key.
Using local.properties (Optional):
- Alternatively, you can use a local.properties file to feed the Roam publish key to the Manifest file.
- In your local.properties file, add the following line, replacing XXXXXXXXXXXXXX with your Roam publish key:
```
ROAM_PUBLISH_KEY = XXXXXXXXXXXXXX
```
- To get Roam publish key from local.properties to Manifest, user must have to add following code in build.gradle(app)
```
defaultConfig {
        Properties properties = new Properties()
        properties.load(project.rootProject.file('local.properties').newDataInputStream())
        manifestPlaceholders = [ROAM_PUBLISH_KEY: "${properties.getProperty('ROAM_PUBLISH_KEY')}"]

    }
```
Initialization Code:
- Initialize Roam SDK in your application class as follows:
- If the publish key is added to the Manifest file, the initialize method can be called without passing the publishable key.

Roam.initialize(this)

Roam.initialize(this);

By following these steps, you can seamlessly initialize Roam SDK using manifest file, simplifying the integration process and saving valuable development time.

Using Application class Initialization:

Before initializing the SDK, the below must be imported.

import com.roam.sdk.Roam;

After importing, add the code below under the Application class onCreate() method. The SDK must be initialized before calling any of the other SDK methods.

Roam.initialize(this, "YOUR-SDK-KEY-GOES-HERE")

Roam.initialize(this, "YOUR-SDK-KEY-GOES-HERE");

Request Permission

To request the location for devices running both below/above Android 10, refer to the following piece of code.

if (!Roam.checkLocationServices()) {
	Roam.requestLocationServices(this)
} else if (!Roam.checkLocationPermission()) {
	Roam.requestLocationPermission(this)
} else if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q && !Roam.checkBackgroundLocationPermission()) {
	Roam.requestBackgroundLocationPermission(this)
}

if (!Roam.checkLocationServices()) {
       Roam.requestLocationServices(this);
} else if (!Roam.checkLocationPermission()) {
       Roam.requestLocationPermission(this);
} else if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q && !Roam.checkBackgroundLocationPermission()) {
       Roam.requestBackgroundLocationPermission(this);
}

Location Tracking

Start Tracking

Roam.startTracking(TrackingMode, object:TrackingCallback(){
            override fun onSuccess(p0: String?) {
                //do something
            }

            override fun onError(p0: RoamError?) {
                //do something
            }
        })

Roam.startTracking(TrackingMode, new TrackingCallback() {
            @Override
            public void onSuccess(String s) {
              //do something
            }

            @Override
            public void onError(RoamError roamError) {
              //do something
            }
        });

Specify the tracking modes while you use the Roam.startTrackingmethod.

Tracking Modes

Adaptive Tracking

Roam has three default tracking modes along with a custom version. They differ based on the frequency of location updates and battery consumption. The higher the frequency, the higher the battery consumption. You must use the foreground service for continuous tracking.

Mode

Battery usage

Updates every

Optimized for/advised for

Active

6% - 12%

25 ~ 250 meters

Ride Hailing / Sharing

Balanced

3% - 6%

50 ~ 500 meters

On Demand Services

Passive

0% - 1%

100 ~ 1000 meters

Social Apps

// active tracking
Roam.startTracking(RoamTrackingMode.ACTIVE, object:TrackingCallback(){
            override fun onSuccess(p0: String?) {
                //do something
            }

            override fun onError(p0: RoamError?) {
                //do something
            }
        })
// balanced tracking
Roam.startTracking(RoamTrackingMode.BALANCED, object:TrackingCallback(){
            override fun onSuccess(p0: String?) {
                //do something
            }

            override fun onError(p0: RoamError?) {
                //do something
            }
        })
// passive tracking
Roam.startTracking(RoamTrackingMode.PASSIVE, object:TrackingCallback(){
            override fun onSuccess(p0: String?) {
                //do something
            }

            override fun onError(p0: RoamError?) {
                //do something
            }
        })

// active tracking
Roam.startTracking(RoamTrackingMode.ACTIVE, object:TrackingCallback(){
            override fun onSuccess(p0: String?) {
                //do something
            }

            override fun onError(p0: RoamError?) {
                //do something
            }
        })
// balanced tracking
Roam.startTracking(RoamTrackingMode.BALANCED, object:TrackingCallback(){
            override fun onSuccess(p0: String?) {
                //do something
            }

            override fun onError(p0: RoamError?) {
                //do something
            }
        })
// passive tracking
Roam.startTracking(RoamTrackingMode.PASSIVE, object:TrackingCallback(){
            override fun onSuccess(p0: String?) {
                //do something
            }

            override fun onError(p0: RoamError?) {
                //do something
            }
        })

Distance Interval Tracking

The SDK also provides a custom tracking mode that allows you to customize and build your own tracking modes.

With distance interval tracking you create a tracking mode with a distance interval in meters of your choice.

Type

Unit

Unit Range

Distance Interval

Meters

1m ~ 2500m

Distance between location updates example code:

// Define a custom tracking method with desired distance interval, stop duration and accuracy
val trackingMode = RoamTrackingMode.Builder(<DISTANCE-FILTER-IN-METERS>, <STOP-INTERVAL-IN-SECONDS>)
            .setDesiredAccuracy(RoamTrackingMode.DesiredAccuracy.HIGH)
            .build()
// Start the tracking with the above created custom tracking method
Roam.startTracking(trackingMode, object:TrackingCallback(){
            override fun onSuccess(p0: String?) {
                //do something
            }

            override fun onError(p0: RoamError?) {
                //do something
            }
        })

// Define a custom tracking method with desired distance interval, stop duration and accuracy
RoamTrackingMode trackingMode = new RoamTrackingMode.Builder(<DISTANCE-FILTER-IN-METERS>, <STOP-INTERVAL-IN-SECONDS>)
                .setDesiredAccuracy(RoamTrackingMode.DesiredAccuracy.HIGH)
                .build();
// Start the tracking with the above created custom tracking method
Roam.startTracking(trackingMode, new TrackingCallback() {
            @Override
            public void onSuccess(String s) {
              //do something
            }

            @Override
            public void onError(RoamError roamError) {
              //do something
            }
        });

Time Interval Tracking

With Time Interval Tracking you can create a tracking mode with the time interval (in seconds) of your choice.

Type

Unit

Unit Range

Time Interval

Seconds

10s ~ 10800s

Time between location updates example code:

// Define a custom tracking method with desired time interval and accuracy
val trackingMode = RoamTrackingMode.Builder(<TIME-INTERVAL-IN-SECONDS>)
            .setDesiredAccuracy(RoamTrackingMode.DesiredAccuracy.HIGH)
            .build()
// Start the tracking with the above created custom tracking method
Roam.startTracking(trackingMode, object:TrackingCallback(){
            override fun onSuccess(p0: String?) {
                //do something
            }

            override fun onError(p0: RoamError?) {
                //do something
            }
        })

// Define a custom tracking method with desired time interval and accuracy
RoamTrackingMode trackingMode = new RoamTrackingMode.Builder(<TIME-INTERVAL-IN-SECONDS>)
                .setDesiredAccuracy(RoamTrackingMode.DesiredAccuracy.HIGH)
                .build();
// Start the tracking with the above created custom tracking method
Roam.startTracking(trackingMode, new TrackingCallback() {
            @Override
            public void onSuccess(String s) {
              //do something
            }

            @Override
            public void onError(RoamError roamError) {
              //do something
            }
        });

You may see a delay if the user's device is in low power mode or has connectivity issues.

Stop Tracking

To stop tracking, use the method below.

Roam.stopTracking(object : TrackingCallback {
            override fun onSuccess(s: String) {
              //do something
            }
            override fun onError(roamError: RoamError) {
              //do something
            }
        })

Roam.stopTracking(new TrackingCallback() {
            @Override
            public void onSuccess(String s) {
              //do something
            }

            @Override
            public void onError(RoamError roamError) {
              //do something
            }
        });

Location Listeners

Listeners are needed to consume the location or event data from the SDK. To enable listeners, ensure the following:

To listen to location updates, create a class that extends RoamReceiver.
Register the receiver by adding a receiver element to the application element in your manifest.

Note: For self-tracking, you can only listen to only location, error, and offline trips status data since the locations are not being sent to our servers for processing events.

<application>
        ...
     <receiver android:name=".LocationReceiver"
                    android:enabled="true"
                    android:exported="false">
         <intent-filter>
         <action android:name="com.roam.android.RECEIVED"/>
         </intent-filter>
     </receiver>
         ...
</application>

Add the code to the receiver.

class LocationReceiver: RoamReceiver() {
    override fun onLocationUpdated(context: Context?, roamLocations: MutableList<RoamLocation>?) {
        super.onLocationUpdated(context, roamLocations)
        // receive own location updates here
        // do something with location data using location
            for (roamLocation in roamLocations!!){
                roamLocation.activity
                roamLocation.recordedAt
                roamLocation.timezoneOffset
                roamLocation.metadata
                roamLocation.batteryStatus
                roamLocation.networkStatus
                roamLocation.location.latitude
                roamLocation.location.longitude
                roamLocation.location.bearing
                roamLocation.location.altitude
                roamLocation.location.accuracy
                roamLocation.location.speed
                roamLocation.location.provider
                roamLocation.location.time
                roamLocation.location.verticalAccuracyMeters
            }
    }

    override fun onError(context: Context?, roamError: RoamError?) {
        super.onError(context, roamError)
        // receive error message here
         roamError?.code
         roamError?.message
    }
}

public class LocationReceiver extends RoamReceiver {

    @Override
    public void onLocationUpdated(Context context, List<RoamLocation> roamLocations) {
        super.onLocationUpdated(context, roamLocations);
        // receive own location updates here
        // do something with location data using location
        for(RoamLocation roamLocation: roamLocations){
             roamLocation.getActivity();
             roamLocation.getRecordedAt();
             roamLocation.getTimezoneOffset();
             roamLocation.getMetadata();
             roamLocation.getBatteryStatus();
             roamLocation.getNetworkStatus();
             roamLocation.getLocation().getLatitude();
             roamLocation.getLocation().getLongitude();
             roamLocation.getLocation().getBearing();
             roamLocation.getLocation().getAltitude();
             roamLocation.getLocation().getAccuracy();
             roamLocation.getLocation().getSpeed();
             roamLocation.getLocation().getProvider();
             roamLocation.getLocation().getTime();
             roamLocation.getLocation().getVerticalAccuracyMeters();
        }
    }

    @Override
    public void onError(Context context, RoamError roamError) {
        super.onError(context, roamError);
        // receive error message here
         roamError.getCode();	
         roamError.getMessage();
    }
}

Batch Configuration

Batch configuration lets you control the number of location data updates being received in the location listener with the desired frequency and window.

Set Batch Configuration

As the name suggests, this method sets the configuration parameters.

The NetworkState.BOTH indicates the state in which the updates are to be received. It can either be set to online, offline, or both.
The batchCount indicates the size of the location batch.
The batchWindow indicates the time interval for every consecutive update (frequency of updates).

By default, the batch configuration values for both batch count and window are set to 1 and 0 respectively.

Roam.setBatchReceiverConfig(
    NetworkState.BOTH,
    batchCount,
    batchWindow,
    object : RoamBatchReceiverCallback {
        override fun onSuccess(list: List<BatchReceiverConfig>) {
            list[i].networkState
            list[i].batchCount
            list[i].batchWindow
        }
        override fun onFailure(roamError: RoamError) {
            roamError.code
            roamError.message
        }
    })

Roam.setBatchReceiverConfig(NetworkState.BOTH, batchCount,
batchWindow, new RoamBatchReceiverCallback() {
@Override
           public void onSuccess(List<BatchReceiverConfig> batchReceiverConfig) {
                 batchReceiverConfig.get(i).getNetworkState();
                 batchReceiverConfig.get(i).getBatchCount();
                 batchReceiverConfig.get(i).getBatchWindow();
}
@Override
           public void onFailure(RoamError error) {
              error.getMessage();
              error.getCode();
} });

Consider the following call,

Roam.setBatchConfig("NetworkState.Both", 5 , 60)

Success Callback - We receive a list of BatchReceiveConfig objects.

Example response:

[{"batchCount":5,"batchWindow":10,"networkState":"OFFLINE"}, {"batchCount":5,"batchWindow":10,"networkState":"ONLINE"}]

Error Callback: We receive a RoamError object in the error callback.

The available details to get from the RoamError object are: error.getMessage() and error.getCode()

Get Batch Configuration

The get receiver config method allows the user to get the current batch configuration for the location listener.

Roam.getBatchReceiverConfig(object : RoamBatchReceiverCallback {
    override fun onSuccess(list: List<BatchReceiverConfig>) {
        list[i].networkState
        list[i].batchCount
        list[i].batchWindow
    }
    override fun onFailure(roamError: RoamError) {
        roamError.code
        roamError.message
    }
})

Roam.getBatchReceiverConfig(new RoamBatchReceiverCallback() {

@Override
           public void onSuccess(List<BatchReceiverConfig> batchReceiverConfig) {
                 batchReceiverConfig.get(i).getNetworkState();
                 batchReceiverConfig.get(i).getBatchCount();
                 batchReceiverConfig.get(i).getBatchWindow();
}
@Override
           public void onFailure(RoamError error) {
              error.getMessage();
              error.getCode();
} });

The response for the above code is the same as that of the Set Receiver Config method.

Reset Batch Configuration

The Reset Batch Configuration method allows the user to reset the batch config for the location listener.

Roam.resetBatchReceiverConfig(object : RoamBatchReceiverCallback {
    override fun onSuccess(list: List<BatchReceiverConfig>) {
        list[i].networkState
        list[i].batchCount
        list[i].batchWindow
    }
    override fun onFailure(roamError: RoamError) {
        roamError.code
        roamError.message
    }
})

Roam.resetBatchReceiverConfig(new RoamBatchReceiverCallback() {
@Override
           public void onSuccess(List<BatchReceiverConfig> batchReceiverConfig) {
                 batchReceiverConfig.get(i).getNetworkState();
                 batchReceiverConfig.get(i).getBatchCount();
                 batchReceiverConfig.get(i).getBatchWindow();
}
@Override
           public void onFailure(RoamError error) {
              error.getMessage();
              error.getCode();
} });Roam.resetBatchReceiverConfig(object : RoamBatchReceiverCallback {
    override fun onSuccess(list: List<BatchReceiverConfig>) {
        list[i].networkState
        list[i].batchCount
        list[i].batchWindow
    }
    override fun onFailure(roamError: RoamError) {
        roamError.code
        roamError.message
    }
})

Geofencing

Explore Roam's Geofencing documentation.

Geofence is a virtual perimeter for a real-world geographical area. A geofence can be dynamically generated around a location point with a radius (circle geofence) or with a pre-defined set of boundaries (polygon geofence) for stores, neighborhoods, or even cities.

Every time the end user enters or exits a geofence with a location aware device, events are generated. These events can be used to alert the user or perform actions in the backend.

Base URL

The Roam API is organized around . Our API has predictable resource-oriented URLs, accepts request bodies, returns responses, and uses standard HTTP response codes, authentication, and verbs.

Authentication

Roam API uses API keys to authenticate requests. You can view and manage your API keys in the Roam Dashboard.

All API requests must be made over . Calls made over plain HTTP and API requests without authentication will fail.

Create Geofence

Geofences can be created using the Roam API. They can be created over a circle or a polygon geometry. By default, a geofence is applicable to all the users of a project but can also be restricted to a group of users. Geofences can be configured to be enabled for a specified time interval.

Geofence Types:

Roam allows you to create two geofence geometry types:

Circle
Polygon

Circle Geofence

A circular geofence is the region around a location point defined by a radius. To create a circular geofence, the required body parameters are coordinates, and geometry_radius .

Sample Request // Circle Geofence

Sample Response // Circle Geofence

Polygon Geofence

A polygon geofence is the area defined by a set of boundaries forming any shape around a location area. To create a polygon geofence, the required body parameters are geometry_type andcoordinates.

Same Request to create a Polygon geofence

Sample Response

User Specific Geofence

You can monitor geofence events for a specific user or a list of users by passing user_ids which are generated at the time of creating a user. In the case of a user group, you may pass the group_id. If by default, user_ids and group_ids are not specified, then the geofence is activated for all the users of the project.

Based on the User ID

Pass a user_id under the "user_ids" body parameter. Pass an array ofuser_idsto create a geofence specific to multiple users.

Sample Request for single User ID

Sample Request for multiple User IDs

Based on Group ID

Pass a group_id under the "group_ids" body parameter. You may pass multiple group IDs into an array to create a geofence specific to those groups.

Sample Request for single Group ID

Sample Request for multiple Group ID

Time-Aware Geofence

You can create time aware geofences to trigger events between a specific time range. You can do so by passing the date and time as the second and third elements of the array to theis_enabledfield in the body section.

During the specified time interval, the entry and exit events will be triggered. However, outside the time interval, you need to ensure that the"is_enabled" field is set to "false".

Sample Response

Personalize Geofence

Description and Metadata

Adding a description and metadata can help identify and personalize the geofences while displaying them on a map. You can add this information while creating a geofence or updating a geofence.

Sample Request

Sample Response

Tags and Color Codes

Adding tag can help filter geofences easily. This field is optional. When a geofence event is generated, the tag is also sent along with the event.

color_code defines the color of the geofence and how it is displayed on the dashboard. Hex Code for CSS colors should be passed in this field without '#'.

Sample Request

Sample Response

Update Geofence

Geofence can be updated using PUT API request along with the geofence endpoint.

The following are the values that can be updated once after the Geofence is created.

The values that cannot be updated once the geofence is created are:

Get Geofence

This API gives you a filtered list of geofences. You can filter by geofence_id, created_at, start_date and end_date fields, user_id and group_id.

Sample Request

Using start_date and end_date

This filter allows you to filter the geofences within the given date range. These are non-mandatory fields and will be set to the current date by default.

You may also pass either the start_date or the end_date as filters. If you pass a specific start date, make sure it is less than the current date since the end date will be set default to the current date. If you pass a specific end_date and leave the start_date empty, make sure it is greater than the current date.

Below are the acceptable formats for the date filter:

Using geofence_id

You can also use geofence_id as a filter. If you pass a valid geofence_id, the results will be filtered to the given geofence id.

You can get the geofence_id when you create a geofence using the Create Geofence API.

If you use a geofence_id as a filter along with a date filter, the date filters will not be considered.

Passing an empty or invalid geofence_id, will return an error.

Make sure the geofence_id used here belongs to the same project linked to the API key.

Using user_id

Similar to the geofence_id, you can fetch the list of geofences that are tagged with the given user_id, which was initially used during the Create Geofence API. The user_id is created within the SDK during thecreateUser method and returns a unique user_id for identification within the Roam environment.

If you use theuser_id as a filter along with the date filter, the date filters will not be considered. And if you pass an empty or invalid user_id, the API will return an error.

Make sure the user_id used here belongs to the same project linked with the API key.

Using group_id

To fetch the list of geofences that are tagged with the given group_id, which was initially used during the Create Geofence API, you can pass the group_id in the header parameter.

You can get the group_id when you create a group using the Create Group API.

If you use group_id as a filter along with the date filter, the date filters will not be considered. Passing an empty or invalid group_id, will return an error.

Make sure the group_id used here belongs to the same project linked with the API key.

Geofence Events

Roam's geofence feature has 2 possible events that can be triggered based on user behavior:

Geofence Entry Event - triggered when a user enters the defined geofence area
Geofence Exit Event - triggered when a user exits from the defined geofence area

Sample Events:

Geofence Entry Event:

Geofence Exit Event:

Enable Events

To enable geofence events for a user, you’ll need to ensure the following:

Under Roam.toggleEvents the geofence flag must be set to true ,and
Ensure you’re publishing location to the server.

Toggle Events docs Links: | | |

Publish Locations docs links: | |

If the geofence flag is false for a user and location is not being published, then geofence events will not be processed for their location updates.

Events via Webhook

Roam supports the posting of events to webhooks in real-time. To enable posting events via webhook, first the webhook URL needs to be configured in the project using the dashboard (Project Settings -> integration) and should be enabled.

Events via API

Geofence events can be retrieved using the Roam API. The Get Events API lets you fetch entry or exit events of the users from your event-enabled geofences. The API also lets you filter by user, geofence, location, and more.

Delete Geofence

Delete any existing geofences from your projects by using the geofence_id.

You can delete the geofence with the delete API using the following two options:

Option 1: Delete geofence individually

You can delete one geofence at a time by passing the geofence ID as a query parameter.

Option 2: Delete geofences in bulk

By passing multiple geofence_ids as a body parameter, you can delete up to 200 geofences at a time.

Error Codes

Pub/Sub Locations (Android)

Explore how to publish and subscribe locations for Android.

Creating Users

Once our SDK is initialized, we need to create or get a user to start the tracking and use other methods. Each user created will have a unique Roam identifier which will be used later to login and access developer APIs. You can call it Roam userId.

Adding metadata to users is optional and you can pass null while creating users to ignore that field.

// create user with meta-data and description
// Declare meta-data as json
// Description as string
val metadata = JSONObject() 
metadata.put("key", "value") 
Roam.createUser("SET-USER-DESCRIPTION-HERE", metadata, object : RoamCallback {
      override fun onSuccess(roamUser: RoamUser) {
        // Access Roam user data below
        // roamUser.getUserId();
        // roamUser.getDescription();
        // roamUser.getEventListenerStatus();
        // roamUser.getLocationListenerStatus();
        // roamUser.getLocationEvents();
        // roamUser.getGeofenceEvents();
        // roamUser.getMovingGeofenceEvents();
        // roamUser.getTripsEvents();
      }

      override fun onFailure(roamError: RoamError) {
        // Access the error code & message below
        // roamError.getCode()
        // roamError.getMessage()
      }
})

// update user with meta-data and description
// Declare meta-data as dictionary
// Description as string
JSONObject metadata = new JSONObject(); 
metadata.put("key", "value"); 
Roam.createUser("YOUR-USER-DESCRIPTION-GOES-HERE", metadata, new RoamCallback() {
            @Override
            public void onSuccess(RoamUser roamUser) {
                // Access Roam user data below
                // roamUser.getUserId();
                // roamUser.getDescription();
                // roamUser.getEventListenerStatus();
                // roamUser.getLocationListenerStatus();
                // roamUser.getLocationEvents();
                // roamUser.getGeofenceEvents();
                // roamUser.getMovingGeofenceEvents();
                // roamUser.getTripsEvents();
            }

            @Override
            public void onFailure(RoamError roamError) {
                // Access error code & message below
                // roamError.getCode();
                // roamError.getMessage();
            }
        });

The "user description" option can be used to update your user information such as name, address or add an existing user ID. Make sure the information is encrypted if you are planning to save personal user information like email or phone number.

You can always set or update user descriptions and meta-data later using the code below.

// update user with meta-data and description
// Declare meta-data as dictionary
// Description as string
val metadata = JSONObject() 
metadata.put("key", "value") 
Roam.setDescription("SET-USER-DESCRIPTION-HERE", metadata)

// update user with meta-data and description
// Declare meta-data as dictionary
// Description as string
JSONObject metadata = new JSONObject(); 
metadata.put("key", "value"); 
Roam.setDescription("SET-USER-DESCRIPTION-HERE", metadata);

Get User

If you already have a Roam userID that you would like to reuse instead of creating a new user, use the below to get the user session.

Roam.getUser("ROAM-USER-ID", object : RoamCallback {
      override fun onSuccess(roamUser: RoamUser) {
        // Access Roam user data below
        // roamUser.getUserId();
        // roamUser.getDescription();
        // roamUser.getEventListenerStatus();
        // roamUser.getLocationListenerStatus();
        // roamUser.getLocationEvents();
        // roamUser.getGeofenceEvents();
        // roamUser.getMovingGeofenceEvents();
        // roamUser.getTripsEvents();
      }

      override fun onFailure(roamError: RoamError) {
        // Access error code & message below
        // roamError.getCode()
        // roamError.getMessage()
      }
})

Roam.getUser("YOUR-ROAM-USER-ID", new RoamCallback() {
            @Override
            public void onSuccess(RoamUser roamUser) {
                // Access Roam user data below
                // roamUser.getUserId();
                // roamUser.getDescription();
                // roamUser.getEventListenerStatus();
                // roamUser.getLocationListenerStatus();
                // roamUser.getLocationEvents();
                // roamUser.getGeofenceEvents();
                // roamUser.getMovingGeofenceEvents();
                // roamUser.getTripsEvents();
            }

            @Override
            public void onFailure(RoamError roamError) {
                // Access error code & message below
                // roamError.getCode();
                // roamError.getMessage();
            }
        });

Location Tracking

To publish and subscribe to location data, startSelfTracking methods have to be changed to startTracking

Start Tracking

Roam.startTracking(TrackingMode, object:TrackingCallback(){
            override fun onSuccess(s: String?) {
                //do something
            }

            override fun onError(roamError: RoamError?) {
                //do something
            }
        })

Roam.startTracking(TrackingMode, new TrackingCallback() {
            @Override
            public void onSuccess(String s) {
              //do something
            }

            @Override
            public void onError(RoamError roamError) {
              //do something
            }
        });

Specify the tracking mode while you use the startTracking method Roam.startTracking

Tracking Modes

Mode

Battery usage

Updates every

Optimised for/advised for

Active

6% - 12%

25 ~ 250 meters

Ride Hailing / Sharing

Balanced

3% - 6%

50 ~ 500 meters

On Demand Services

Passive

0% - 1%

100 ~ 1000 meters

Social Apps

// active tracking
Roam.startTracking(RoamTrackingMode.ACTIVE, object:TrackingCallback(){
            override fun onSuccess(s: String?) {
                //do something
            }

            override fun onError(roamError: RoamError?) {
                //do something
            }
        })
// balanced tracking
Roam.startTracking(RoamTrackingMode.BALANCED, object:TrackingCallback(){
            override fun onSuccess(s: String?) {
                //do something
            }

            override fun onError(roamError: RoamError?) {
                //do something
            }
        })
// passive tracking
Roam.startTracking(RoamTrackingMode.PASSIVE, object:TrackingCallback(){
            override fun onSuccess(s: String?) {
                //do something
            }

            override fun onError(roamError: RoamError?) {
                //do something
            }
        })

// active tracking
Roam.startTracking(RoamTrackingMode.ACTIVE, new TrackingCallback() {
            @Override
            public void onSuccess(String s) {
              //do something
            }

            @Override
            public void onError(RoamError roamError) {
              //do something
            }
        });
// balanced tracking
Roam.startTracking(RoamTrackingMode.BALANCED, new TrackingCallback() {
            @Override
            public void onSuccess(String s) {
              //do something
            }

            @Override
            public void onError(RoamError roamError) {
              //do something
            }
        });
// passive tracking
Roam.startTracking(RoamTrackingMode.PASSIVE, new TrackingCallback() {
            @Override
            public void onSuccess(String s) {
              //do something
            }

            @Override
            public void onError(RoamError roamError) {
              //do something
            }
        });

Custom Tracking Modes

Our SDK also provides a custom tracking mode that allows you to customize and build your own tracking modes.

Type

Unit

Unit Range

Distance Interval

Meters

1m ~ 2500m

Time Interval

Seconds

10s ~ 10800s

Distance between location updates example code:

// Define a custom tracking method with desired distance interval, stop duration and accuracy
val trackingMode = RoamTrackingMode.Builder(<DISTANCE-FILTER-IN-METERS>, <STOP-INTERVAL-IN-SECONDS>)
                  .setDesiredAccuracy(RoamTrackingMode.DesiredAccuracy.HIGH)
                  .build()
// Start the tracking with the above created custom tracking method
Roam.startTracking(trackingMode, object:TrackingCallback(){
            override fun onSuccess(s: String?) {
                //do something
            }

            override fun onError(roamError: RoamError?) {
                //do something
            }
        })

// Define a custom tracking method with desired distance interval, stop duration and accuracy
RoamTrackingMode trackingMode = new RoamTrackingMode.Builder(<DISTANCE-FILTER-IN-METERS>, <STOP-INTERVAL-IN-SECONDS>)
                .setDesiredAccuracy(RoamTrackingMode.DesiredAccuracy.HIGH)
                .build();
// Start the tracking with the above created custom tracking method
Roam.startTracking(trackingMode, new TrackingCallback() {
            @Override
            public void onSuccess(String s) {
              //do something
            }

            @Override
            public void onError(RoamError roamError) {
              //do something
            }
        });

Time between location updates example code:

// Define a custom tracking method with desired time interval and accuracy
val trackingMode = RoamTrackingMode.Builder(<TIME-INTERVAL-IN-SECONDS>)
                  .setDesiredAccuracy(RoamTrackingMode.DesiredAccuracy.HIGH)
                  .build()
// Start the tracking with the above created custom tracking method
Roam.startTracking(trackingMode, object:TrackingCallback(){
            override fun onSuccess(s: String?) {
                //do something
            }

            override fun onError(roamError: RoamError?) {
                //do something
            }
        })

// Define a custom tracking method with desired time interval and accuracy
RoamTrackingMode trackingMode = new RoamTrackingMode.Builder(<TIME-INTERVAL-IN-SECONDS>)
                .setDesiredAccuracy(RoamTrackingMode.DesiredAccuracy.HIGH)
                .build();
// Start the tracking with the above created custom tracking method
Roam.startTracking(trackingMode, new TrackingCallback() {
            @Override
            public void onSuccess(String s) {
              //do something
            }

            @Override
            public void onError(RoamError roamError) {
              //do something
            }
        });

You may see a delay if the user's device is in low power mode or has connectivity issues.

Stop Tracking

To stop the tracking use the below method.

Roam.stopTracking(object : TrackingCallback {
            override fun onSuccess(s: String) {
              //do something
            }
            override fun onError(roamError: RoamError) {
              //do something
            }
        })

Roam.stopTracking(new TrackingCallback() {
            @Override
            public void onSuccess(String s) {
              //do something
            }

            @Override
            public void onError(RoamError roamError) {
              //do something
            }
        });

Publish Locations

Publishing will help publish location data that will be stored in our database and sent to Roam servers for further processing.

Location data will be published and sent to the Roam servers for further processing. The data will be saved on our database servers.

val locationData = RoamPublish.Builder().build()
Roam.publishAndSave(locationData, object : PublishCallback {
            override fun onSuccess(s: String) {
                //do something
            }
            override fun onError(roamError: RoamError) {
                //do something
            }
        })

RoamPublish locationData = new RoamPublish.Builder().build();
Roam.publishAndSave(locationData, new PublishCallback() {
            @Override
            public void onSuccess(String s) {
              //do something
            }

            @Override
            public void onError(RoamError roamError) {
              //do something
            }
        });

You can now send custom meta-data json values along with location data in publishAndSavemethod.

val data = JSONObject()
data.put("Key", "Value")
val roamPublish = RoamPublish.Builder()
            .metadata(data)
            .build()
Roam.publishAndSave(roamPublish, object : PublishCallback {
            override fun onSuccess(s: String) {
                //do something
            }
            override fun onError(roamError: RoamError) {
                //do something
            }
        })

JSONObject data = new JSONObject();
data.put("Key", "Value");
RoamPublish roamPublish = new RoamPublish.Builder()
                    .metadata(data)
                    .build();
Roam.publishAndSave(roamPublish, new PublishCallback() {
            @Override
            public void onSuccess(String s) {
               //do something
            }

            @Override
            public void onError(RoamError roamError) {
              //do something
            }
        });

To stop publishing locations,

Roam.stopPublishing(object : PublishCallback {
            override fun onSuccess(s: String) {
                //do something
            }
            override fun onError(roamError: RoamError) {
                //do something
            }
        })

Roam.stopPublishing(new PublishCallback() {
            @Override
            public void onSuccess(String s) {
                //do something
            }

            @Override
            public void onError(RoamError roamError) {
                //do something
            }
        });

Now that you have enabled the location listener, use the below method to subscribe to your own or other user's location updates and events.

Roam.subscribe(TYPE, "ROAM-USER-ID", object : SubscribeCallback {
            override fun onSuccess(s: String, s1: String) {
                //do something
            }
            override fun onError(roamError: RoamError) {
                //do something
            }
        })

Roam.subscribe(TYPE, "USER-ID", new SubscribeCallback() {
            @Override
            public void onSuccess(String s, String s1) {
              //do something
            }

            @Override
            public void onError(RoamError roamError) {
              //do something
            }
        });

UnSubscribe

Roam.unSubscribe(TYPE, "ROAM-USER-ID", object : SubscribeCallback {
            override fun onSuccess(s: String, s1: String) {
                //do something
            }
            override fun onError(roamError: RoamError) {
                //do something
            }
        })

Roam.unSubscribe(TYPE, "ROAM-USER-ID", new SubscribeCallback() {
            @Override
            public void onSuccess(String s, String s1) {
              //do something
            }

            @Override
            public void onError(RoamError roamError) {
              //do something
            }
        });

Type

Description

Roam.Subscribe.EVENTS

Subscribe to your own events.

Roam.Subscribe.LOCATION

Subscribe to your own location (or) other user's location updates.

Roam.Subscribe.BOTH

Subscribe to your own events and location (or) other user's location updates.

You can pass an empty user_id which is an optional field from v0.0.14 to unsubscribe from all the users.

Location Listener

Before adding listeners for locations and other data, we need to toggle the listener flags for the user in order to get the data.

To do that, you need to set the location and event listener to true using the below method. By default, the status will be set to false and needs to be set to true in order to stream the location and event updates to the same device or other devices.

Roam.toggleListener(locations, events, object : RoamCallback {
    override fun onSuccess(roamUser: RoamUser) {
        // do something when toggle listener success
        // access location listener status with roamUser.getLocationListenerStatus()
        // access event listener status with roamUser.getEventListenerStatus()
    }

    override fun onFailure(roamError: RoamError) {
        // do something when toggle listener failure
    }
})

Roam.toggleListener(true, true, new RoamCallback() {
            @Override
            public void onSuccess(RoamUser roamUser) {
	              // Access Roam user data below
                // roamUser.getUserId();
                // roamUser.getDescription();
                // roamUser.getEventListenerStatus();
                // roamUser.getLocationListenerStatus();
                // roamUser.getLocationEvents();
                // roamUser.getGeofenceEvents();
                // roamUser.getMovingGeofenceEvents();
                // roamUser.getTripsEvents();
            }

            @Override
            public void onFailure(RoamError roamError) {
      	        // Access error code & message below
                // roamError.getCode();
                // roamError.getMessage();
            }
        });

You can also get the current status of listeners with the below method.

Roam.getListenerStatus(object : RoamCallback {
    override fun onSuccess(roamUser: RoamUser) {
        // do something when get listener status success
        // get location listener status with roamUser.getLocationListenerStatus
        // get event listener status with roamUser.getEventListenerStatus
    }
    override fun onFailure(roamError: RoamError) {
        // do something when get listener status failure
    }
})

Roam.getListenerStatus(new RoamCallback() {
            @Override
            public void onSuccess(RoamUser roamUser) {
	              // Access Roam user data below
                // roamUser.getUserId();
                // roamUser.getDescription();
                // roamUser.getEventListenerStatus();
                // roamUser.getLocationListenerStatus();
                // roamUser.getLocationEvents();
                // roamUser.getGeofenceEvents();
                // roamUser.getMovingGeofenceEvents();
                // roamUser.getTripsEvents();
            }

            @Override
            public void onFailure(RoamError roamError) {
      	        // Access error code & message below
                // roamError.getCode();
                // roamError.getMessage();
            }
      });

Toggle Events

To listen to events on the server-side, you should enable events for the user using the method below.

Roam.toggleEvents(geofence, trip, location, movingGeofence, object : RoamCallback {
    override fun onSuccess(roamUser: RoamUser) {
        // do something when toggle events success
        // access location event status with roamUser.getLocationEvents()
        // access geofence event status with roamUser.getGeofenceEvents()
        // access trip events status with roamUser.getTripsEvents()
        // get moving geofence event status with roamUser.getMovingGeofenceEvents()
    }

    override fun onFailure(error: roamError) {
        // do something when toggle events failure
    }

Roam.toggleEvents(true, true, true, true, new RoamCallback() {
            @Override
            public void onSuccess(RoamUser roamUser) {
	              // Access Roam user data below
                // roamUser.getUserId();
                // roamUser.getDescription();
                // roamUser.getEventListenerStatus();
                // roamUser.getLocationListenerStatus();
                // roamUser.getLocationEvents();
                // roamUser.getGeofenceEvents();
                // roamUser.getMovingGeofenceEvents();
                // roamUser.getTripsEvents();
            }

            @Override
            public void onFailure(RoamError roamError) {
      	        // Access error code & message below
                // roamError.getCode();
                // roamError.getMessage();
            }
        });

Location Listener

Now, to listen to location updates and events, create a class that extends RoamReceiver. Then register the receiver by adding a receiver element to the application element in your manifest.

<application>
        ...
     <receiver android:name=".LocationReceiver"
                    android:enabled="true"
                    android:exported="false">
         <intent-filter>
         <action android:name="com.roam.android.RECEIVED"/>
         </intent-filter>
     </receiver>
         ...
</application>

Then add the code to the receiver.

public class LocationReceiver : RoamReceiver() {
    override fun onLocationUpdated(context: Context, roamLocations: MutableList<RoamLocation>) {
        // receive own location updates here
        // do something with location data using location
    }

    override fun onLocationReceived(context: Context, roamLocationReceived: RoamLocationReceived) {
        // receive other user's location updates here
        // do something with location
    }
    
    override fun onEventReceived(context: Context, roamEvent: RoamEvent) {
        //access event data here
    }

    override fun onReceiveTripStatus(context: Context, listener:List<TripStatusListener>) {
        // receive real time trip status here
        // do something with trip status data    
    }

    override fun onError(context: Context, roamError: RoamError) {
        //access error data here
    }
}

public class LocationReceiver extends RoamReceiver {

    @Override
    public void onLocationUpdated(Context context, List<RoamLocation> roamLocations) {
        // receive own location updates here
		    // do something with location data using location
    }

    @Override
    public void onLocationReceived(Context context, RoamLocationReceived roamLocationReceived) {
        // receive other user's location updates here
    		// do something with location
    }

    @Override
    public void onEventReceived(Context context, RoamEvent roamEvent) {
    		//access event data here
    }

    @Override
    public void onReceiveTripStatus(Context context,List<TripStatusListener> listener) {
                // receive real time trip status here
                // do something with trip status data    
    }

    @Override
    public void onError(Context context, RoamError roamError) {
         //access error data here
    }
}

Get Trip Summary API

Explore how to get a trip summary with our Trip API

Get Trip Summary

GET https://api.roam.ai/v2/trips/:id/summary

Get the summary of the given trip id.

Path Parameters

Name

Type

Description

id*

String

Retrieves the trip summary with the given ID.

Headers

Name

Type

Description

Authorization*

String

Bearer <API-KEY>

{
   "code": 200,
   "description": "The trip summary for requested id.",
   "message": "trip_summary",
   "trip": {
       "id": "6221bf4393ade81ce90c8c5c",
       "trip_state": "ended",
       "total_distance": 1942.08,
       "total_duration": 328,
       "total_elevation_gain": 52,
       "name": "trip name",
       "description": "trip description",
       "metadata": {
           "Key1": "value1"
       },
       "start_location": {
           "id": "6221bf683d4d460000e33446",
           "metadata": {},
           "address": "Bailey Road, Priyadarshi Nagar, Danapur, Dinapur-Cum-Khagaul, Patna District, Bihar, 801506, India",
           "recorded_at": "2022-03-04T07:27:36.645",
           "geometry": {
               "type": "Point",
               "coordinates": [
                   85.06961939,
                   25.60647234
               ]
           }
       },
       "end_location": {
           "id": "6221c1493d4d460000e334c1",
           "metadata": {},
           "address": "Priyadarshi Nagar, Danapur, Dinapur-Cum-Khagaul, Patna District, Bihar, 800018, India",
           "recorded_at": "2022-03-04T07:35:37.382",
           "geometry": {
               "type": "Point",
               "coordinates": [
                   85.06689824,
                   25.61904625
               ]
           }
       },
       "started_at": "2022-03-04T07:27:36.645",
       "ended_at": "2022-03-04T07:35:37.382",
       "created_at": "2022-03-04T07:26:59.480",
       "updated_at": "2022-03-04T07:35:39.913",
       "user": {
           "id": "6221bc24ffb3fb125a2e2342",
           "name": "",
           "description": "",
           "metadata": {
               "Mobile": "1234567890",
               "Name": "Nikhil"
           }
       },
       "stops": [
           {
               "id": "6221bf4393ade81ce90c8c5b",
               "name": "STOP 1",
               "description": "tea break",
               "metadata": {
                   "Key1": "value1"
               },
               "address": "Bangalore",
               "geometry_radius": 600,
               "geometry": {
                   "type": "Point",
                   "coordinates": [
                       85.30614739,
                       23.5155215
                   ]
               },
               "created_at": "2022-03-04T07:26:59.475",
               "updated_at": "2022-03-04T07:26:59.475",
               "arrived_at": null,
               "departed_at": null
           }
       ],
       "events": [
           {
               "id": "6221bf45b5ef8c40ac13ff5e",
               "trip_id": "6221bf4393ade81ce90c8c5c",
               "location_id": "",
               "user_id": "6221bc24ffb3fb125a2e2342",
               "event_type": "roam:trip:created",
               "created_at": "2022-03-04T07:27:01.615",
               "event_source": "roam:trip",
               "event_version": "1.0"
           },
           {
               "id": "6221bf6e1674e3543f398a40",
               "trip_id": "6221bf4393ade81ce90c8c5c",
               "location_id": "6221bf683d4d460000e33446",
               "user_id": "6221bc24ffb3fb125a2e2342",
               "event_type": "roam:trip:started",
               "created_at": "2022-03-04T07:27:41.257",
               "event_source": "roam:trip",
               "event_version": "1.0"
           },
           {
               "id": "6221c0701674e3543f398a41",
               "trip_id": "6221bf4393ade81ce90c8c5c",
               "location_id": "6221c06d3d4d460000e3346c",
               "user_id": "6221bc24ffb3fb125a2e2342",
               "event_type": "roam:trip:paused",
               "created_at": "2022-03-04T07:31:59.919",
               "event_source": "roam:trip",
               "event_version": "1.0"
           },
           {
               "id": "6221c0e1b5ef8c40ac13ff5f",
               "trip_id": "6221bf4393ade81ce90c8c5c",
               "location_id": "6221c0dd3d4d460000e33492",
               "user_id": "6221bc24ffb3fb125a2e2342",
               "event_type": "roam:trip:resumed",
               "created_at": "2022-03-04T07:33:53.222",
               "event_source": "roam:trip",
               "event_version": "1.0"
           },
           {
               "id": "6221c14d1674e3543f398a42",
               "trip_id": "6221bf4393ade81ce90c8c5c",
               "location_id": "6221c1493d4d460000e334c1",
               "user_id": "6221bc24ffb3fb125a2e2342",
               "event_type": "roam:trip:ended",
               "created_at": "2022-03-04T07:35:41.291",
               "event_source": "roam:trip",
               "event_version": "1.0"
           }
       ],
       "route_indexes": [
           [
               1,
               39
           ],
           [
               40,
               86
           ]
       ],
       "route": [
           {
               "coordinates": {
                   "coordinates": [
                       85.06961939,
                       25.60647234
                   ],
                   "type": "Point"
               },
               "speed": 0,
               "altitude": 110,
               "activity": "STOP",
               "recorded_at": "2022-03-04T07:27:36.645",
               "metadata": null,
               "distance": 0,
               "duration": 0,
               "elevation_gain": 0
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06968719,
                       25.60665091
                   ],
                   "type": "Point"
               },
               "speed": 13,
               "altitude": 129.82,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:28:31.744",
               "metadata": null,
               "distance": 21.01,
               "duration": 55,
               "elevation_gain": 19
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06948914,
                       25.60671479
                   ],
                   "type": "Point"
               },
               "speed": 6,
               "altitude": 130,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:28:41.816",
               "metadata": null,
               "distance": 42.12,
               "duration": 65,
               "elevation_gain": 20
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06929126,
                       25.60677863
                   ],
                   "type": "Point"
               },
               "speed": 14,
               "altitude": 129.38,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:29:04.882",
               "metadata": null,
               "distance": 63.21,
               "duration": 88,
               "elevation_gain": 20
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06904013,
                       25.60685963
                   ],
                   "type": "Point"
               },
               "speed": 24,
               "altitude": 129.91,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:29:09.838",
               "metadata": null,
               "distance": 89.98,
               "duration": 92,
               "elevation_gain": 20
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06883539,
                       25.60692568
                   ],
                   "type": "Point"
               },
               "speed": 7,
               "altitude": 129.44,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:29:16.823",
               "metadata": null,
               "distance": 111.8,
               "duration": 98,
               "elevation_gain": 20
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06863859,
                       25.60698916
                   ],
                   "type": "Point"
               },
               "speed": 12,
               "altitude": 129.26,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:29:30.928",
               "metadata": null,
               "distance": 132.78,
               "duration": 112,
               "elevation_gain": 20
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.0684211,
                       25.60706062
                   ],
                   "type": "Point"
               },
               "speed": 22,
               "altitude": 128.27,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:29:35.939",
               "metadata": null,
               "distance": 156.01,
               "duration": 117,
               "elevation_gain": 20
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06820577,
                       25.60713976
                   ],
                   "type": "Point"
               },
               "speed": 16,
               "altitude": 127.77,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:29:41.011",
               "metadata": null,
               "distance": 179.35,
               "duration": 122,
               "elevation_gain": 20
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06800858,
                       25.60721223
                   ],
                   "type": "Point"
               },
               "speed": 11,
               "altitude": 127.61,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:29:45.849",
               "metadata": null,
               "distance": 200.72,
               "duration": 126,
               "elevation_gain": 20
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06781342,
                       25.60728395
                   ],
                   "type": "Point"
               },
               "speed": 9,
               "altitude": 128.85,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:30:10.860",
               "metadata": null,
               "distance": 221.87,
               "duration": 151,
               "elevation_gain": 21
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06759802,
                       25.60736312
                   ],
                   "type": "Point"
               },
               "speed": 18,
               "altitude": 128.68,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:30:15.998",
               "metadata": null,
               "distance": 245.21,
               "duration": 156,
               "elevation_gain": 21
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06739371,
                       25.60743821
                   ],
                   "type": "Point"
               },
               "speed": 11,
               "altitude": 129.95,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:30:21.892",
               "metadata": null,
               "distance": 267.35,
               "duration": 161,
               "elevation_gain": 23
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.0672014,
                       25.60751067
                   ],
                   "type": "Point"
               },
               "speed": 12,
               "altitude": 128.69,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:30:26.826",
               "metadata": null,
               "distance": 288.27,
               "duration": 165,
               "elevation_gain": 23
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06700945,
                       25.60758558
                   ],
                   "type": "Point"
               },
               "speed": 16,
               "altitude": 128.34,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:30:32.845",
               "metadata": null,
               "distance": 309.26,
               "duration": 171,
               "elevation_gain": 23
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06679251,
                       25.60767003
                   ],
                   "type": "Point"
               },
               "speed": 17,
               "altitude": 128.24,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:30:38.918",
               "metadata": null,
               "distance": 332.97,
               "duration": 177,
               "elevation_gain": 23
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06660112,
                       25.60774419
                   ],
                   "type": "Point"
               },
               "speed": 13,
               "altitude": 128.32,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:30:42.852",
               "metadata": null,
               "distance": 353.88,
               "duration": 180,
               "elevation_gain": 23
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06638153,
                       25.60782928
                   ],
                   "type": "Point"
               },
               "speed": 19,
               "altitude": 127.84,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:30:47.844",
               "metadata": null,
               "distance": 377.87,
               "duration": 184,
               "elevation_gain": 23
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.0661767,
                       25.60790865
                   ],
                   "type": "Point"
               },
               "speed": 26,
               "altitude": 128.25,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:30:52.856",
               "metadata": null,
               "distance": 400.24,
               "duration": 189,
               "elevation_gain": 23
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06594634,
                       25.60799497
                   ],
                   "type": "Point"
               },
               "speed": 31,
               "altitude": 128.76,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:30:55.981",
               "metadata": null,
               "distance": 425.28,
               "duration": 192,
               "elevation_gain": 24
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06573304,
                       25.60807386
                   ],
                   "type": "Point"
               },
               "speed": 31,
               "altitude": 127.26,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:30:58.857",
               "metadata": null,
               "distance": 448.42,
               "duration": 194,
               "elevation_gain": 24
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06547511,
                       25.60817058
                   ],
                   "type": "Point"
               },
               "speed": 34,
               "altitude": 128.9,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:31:01.830",
               "metadata": null,
               "distance": 476.46,
               "duration": 196,
               "elevation_gain": 25
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06521008,
                       25.60824988
                   ],
                   "type": "Point"
               },
               "speed": 31,
               "altitude": 129.79,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:31:04.882",
               "metadata": null,
               "distance": 504.49,
               "duration": 199,
               "elevation_gain": 26
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.0649913,
                       25.6083136
                   ],
                   "type": "Point"
               },
               "speed": 25,
               "altitude": 130,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:31:07.885",
               "metadata": null,
               "distance": 527.56,
               "duration": 202,
               "elevation_gain": 26
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06477762,
                       25.60837584
                   ],
                   "type": "Point"
               },
               "speed": 29,
               "altitude": 130,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:31:11.031",
               "metadata": null,
               "distance": 550.1,
               "duration": 205,
               "elevation_gain": 26
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06452776,
                       25.60844861
                   ],
                   "type": "Point"
               },
               "speed": 32,
               "altitude": 129.09,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:31:13.865",
               "metadata": null,
               "distance": 576.45,
               "duration": 207,
               "elevation_gain": 26
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06426739,
                       25.60851561
                   ],
                   "type": "Point"
               },
               "speed": 31,
               "altitude": 130,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:31:16.873",
               "metadata": null,
               "distance": 603.63,
               "duration": 210,
               "elevation_gain": 27
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06405443,
                       25.60857429
                   ],
                   "type": "Point"
               },
               "speed": 24,
               "altitude": 130,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:31:19.974",
               "metadata": null,
               "distance": 625.98,
               "duration": 213,
               "elevation_gain": 27
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06386509,
                       25.60864441
                   ],
                   "type": "Point"
               },
               "speed": 24,
               "altitude": 129.01,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:31:22.914",
               "metadata": null,
               "distance": 646.52,
               "duration": 215,
               "elevation_gain": 27
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06364274,
                       25.60872913
                   ],
                   "type": "Point"
               },
               "speed": 31,
               "altitude": 128.36,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:31:26.044",
               "metadata": null,
               "distance": 670.75,
               "duration": 218,
               "elevation_gain": 27
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06341159,
                       25.60881739
                   ],
                   "type": "Point"
               },
               "speed": 20,
               "altitude": 129.18,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:31:29.963",
               "metadata": null,
               "distance": 695.94,
               "duration": 221,
               "elevation_gain": 28
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06322453,
                       25.60888629
                   ],
                   "type": "Point"
               },
               "speed": 23,
               "altitude": 130,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:31:33.856",
               "metadata": null,
               "distance": 716.22,
               "duration": 224,
               "elevation_gain": 29
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06302312,
                       25.60895644
                   ],
                   "type": "Point"
               },
               "speed": 19,
               "altitude": 129.83,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:31:38.029",
               "metadata": null,
               "distance": 737.89,
               "duration": 228,
               "elevation_gain": 29
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06280411,
                       25.60903273
                   ],
                   "type": "Point"
               },
               "speed": 22,
               "altitude": 128.76,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:31:41.848",
               "metadata": null,
               "distance": 761.45,
               "duration": 231,
               "elevation_gain": 29
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06256706,
                       25.60911529
                   ],
                   "type": "Point"
               },
               "speed": 22,
               "altitude": 128.39,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:31:45.793",
               "metadata": null,
               "distance": 786.95,
               "duration": 234,
               "elevation_gain": 29
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.0623316,
                       25.6091994
                   ],
                   "type": "Point"
               },
               "speed": 31,
               "altitude": 129.52,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:31:48.884",
               "metadata": null,
               "distance": 812.37,
               "duration": 237,
               "elevation_gain": 30
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06211789,
                       25.60929494
                   ],
                   "type": "Point"
               },
               "speed": 27,
               "altitude": 128.6,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:31:51.924",
               "metadata": null,
               "distance": 836.31,
               "duration": 240,
               "elevation_gain": 30
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06193204,
                       25.60937814
                   ],
                   "type": "Point"
               },
               "speed": 24,
               "altitude": 129.52,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:31:54.941",
               "metadata": null,
               "distance": 857.13,
               "duration": 243,
               "elevation_gain": 31
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06182,
                       25.60942829
                   ],
                   "type": "Point"
               },
               "speed": 0,
               "altitude": 129.91,
               "activity": "STOP",
               "recorded_at": "2022-03-04T07:31:57.273",
               "metadata": null,
               "distance": 869.68,
               "duration": 245,
               "elevation_gain": 31
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06280688,
                       25.61014692
                   ],
                   "type": "Point"
               },
               "speed": 0,
               "altitude": 127.47762887,
               "activity": "STOP",
               "recorded_at": "2022-03-04T07:33:51.349",
               "metadata": null,
               "distance": 869.68,
               "duration": 0,
               "elevation_gain": 31
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06297614,
                       25.61050536
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 129.96,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:33:53.057",
               "metadata": null,
               "distance": 913.04,
               "duration": 246,
               "elevation_gain": 34
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06306297,
                       25.61068923
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 130,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:33:55.087",
               "metadata": null,
               "distance": 935.28,
               "duration": 248,
               "elevation_gain": 34
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.0631498,
                       25.6108731
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 130,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:33:56.975",
               "metadata": null,
               "distance": 957.52,
               "duration": 249,
               "elevation_gain": 34
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06323663,
                       25.61105697
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 129.62,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:33:58.909",
               "metadata": null,
               "distance": 979.76,
               "duration": 250,
               "elevation_gain": 34
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06331741,
                       25.61122804
                   ],
                   "type": "Point"
               },
               "speed": 34,
               "altitude": 129.15,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:01.095",
               "metadata": null,
               "distance": 1000.45,
               "duration": 252,
               "elevation_gain": 34
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06339631,
                       25.61139512
                   ],
                   "type": "Point"
               },
               "speed": 38,
               "altitude": 127.42,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:02.978",
               "metadata": null,
               "distance": 1020.66,
               "duration": 253,
               "elevation_gain": 34
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06348155,
                       25.61157489
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 125.79,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:04.978",
               "metadata": null,
               "distance": 1042.42,
               "duration": 255,
               "elevation_gain": 34
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06356958,
                       25.6117583
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 126.78,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:07.109",
               "metadata": null,
               "distance": 1064.66,
               "duration": 257,
               "elevation_gain": 35
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06365239,
                       25.61194366
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 127.96,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:09.097",
               "metadata": null,
               "distance": 1086.9,
               "duration": 258,
               "elevation_gain": 36
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06372888,
                       25.61211659
                   ],
                   "type": "Point"
               },
               "speed": 34,
               "altitude": 128.9,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:11.004",
               "metadata": null,
               "distance": 1107.62,
               "duration": 259,
               "elevation_gain": 37
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06380536,
                       25.61228952
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 130,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:13.006",
               "metadata": null,
               "distance": 1128.34,
               "duration": 261,
               "elevation_gain": 38
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06390366,
                       25.61246859
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 130,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:14.985",
               "metadata": null,
               "distance": 1150.58,
               "duration": 262,
               "elevation_gain": 38
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06397223,
                       25.61264941
                   ],
                   "type": "Point"
               },
               "speed": 36,
               "altitude": 130,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:16.988",
               "metadata": null,
               "distance": 1171.85,
               "duration": 264,
               "elevation_gain": 38
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06403591,
                       25.61282275
                   ],
                   "type": "Point"
               },
               "speed": 36,
               "altitude": 128.43,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:18.946",
               "metadata": null,
               "distance": 1192.17,
               "duration": 265,
               "elevation_gain": 38
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.0641024,
                       25.6129951
                   ],
                   "type": "Point"
               },
               "speed": 36,
               "altitude": 127.34,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:21.022",
               "metadata": null,
               "distance": 1212.48,
               "duration": 267,
               "elevation_gain": 38
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06418866,
                       25.61316979
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 127.88,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:22.997",
               "metadata": null,
               "distance": 1233.76,
               "duration": 268,
               "elevation_gain": 39
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06430193,
                       25.61339917
                   ],
                   "type": "Point"
               },
               "speed": 30,
               "altitude": 128.38,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:26.011",
               "metadata": null,
               "distance": 1261.71,
               "duration": 271,
               "elevation_gain": 39
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06441341,
                       25.61362491
                   ],
                   "type": "Point"
               },
               "speed": 38,
               "altitude": 129.56,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:29.227",
               "metadata": null,
               "distance": 1289.21,
               "duration": 274,
               "elevation_gain": 40
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06452199,
                       25.6138474
                   ],
                   "type": "Point"
               },
               "speed": 29,
               "altitude": 130,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:32.071",
               "metadata": null,
               "distance": 1316.26,
               "duration": 276,
               "elevation_gain": 41
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06460088,
                       25.61401364
                   ],
                   "type": "Point"
               },
               "speed": 36,
               "altitude": 130,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:34.039",
               "metadata": null,
               "distance": 1336.38,
               "duration": 277,
               "elevation_gain": 41
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06468287,
                       25.6141864
                   ],
                   "type": "Point"
               },
               "speed": 37,
               "altitude": 129.06,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:35.987",
               "metadata": null,
               "distance": 1357.29,
               "duration": 278,
               "elevation_gain": 41
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06477006,
                       25.61437013
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 128.43,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:38.046",
               "metadata": null,
               "distance": 1379.53,
               "duration": 280,
               "elevation_gain": 41
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06485726,
                       25.61455386
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 128.77,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:40.104",
               "metadata": null,
               "distance": 1401.77,
               "duration": 282,
               "elevation_gain": 41
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06494445,
                       25.6147376
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 130,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:42.115",
               "metadata": null,
               "distance": 1424.01,
               "duration": 284,
               "elevation_gain": 42
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06503091,
                       25.61491977
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 128.43,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:44.000",
               "metadata": null,
               "distance": 1446.06,
               "duration": 285,
               "elevation_gain": 42
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06511283,
                       25.61510362
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 129.57,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:46.054",
               "metadata": null,
               "distance": 1468.11,
               "duration": 287,
               "elevation_gain": 43
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06519253,
                       25.61528579
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 128.22,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:48.054",
               "metadata": null,
               "distance": 1489.9,
               "duration": 289,
               "elevation_gain": 43
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06527387,
                       25.6154717
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 127.24,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:50.034",
               "metadata": null,
               "distance": 1512.14,
               "duration": 290,
               "elevation_gain": 43
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.0653552,
                       25.6156576
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 128.53,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:52.010",
               "metadata": null,
               "distance": 1534.38,
               "duration": 291,
               "elevation_gain": 45
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06546331,
                       25.6159047
                   ],
                   "type": "Point"
               },
               "speed": 35,
               "altitude": 127.5,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:55.108",
               "metadata": null,
               "distance": 1563.95,
               "duration": 294,
               "elevation_gain": 45
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06557565,
                       25.61615026
                   ],
                   "type": "Point"
               },
               "speed": 35,
               "altitude": 126.02,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:34:58.035",
               "metadata": null,
               "distance": 1593.51,
               "duration": 296,
               "elevation_gain": 45
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06566061,
                       25.61633543
                   ],
                   "type": "Point"
               },
               "speed": 29,
               "altitude": 126.06,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:35:01.010",
               "metadata": null,
               "distance": 1615.81,
               "duration": 298,
               "elevation_gain": 45
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06574934,
                       25.61652881
                   ],
                   "type": "Point"
               },
               "speed": 27,
               "altitude": 124.9,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:35:04.062",
               "metadata": null,
               "distance": 1639.1,
               "duration": 301,
               "elevation_gain": 45
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06583606,
                       25.61671781
                   ],
                   "type": "Point"
               },
               "speed": 27,
               "altitude": 125.89,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:35:07.030",
               "metadata": null,
               "distance": 1661.86,
               "duration": 303,
               "elevation_gain": 46
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06592368,
                       25.61690647
                   ],
                   "type": "Point"
               },
               "speed": 27,
               "altitude": 125.79,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:35:10.019",
               "metadata": null,
               "distance": 1684.62,
               "duration": 305,
               "elevation_gain": 46
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06601764,
                       25.61710781
                   ],
                   "type": "Point"
               },
               "speed": 32,
               "altitude": 127.84,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:35:13.039",
               "metadata": null,
               "distance": 1708.93,
               "duration": 308,
               "elevation_gain": 48
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06613094,
                       25.61735059
                   ],
                   "type": "Point"
               },
               "speed": 36,
               "altitude": 127.83,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:35:16.005",
               "metadata": null,
               "distance": 1738.25,
               "duration": 310,
               "elevation_gain": 48
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06624213,
                       25.61759282
                   ],
                   "type": "Point"
               },
               "speed": 36,
               "altitude": 125.88,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:35:19.022",
               "metadata": null,
               "distance": 1767.43,
               "duration": 313,
               "elevation_gain": 48
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06631701,
                       25.61776256
                   ],
                   "type": "Point"
               },
               "speed": 36,
               "altitude": 126.07,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:35:21.013",
               "metadata": null,
               "distance": 1787.76,
               "duration": 314,
               "elevation_gain": 48
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06639542,
                       25.61794028
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 127.75,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:35:23.027",
               "metadata": null,
               "distance": 1809.05,
               "duration": 316,
               "elevation_gain": 50
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06647734,
                       25.61812598
                   ],
                   "type": "Point"
               },
               "speed": 39,
               "altitude": 127.96,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:35:25.079",
               "metadata": null,
               "distance": 1831.29,
               "duration": 318,
               "elevation_gain": 50
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06655628,
                       25.61830491
                   ],
                   "type": "Point"
               },
               "speed": 37,
               "altitude": 128.07,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:35:27.089",
               "metadata": null,
               "distance": 1852.72,
               "duration": 320,
               "elevation_gain": 50
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06666323,
                       25.61854686
                   ],
                   "type": "Point"
               },
               "speed": 33,
               "altitude": 126.67,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:35:30.067",
               "metadata": null,
               "distance": 1881.71,
               "duration": 322,
               "elevation_gain": 50
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06677069,
                       25.61877522
                   ],
                   "type": "Point"
               },
               "speed": 33,
               "altitude": 124.07,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:35:33.186",
               "metadata": null,
               "distance": 1909.32,
               "duration": 325,
               "elevation_gain": 50
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06686524,
                       25.61897614
                   ],
                   "type": "Point"
               },
               "speed": 27,
               "altitude": 125.17,
               "activity": "MOVING",
               "recorded_at": "2022-03-04T07:35:36.054",
               "metadata": null,
               "distance": 1933.61,
               "duration": 327,
               "elevation_gain": 51
           },
           {
               "coordinates": {
                   "coordinates": [
                       85.06689824,
                       25.61904625
                   ],
                   "type": "Point"
               },
               "speed": 0,
               "altitude": 126.05,
               "activity": "STOP",
               "recorded_at": "2022-03-04T07:35:37.382",
               "metadata": null,
               "distance": 1942.08,
               "duration": 328,
               "elevation_gain": 52
           }
       ],
       "is_local": false
   }
}

{
  "code" : 404,
  "message" : "object_not_found",
  "description": "The requested object does not exist or already deleted.",
  "errors" : [ ]
}

Example

curl --location --request GET 'https://api.roam.ai/v2/trips/6221bf4393ade81ce90c8c5c/summary' \
--header 'Authorization: Bearer 07XXXX2fd55XXX0c6a58ab7101a9f5fa2'