Update Trip API

Explore how to update a trip with our Trip API

Update Trip

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

Updates the metadata, description and name of a trip. Details of existing stop locations like metadata, description, name and address can be updated except geometry_radius and geometry by passing stop location id. To add new stop location, add new stop location item to array without id. To remove the existing stop location, remove the entire item in the array which will remove the stop location only if it is not entered/existed by the assigned user.

You cannot update the user once the trip is started.

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.
description	String	Description of the trip. By default the id is shown if the description is not set.
name	String	Name of the trip. By default the id is shown if the name is not set.
metadata	Dictionary	Set of key-value pairs that you can attach to the trip. This can be useful for storing additional information about the trip in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.
stops	Array	For the trips with stop locations, add an array of stop locations.
stops.metadata	Dictionary	Set of key-value pairs that you can attach to the stop location. This can be useful for storing additional information about the stop location in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.
stops.name	String	Name of the stop location. By default the id is shown if the name is not set.
stops.description	String	Description of the stop location. By default the id is shown if the description is not set.
stops.address	String	Address of the stop location.
stops.geometry_radius	Number	The radius in meters.
stops.geometry	Point	Location coordinates in GeoJSON format.

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