Control Trip API

Explore how to control a trip with our Trip API

Control Trip

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

Starts/Pauses/Resumes/Stops the trip for the given id.

Path Parameters

Name	Type	Description
id*	String	Updates 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
paused_at*	String	Timestamp is UTC for action:pause eg: 2022-01-14T09:10:59.125
resumed_at*	String	Timestamp is UTC for action:resume eg: 2022-01-14T09:10:59.125
ended_at*	String	Timestamp is UTC for action:end eg: 2022-01-14T09:10:59.125

200: OK Trip updated

{
   "code": 201,
   "message": "trip_updated",
   "description": "The trip data is updated successfully for given id.",
   "trip": {
       "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
           }
       ]
   }
}

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"
    },
    {
       "field" : "stops.id",
       "message" : "This field should be a valid stop id"
    },
    {
       "field" : "stops.geometry_radius",
       "message" : "This field should be valid number between 10 and 10000"
    }
  ]
}

Example

cURL

curl --location --request POST 'https://api.roam.ai/v2/trips' \
--header 'Authorization: Bearer dfbbf5d5ff6b41ecb1166147b87c0544' \
--header 'Content-Type: application/json' \
--data-raw '{
    "user_id": "61ffb486d2c69840ee518073",
    "description": "item pickup for test users",
    "name": "Test Delivery",
    "metadata": {
        "order_id": "1123",
        "_id": 21
    },
    "stops": [
        {
            "metadata": {"order_id": "1120"},
            "description": "test Pickup for Johan",
            "name": "Delivery",
            "address": "Flat NO 121 MG road ",
            "geometry_radius": 20,
            "geometry": {
                "type": "Point",
                "coordinates": [
                    77.6879689,
                    27.4072289
                ]
            }
        },
        {
            "metadata": {"order_id": "1129"},
            "description": "another tester Pickup for Johan",
            "name": "Delivery",
            "address": "teacher colony ",
            "geometry_radius": 200,
            "geometry": {
                "type": "Point",
                "coordinates": [
                    77.6925657818137,
                    27.422398561298454
                ]
            }
        }
    ]
}'