Roam.ai Docs
HomeContactDashboard
  • Introduction
  • Getting Started
    • Key Concepts
  • Frameworks
  • Android
    • Quickstart (Android)
    • Pub/Sub Locations (Android)
    • SDK Methods (Android)
      • SDK Configuration (Android)
      • Get Current Location (Android)
      • Update Current Location (Android)
      • Update Location When Stationary (Android)
      • Trip v1 SDK Methods (Android)
      • Trip v2 SDK Methods (Android)
        • Create Trip (Android)
        • Update Trip (Android)
        • Start Quick Trip (Android)
        • Start Trip (Android)
        • End Trip (Android)
        • Pause Trip (Android)
        • Resume Trip (Android)
        • Sync Trip (Android)
        • Get Trip (Android)
        • Get Active Trips (Android)
        • Get Trip Summary (Android)
        • Subscribe to Trip (Android)
        • Delete Trip (Android)
    • Utility Methods (Android)
    • Troubleshooting (Android)
    • Changelog (Android)
  • iOS
    • Quickstart (iOS)
    • Pub/Sub Locations (iOS)
    • SDK Methods (iOS)
      • SDK Configuration (iOS)
      • Get Current Location (iOS)
      • Update Current Location (iOS)
      • Update Location When Stationary (iOS)
      • Trips v1 SDK Methods (iOS)
      • Trips v2 SDK Methods (iOS)
        • Create Trip (iOS)
        • Update Trip (iOS)
        • Start Quick Trip (iOS)
        • Start Trip (iOS)
        • End Trip (iOS)
        • Pause Trip (iOS)
        • Resume Trip (iOS)
        • Sync Trip (iOS)
        • Get Trip (iOS)
        • Get Active Trips (iOS)
        • Get Trip Summary (iOS)
        • Subscribe Trip (iOS)
        • Delete Trip (iOS)
    • Utility Methods (iOS)
    • Troubleshooting (iOS)
    • Changelog (iOS)
  • React Native
  • Flutter
  • PRODUCTS
  • Tracking (BETA)
  • Geofencing
  • Trips
  • APIs
    • Authorization
    • Users API
      • Create User API
      • Get User API
      • Update User API
    • Locations API
      • Get Locations API
      • Get Stop Locations API
    • Insights API
      • Get User POIs API
      • Get User Home Location API
      • Get User Work Location API
    • Trips v1 API
      • Create Trip API v1
      • Get Trip API
      • Update Trip API v1
      • Delete Trip API v1
      • Trip Summary API
      • Export Trip Summary as GPX
    • Trips v2 API
      • Create Trip API
      • Get Single Trip API
      • Get Multiple Trips API
      • Update Trip API
      • Control Trip API
        • Start Trip API
        • Pause Trip API
        • Resume Trip API
        • End Trip API
      • Get Trip Summary API
      • Export Trip API
      • Delete Trip API
    • Geofencing API
      • CREATE Geofence API
      • GET Geofence API
      • UPDATE Geofence API
      • DELETE Geofence API
    • Events API
      • Get Events
      • Trip Events
    • Nearby API
      • Get Nearby User API
      • Get Nearby Geofence API
    • Moving Geofence API
      • Create Moving-Geofence API
      • Update Moving-Geofence API
      • GET Moving-Geofence API
      • Delete Moving-Geofence API
    • User Groups API
      • Create Group API
      • Get User Group by ID
      • Get User Group List
      • Add Users to Group API
      • Update Group API
      • Find Nearby Users from Group
    • Query with Metadata
  • WEBHOOK
    • Webhook
    • Slack Integration
  • LIBRARIES
    • Javascript Library
    • Go Library
    • Python Library
Powered by GitBook
On this page
  • Quick Trips
  • Planned Trips
  • SDK Methods and APIs
  • Start Quick Trip
  • Update Trip
  • Create Trip
  • Control Trip
  • Get Trips
  • Get Trip Summary
  • Subscribe Trip
  • Export Trip
  • Delete Trip
  • Error Codes
  • Live Tracking Link

Was this helpful?

Export as PDF

Trips

Explore Roam's Trips documentation.

PreviousGeofencingNextAuthorization

Last updated 2 years ago

Was this helpful?

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

Roam.createTrip

Allows you to create a Planned trip with stop_locations

Roam.updateTrip

Allows you to update a trip with user_id, stop_locations and more.

Roam.startTrip

Allows you to start a "Quick Trip" or a "Planned Trip" with pre-defined stop_locations.

Roam.endTrip

Allows you to end a Trip.

