Query with Metadata

The metadata parameter can be used in the Get users/geofence/trips API to query on top of the metadata field.

Example :

curl --location --request GET 'https://api.roam.ai/v1/api/user/?start_date=2021-12-15&end_date=2021-12-20&metadata=name:nokia,external_id:bcy573b892' \
--header 'Api-key: xxxxxxxxxxx' \
--data-raw ''

You can query the trips and users via the API and use metadata values as filters to get the respective results.

You need to make sure the external_id or metadata values are not duplicated since this might end up in multiple results. So that's something that needs to be handled from your side.

Get user list

GET /v1/api/user

Query Parameters

Name	Type	Description
start_date	String	Date from when the data is to be returned. E.g.:- 2021-12-27
end_date	String	Date till when the data is to be returned. E.g:- 2021-12-29
metadata	JSON	The metadata will be in a format key1:value1,key2:value2,.. to support query on multiple keys (key1 and key2 in this case). E.g.:- key1:value1,key2:value2,..
page_number	Integer	This field is used for getting 10 entries at a time. If the response returns an empty list in the data field, it is safe to assume the pages are exhausted. E.g.:- 1

Headers

Name	Type	Description
Api-key*	String	Auth-key E.g.:- 099923kjhdcscijhb5sdbsdmjsdc77

200: OK

{
    "status": true,
    "msg": "Success.",
    "code": 200,
    "data": {
        "next_page": null,
        "pages": 1,
        "prev_page": null,
        "account_id": "xxxxxxxxxxxx",
        "users": [
            {
                "id": "61cae045bd3ea85964b3d166",
                "app_id": "61caa3ae51efb028427512da_1",
                "device_token": "xxxxxxxx-z6mIKnf3-xxxxxxx",
                "device_uuid": "xxxxxx-bf1d-41f1-a199-xxxxxxxxx",
                "description": "api testing",
                "brand": "samsung",
                "model": "SM-G930F",
                "os_version": "26",
                "sdk_version": "r_0.0.9",
                "geofence_events": true,
                "motion_events": false,
                "location_events": true,
                "trips_events": true,
                "nearby_events": true,
                "location_listener": true,
                "event_listener": true,
                "metadata": {
                    "name": "new_test",
                    "external_id": "02"
                },
                "is_deleted": false,
                "created_at": "2021-12-28T10:00:37.423",
                "last_location_update": {}
            }
        ]
    }
}

Sample Request

curl --location --request GET 'https://api.roam.ai/v1/api/user/?start_date=2021-12-27&end_date=2021-12-29&metadata=name:new_test,external_id:02' \
--header 'Api-key: xxxxxxxxx'

Get Trip list

GET /v1/api/trips

Query Parameters

Name	Type	Description
start_date	String	Date from when the data is to be returned. E.g.:- 2021-12-27
end_date	String	Date till when the data is to be returned. E.g.:- 2021-12-29
metadata	JSON	The metadata will be in a format key1:value1,key2:value2,.. to support query on multiple keys (key1 and key2 in this case). E.g.:- key1:value1,key2:value2,..
page_number	Integer	This field is used for getting 10 entries at a time. If the response returns an empty list in the data field, it is safe to assume the pages are exhausted. E.g:- 1

Headers

Name	Type	Description
Api-key*	String	Auth-key E.g.:- 099923kjhdcscijhb5sdbsdmjsdc77

200: OK

