Create Trip API

Explore how to create a trip with our Trip API

Create Trip

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

Trips creation is also accessible via the API if you need to create trips on the fly.

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.

201: Created Trip created

{
   "code": 201,
   "message": "trip_created",
   "description": "The trip is created successfully.",
   "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.geometry",
       "message" : "This field should be valid GeoJSON"
    },
    {
       "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
                ]
            }
        }
    ]
}'