Start Trip API

Explore how to start a trip with our Trip API

Start Trip

POST https://api.roam.ai/v2/trips/:id/controls

Starts the trip for the given id.

Path Parameters

Name	Type	Description
id*	String	Controls the trip with the given ID.

Headers

Name	Type	Description
Authorization*	String	Bearer <API-KEY>

Request Body

Name	Type	Description
user_id*	String	The user for which the trip is being tracked.
started_at*	String	Timestamp is UTC for action:start eg: 2022-01-14T09:10:59.125
action*	String	To control the trip. eg. start, pause, resume, end

201: Created Trip started

{
   "code": 201,
   "message": "trip_started",
   "description": "The trip is started successfully.",
   "trip": {
       "id": "62132b22f13667633fbad210",
       "name": "Test Delivery",
       "description": "item pickup for test users",
       "trip_state": "started",
       "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-21T06:03:14.650",
       "updated_at": "2022-02-21T06:03:14.650",
       "events": [
           {
               "id": "62132b28c78454e82f29a5f1",
               "trip_id": "62132b22f13667633fbad210",
               "location_id": "",
               "user_id": "61ffb486d2c69840ee518073",
               "event_type": "roam:trip:created",
               "created_at": "2022-02-21T06:03:20.603",
               "event_source": "roam:trip",
               "event_version": "2.0"
           }
       ],
       "stops": [
           {
               "id": "62132b22f13667633fbad20e",
               "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-21T06:03:14.607",
               "updated_at": "2022-02-21T06:03:14.607",
               "arrived_at": null,
               "departed_at": null
           },
           {
               "id": "62132b22f13667633fbad20f",
               "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-21T06:03:14.649",
               "updated_at": "2022-02-21T06:03:14.649",
               "arrived_at": null,
               "departed_at": null
           }
       ]
   }
}

400: Bad Request Invalid request

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

Example

cURL

curl --location --request POST 'https://api.roam.ai/v2/trips/62132b22f13667633fbad210/controls' \
--header 'Authorization: Bearer dfbbf5d5ff6b41ecb1166147b87c0544' \
--header 'Content-Type: application/json' \
--data-raw '{
    "user_id":"61ffb486d2c69840ee518073",
    "started_at":"2022-02-21T06:03:15.649",
    "action": "start"
}'