{
    "status": true,
    "msg": "Success.",
    "code": 200,
    "data": {
        "next_page": null,
        "pages": 1,
        "prev_page": null,
        "trips": [
            {
                "id": "61c170986f9faa09f84164bd",
                "project_id": "619490d9ffb3fb7bdbaa4081",
                "origins": [
                    {
                        "id": "61c170996f9faa09f84164be",
                        "trip_id": "61c170986f9faa09f84164bd",
                        "created_at": "2021-12-21T06:13:44.377",
                        "updated_at": "2021-12-21T06:13:45.671",
                        "coordinates": {
                            "type": "Point",
                            "coordinates": [
                                77.622977,
                                12.917042
                            ]
                        },
                        "loc_type": "origin"
                    }
                ],
                "destinations": [
                    {
                        "id": "61c1709a6f9faa09f84164bf",
                        "trip_id": "61c170986f9faa09f84164bd",
                        "created_at": "2021-12-21T06:13:46.463",
                        "updated_at": "2021-12-21T06:13:47.173",
                        "coordinates": {
                            "type": "Point",
                            "coordinates": [
                                77.650239,
                                12.924304
                            ]
                        },
                        "loc_type": "destination"
                    },
                    {
                        "id": "61c1709c6f9faa09f84164c0",
                        "trip_id": "61c170986f9faa09f84164bd",
                        "created_at": "2021-12-21T06:13:47.957",
                        "updated_at": "2021-12-21T06:13:48.706",
                        "coordinates": {
                            "type": "Point",
                            "coordinates": [
                                77.697418,
                                12.959172
                            ]
                        },
                        "loc_type": "destination"
                    }
                ],
                "events": [
                    {
                        "id": "61c1709f1c87eaa57bc27535",
                        "trip_id": "61c170986f9faa09f84164bd",
                        "user_id": "61c02a328ccb5f0b34a21482",
                        "event_type": "geospark:trip:created",
                        "created_at": "2021-12-21T06:13:51.181",
                        "is_deleted": false,
                        "event_source": "geospark:trip",
                        "event_version": "1.0"
                    }
                ],
                "user_id": "61c02a328ccb5f0b34a21482",
                "is_started": false,
                "is_ended": false,
                "is_deleted": false,
                "metadata": {
                    "order_id": "63g773832",
                    "delivery": "fast_delivery"
                },
                "created_at": "2021-12-21T06:13:43.641",
                "updated_at": "2021-12-21T06:13:50.686"
            }
        ]
    }
}

Sample Request

curl --location --request GET 'https://api.roam.ai/v1/api/trips/?metadata=delivery:fast_delivery,order_id:63g773832&start_date=2021-12-20&end_date=2021-12-21' \
--header 'Api-Key: xxxxxxxxxxxxxx'

Get Geofence list

GET /v1/api/geofence

Query Parameters

Name	Type	Description
start_date	String	Date from when the data is to be returned. E.g.:- 2021-12-27
end_date	String	Date till when the data is to be returned. E.g.:- 2021-12-29
metadata	JSON	The metadata will be in a format key1:value1,key2:value2,.. to support query on multiple keys (key1 and key2 in this case). E.g.:- key1:value1,key2:value2,..
page_number	Integer	This field is used for getting 10 entries at a time. If the response returns an empty list in the data field, it is safe to assume the pages are exhausted. E.g.:- 1

Headers

Name	Type	Description
Api-key*	String	Auth-key E.g.:- 099923kjhdcscijhb5sdbsdmjsdc77

200: OK

  {
    "status": true,
    "msg": "Success.",
    "code": 200,
    "data": {
        "next_page": null,
        "pages": 1,
        "prev_page": null,
        "geofences": [
            {
                "geofence_id": "61cae13bbc69252a31c8cc24",
                "geometry_type": "circle",
                "geometry_radius": 200,
                "geometry_center": {
                    "type": "Point",
                    "coordinates": [
                        77.659094,
                        27.497836
                    ]
                },
                "is_enabled": true,
                "description": "demo desc",
                "metadata": {
                    "name": "type_1",
                    "id": "01"
                },
                "is_deleted": false,
                "created_at": "2021-12-28T10:04:43.572",
                "updated_at": "2021-12-28T10:04:43.572"
            },
            {
                "geofence_id": "61cae13a51efb0501804855b",
                "geometry_type": "circle",
                "geometry_radius": 200,
                "geometry_center": {
                    "type": "Point",
                    "coordinates": [
                        77.659094,
                        27.497836
                    ]
                },
                "is_enabled": true,
                "description": "demo desc",
                "metadata": {
                    "name": "type_1",
                    "id": "01"
                },
                "is_deleted": false,
                "created_at": "2021-12-28T10:04:42.141",
                "updated_at": "2021-12-28T10:04:42.141"
            }
        ]
    }
}

Sample Request

curl --location --request GET 'https://api.roam.ai/v1/api/geofence/?start_date=2021-12-27&end_date=2021-12-29&metadata=name:type_1,id:01' \
--header 'Api-Key: xxxxxxxxxxxxxx'