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.

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.

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:

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 .

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

// Enter update interval in seconds
Roam.updateLocationWhenStationary(int i);

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

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 more.

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.

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).

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

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

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

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.

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.

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

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

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

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..

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.

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  
            }
        });

  Roam.syncTrip("tripId", object : RoamSyncTripCallback {
            override fun onSuccess(response: RoamSyncTripResponse) {
                //get sync trip details
            }

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

You can access the sync trip response parameters below:

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

Set Tracking in AppState

[Roam setTrackingInAppState:STATE];

Offline Location Tracking

[Roam offlineLocationTracking];

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()

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.

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.

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

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

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

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.

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.

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.

1. Callback Method which returns the current location with a faster response time. However, the accuracy depends on the current GPS connectivity.

2. 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.

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.

Add the code to the receiver.

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

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).

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

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).

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

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

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

Base URL

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

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:

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

SDKs

Roam SDK is a convenient Software Development Kit that helps you easily add 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:

• - static and moving geofences with events.

• - detailed location information about your users' patterns.

• - full trip management for mobility and on-demand services.

• - find nearby users and geofences.

Set Tracking in AppState

Roam.setTrackingInAppState(STATE)

Roam.setTrackingInAppState(STATE);

Offline Location Tracking

Roam.offlineLocationTracking(Boolean)

Roam.offlineLocationTracking(Boolean);

Allow Mock Location

Roam SDKs reject Mock Locations on the device by default.

Roam.allowMockLocation(Boolean)

Roam.allowMockLocation(Boolean);

Accuracy Engine

To enable accuracy engine for Passive, Active, and Balanced tracking

Roam.enableAccuracyEngine()

Roam.enableAccuracyEngine();

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

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

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

For disabling accuracy engine

 Roam.disableAccuracyEngine()

 Roam.disableAccuracyEngine();

Set Foreground Service Notification

Use setForegroundNotification method to notify the user about location tracking in the notification bar. Set ENABLE as true to enable notification and false to disable the notification.

// ENABLE as Boolean (mandatory)
// TITLE as String (mandatory)
// DESCRIPTION as String (mandatory)
// ICON as String (mandatory)
// ACTIVITY_PATH as String (mandatory)
// FOREGROUND_SERVICE_PATH as String (mandatory)

Roam.setForegroundNotification(ENABLE,"TITLE","DESCRIPTION","ICON",
"ACTIVITY_PATH","FOREGROUND_SERVICE_PATH")

// ENABLE as Boolean (mandatory)
// TITLE as String (mandatory)
// DESCRIPTION as String (mandatory)
// ICON as String (mandatory)
// ACTIVITY_PATH as String (mandatory)
// FOREGROUND_SERVICE_PATH as String (mandatory)

Roam.setForegroundNotification(ENABLE,"TITLE","DESCRIPTION","ICON",
"ACTIVITY_PATH","FOREGROUND_SERVICE_PATH");

You can subscribe to a trip using the tripID to get real-time trip data.

Roam.subscribeTrip("tripId");

Roam.subscribeTrip("tripId")

Once you subscribe to the trip, you will receive real time trip data in the listener method of RoamReceiver sub-class.

Listeners are needed to consume the location data from the SDK itself. In order to enable listeners, ensure the following.

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>

Then add the code to the receiver.

public class LocationReceiver extends RoamReceiver {

    @Override
    public void onLocationUpdated(Context context, RoamLocation roamLocation) {
        super.onLocationUpdated(context, roamLocation);
	// receive own location updates here
	// do something with location data using location
	// 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 onReceiveTrip(Context context, RoamTripStatus roamTripStatus) {
       //get realtime trip data
    }
    
    @Override
    public void onError(Context context, RoamError roamError) {
    	// receive error message here
        // roamError.getCode());	
        // roamError.getMessage());
    }

}

class LocationReceiver : RoamReceiver() {
            override fun onLocationUpdated(context: Context?, roamLocation: RoamLocation?) {
                super.onLocationUpdated(context, roamLocation)
                // receive own location updates here
                // do something with location data using location
                // 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 fun onReceiveTrip(context: Context?, roamTripStatus: RoamTripStatus?) {
                //get realtime trip data
            }

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

You can access the subscribed trip response parameters below:

You can also unsubscribe from the trip using its tripID.

Roam.unsubscribeTrip("tripId")

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.

Roam.deleteTrip("tripId") { response, error in
    // Access delete trip response
}

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

You can access the delete trip response parameters below:

Set DeviceToken

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

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
     Roam.setDeviceToken(deviceToken)
 }

- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken{
    [Roam setDeviceToken:deviceToken];
}

Check Location Permission

Check if the location permissions for the app are enabled.

Roam.isLocationEnabled()

[Roam isLocationEnabled];

Location Permission Status

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

Roam.locationPermissionStatus()

 [Roam locationPermissionStatus];

Request Location Permission

Application request for the user location.

Roam.requestLocation()

 [Roam requestLocation];

Check Location Tracking

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

Roam.isLocationTracking()