Roam.pauseTrip

Allows you to pause a Trip.

Roam.ResumeTrip

Allows you to resume a Trip.

Roam.syncTrip

Allows you to sync an offline Trip.

Roam.getTrip

Allows you to get the trip details using the trip_id.

Roam.getActiveTrips

Allows you to get a list of active trips for a specific user_id.

Roam.getTripSummary

Allows you to get a trip summary which includes the trip route, time taken, distance covered, and more.

Roam.subscribeTripStatus

Allows you to subscribe to the real-time status of any ongoing trip.

Roam.deleteTrip

Allows you delete any trip.

Trip APIs

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

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

API Endpoint
Description

Create Trip

Allows you to create a Planned trip with or without origins and destinations.

Get Trip

Allows you to get the trip details using the trip_id.

Get Multiple Trips

Allows you to get multiple trips.

Update Trip

Allows you to update a trip with user_id, stop_locations and more.

Control Trips

Allows you to control a trip like start, end, pause and resume.

Trip Summary

Allows you to get a trip summary which includes the trip route, time taken, distance covered, and more.

Export Trip

Allows you to get a trip summary which includes the trip route, time taken, distance covered, and more.

Delete Trip

Allows you to delete any trip

API Objects

Trip Object

Attributes
Description

id

Unique identification of the trip object.

name

Name of the trip.

description

The trip's description.

metadata

A set of key-value pairs that you can attach to the trip object.

trip_state

The current state of the trip.

States: Created, Started, or Ended.

total_distance

Total distance covered by the user for this trip.

total_duration

Total duration taken by the user for this trip

toal_elevation_gain

Total positive elevation gain covered by the user for this trip.

started_at

Timestamp of when the trip started.

ended_at

Timestamp of when the trip ended.

created_at

Timestamp of when the trip was created.

updated_at

Timestamp of when the trip was last updated.

user

List of user objects.

events

List of event objects.

stops

List of stop objects.

User Object

Attributes
Description

id

Unique identification of the user object.

name

User name

description

User Description

metadata

A set of key-value pairs that you can attach to the user object.

Event Object

Attributes
Description

id

Unique identifier of the event Object

trip_id

ID associated with the trip.

user_id

User associated with the event.

event_type

Type of trip event: created, started, or ended.

created_at

Timestamp of when the event was created.

event_source

The source of this event, for example: "Trip"

event_version

Version of the event.

Stop Object

Attributes
Description

id

Unique identifier for the Stop Object

name

The name of the stop.

description

Stop description.

metadata

A Set of key-value pairs that you can attach to the user object.

geometry_radius

The geofence radius of the stop.

geometry

The coordinates of the stop geofence in geoJSON format.

arrived_at

Timestamp of when the user arrived/entered the stop.

departed_at

Timestamp of when the user departed/exited the stop.

created_at

Timestamp of when the stop was created.

updated_at

Timestamp of when the stop was updated.

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.

Subscribe Trip

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.

Subscribe to Webhook

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.

Subscribe to Backend Libraries

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

400

invalid_request_error

The request was unacceptable due to a missing parameter or an invalid parameter.

401

invalid_api_key

No valid API key provided or API key is missing.

402

account_error

The parameters were valid but the request failed due to either a payment error or the organization disabled it or you have exceeded your usage.

404

object_not_found

The requested object does not exist or has already been deleted.

429

rate_limit_exceeded

Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.

Live Tracking Link

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.

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.

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

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 .

REST
JSON-encoded
JSON-encoded
HTTPS
Start Quick Trip (iOS)
Start Quick Trip (Android)
Update Trip API
Update Trip (Android)
Update Trip (iOS)
Create Trip (Android)
Create Trip (iOS)
Create Trip API
Start Trip (Android)
Start Trip (iOS)
Start Trip API
End Trip (Android)
End Trip (iOS)
End Trip API
Pause Trip (Android)
Pause Trip (iOS)
Pause Trip API
Resume Trip (Android)
Resume Trip (iOS)
Resume Trip API
Sync Trip (Android)
Sync Trip (iOS)
Get Trip (Android)
Get Trip (iOS)
Get Single Trip API
Get Multiple Trips API
Get Active Trips (Android)
Get Active Trips (iOS)
Subscribe to Trip (Android)
Get Trip Summary (iOS)
Get Trip Summary API
Subscribe to Trip (Android)
Subscribe Trip (iOS)
Webhook
Javascript Library
Go Library
Python Library
Export Trip API
Delete Trip (Android)
Delete Trip (iOS)
Delete Trip API
Tracking Dashboard