[Roam isLocationTracking];

Notification Opened Handler

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

func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void)
        {
                Roam.notificationOpenedHandler(response)
                completionHandler()
        }

- (void)userNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void (^)(void))completionHandler{
    [Roam notificationOpenedHandler:response];
}

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.

Export Trip Summary as GPX

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

Query Parameters

Headers

Sample Request

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

Delete Trip API

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

Query Parameters

Headers

Sample Request

curl --location --request DELETE 'https://api.roam.ai/v1/api/trips/?trip_id=<TRIP-ID>' \
--header 'Content-Type: application/json' \
--header 'Api-key: <API-KEY>'

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

Request Body

Sample Request

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

Headers

Example

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

Headers

Request Body

Sample Request

Single Delete

Bulk Delete

Update User API

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

Headers

Request Body

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
}'

Get Home Insight API

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

Query Parameters

Headers

Sample Request

curl --location --request GET 'https://api.roam.ai/v1/api/insights/home/?user_id=5f30d339b36114713d8b610e' \
--header 'Api-key: ee5b950fdf284474a8727409cd12bb3b'

Get Work Insight API

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

Query Parameters

Headers

Sample Request

curl --location --request GET 'https://api.roam.ai/v1/api/insights/work/?user_id=5f30d339b36114713d8b610e' \
--header 'Api-key: ee5b950fdf284474a8727409cd12bb3b'

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

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

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.

You can access the subscribed trip response parameters below:

You can unsubscribe from trips using the tripID.

Update Trip API

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

Headers

Request Body

Sample Request

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

You can access the sync trip response parameters below:

GET Geofence API

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

Query Parameters

Headers

{
  "status": true,
  "msg": "Success.",
  "code": 200,
  "data": {
    "next_page": null,
    "pages": 1,
    "prev_page": null,
    "geofences": [
      
      {
        "geofence_id": "60ee8ea4ffb3fb728c120d8b",
        "geometry_type": "circle",
        "geometry_radius": 177,
        "geometry_center": {
          "type": "Point",
          "coordinates": [
            -72.28122,
            42.926042
          ]
        },
        "is_enabled": [
          true,
          "2021-06-10T18:45:00.000",
          "2021-06-10T19:29:00.000"
        ],
        "user_ids": [
          "6bda16edea01848b3b419163"
        ],
        "is_deleted": false,
        "created_at": "2021-07-14T07:13:40.765",
        "updated_at": "2021-07-14T07:13:40.765"
      },
      {
        "geofence_id": "60ee8e6effb3fb728c120d8a",
        "geometry": {
          "type": "Polygon",
          "coordinates": [
            [
              [
                -0.08789347686767579,
                51.50619618452938
              ],
              [
                -0.0905934768676758,
                51.50619618452938
              ],
              [
                -0.0905934768676758,
                51.503796184529385
              ],
              [
                -0.08789347686767579,
                51.50619618452938
              ]
            ]
          ]
        },
        "geometry_type": "polygon",
        "geometry_center": {
          "type": "Point",
          "coordinates": [
            -0.08969347686882724,
            51.505396185373506
          ]
        },
        "is_enabled": [
          true,
          "2021-06-10T18:45:00.000",
          "2021-06-10T19:29:00.000"
        ],
        "is_deleted": false,
        "created_at": "2021-07-14T07:12:46.811",
        "updated_at": "2021-07-14T07:12:46.811"
      }
    ]
  }
}

Sample Request

curl --location --request GET 'https://api.roam.ai/v1/api/geofence/?start_date=2020-09-28&end_date=2020-09-29' \
--header 'Api-Key: e566c098cc6b441a9c3453b6fcf76e88'

Create Geofence API

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

Headers

Request Body

{
    "status": true,
    "msg": "Geofence created successfully.",
    "code": 201,
    "data": {
        "geofence_id": "5f73326ce5fc231ba4b253eb",
        "geometry_radius": 177,
        "geometry_center": {
            "type": "Point",
            "coordinates": [
                -72.28122,
                42.926042
            ]
        },
    "is_enabled": [true, "2021-06-10T18:45:00", "2021-06-10T19:29:00"],
    "user_ids": ["6bda16edea01848b3b419163"],
    "group_ids": ["5cda16edea00845b3b419173"],
    "created_at": "2020-09-29T13:11:08.702",
    "updated_at": "2020-09-29T13:11:08.702"
    }
}

Sample Request

curl --location --request POST 'https://api.roam.ai/v1/api/geofence/' \
--header 'Api-Key: e566c098cc6b441a9c3453b6fcf76e88' \
--header 'Content-Type: application/json' \
--data-raw '{
	"coordinates": [ -72.28122, 42.926042 ] ,
	"geometry_radius": 177,
	"description": "Roam Amsterdam HQ",
	"tag": "Office",
	"metadata": {},
  "user_ids": ["6bda16edea01848b3b419163"],
  "group_ids": ["5cda16edea00845b3b419173"],
	"is_enabled": [true, "2021-06-10T18:45:00", "2021-06-10T19:29:00"]
}'