🚗 Trips

The Trips module offers a robust set of functionalities designed for efficient trip data management. This encompasses a range of operations from fetching trip details, updating trip

1. Get started

If you haven't already, install the Damoov-Admin SDK for Python.

pip install damoov-admin

Begin by importing the User management module and finalizing the authentication process.

from damoov_admin import trips
email="[email protected]"
password="YOUR PASSWORD"

trips_mngt = trips.DamoovAuth(email=email, password=password)

2. Methods

The Trips module offers a robust set of functionalities tailored for managing and fetching trip-related data. Here's a comprehensive breakdown of its methods and their usage:

Syntaxes:

sort_by: Sort parameter (e.g., "StartDateUtc, StartDateUtc_Desc").
unit_system: Measurement unit system (e.g., "Si" or "Imperial")
user_id: ID of the user/ DeviceToken whose trips are to be fetched.
start_date, end_date: Date range for the trip in format YYYY-MM-DDTHH:MM:SS
start_date_timestamp_sec, end_date_timestamp_sec: Alternative date range using timestamps.
include_details: Include detailed trip data, like start, end address, transportation type, and tags
include_statistics: Include statistics related to the trip.
include_scores: Include scores associated with the trip.
include_waypoints: Include per-second GPS waypoints of the trip.
include_events: Include events or incidents associated with the trip.
include_related: Include related trip data, including URI for future get requests.
tags_included: Tags to be included in the filtering.
tags_excluded: Tags to be excluded in the filtering.
limit: Limit the number of trips returned.

`get_list_trips`

Fetches the list of trips for a specific user, with various optional filters to refine the result set.

Parameters:
- user_id: Required
- start_date, end_date: Required.
- start_date_timestamp_sec, end_date_timestamp_sec
- include_details
- include_statistics
- include_scores
- include_related
- tags_included
- tags_excluded:
- unit_system
- sort_by
- limit

Example:

Request

    user_trip_details=trip.get_list_trips(
    user_id='user_id',
    # start_date='2023-09-09', 
    # end_date='2023-10-10', 
    start_date_timestamp_sec=1696704060, 
    end_date_timestamp_sec=1696713840,
    sort_by='StartDateUtc',
    include_details=False, 
    include_statistics=False, 
    include_scores=False, 
    include_related=True, 
    tags_included=None, 
    tags_excluded=None,  
    locale="EN", 
    unit_system="Imperial",
    # limit=3
    )

Response

{
    "Result": {
        "Trips": [
            {
                "Id": "trip_id",
                "DateUpdated": "2022-09-10T12:29:25+00:00",
                "Identifiers": {
                    "CompanyId": "company_id",
                    "ApplicationId": "application_id",
                    "InstanceId": "instance_id",
                    "UserId": "user_id"
                },
                "Data": {
                    "StartDate": "2022-09-10T12:20:25+00:00",
                    "EndDate": "2022-09-10T12:29:25+00:00",
                    "UnitSystem": "Imperial",
                    "Addresses": {
                        "Start": {
                            "Full": "102 Beach St, San Francisco, CA 94133-1101, United States",
                            "Parts": {
                                "CountryCode": "USA",
                                "Country": "United States",
                                "County": "San Francisco",
                                "State": "California",
                                "City": "San Francisco",
                                "District": "Fisherman's Wharf",
                                "Street": "Beach St",
                                "House": "102"
                            }
                        },
                        "End": {
                            "Full": "E Beach, San Francisco, CA 94129, United States",
                            "Parts": {
                                "CountryCode": "USA",
                                "Country": "United States",
                                "County": "San Francisco",
                                "State": "California",
                                "City": "San Francisco",
                                "District": "Presidio",
                                "Street": "E Beach"
                            }
                        }
                    },
                    "TransportType": {
                        "Current": "OriginalDriver",
                        "ConfirmNeeded": false
                    },
                    "Tags": []
                },
                "Statistics": {
                    "Mileage": 4.143953744168464,
                    "DurationMinutes": 17.183333333333334,
                    "AccelerationsCount": 0.0,
                    "BrakingsCount": 0.0,
                    "CorneringsCount": 1.0,
                    "TotalSpeedingMileage": 0.0,
                    "MidSpeedingMileage": 0.0,
                    "HighSpeedingMileage": 0.0,
                    "PhoneUsageDurationMinutes": 11.989366666666665,
                    "PhoneUsageMileage": 3.5955679069262994,
                    "PhoneUsageWithSpeedingDurationMinutes": 0.0,
                    "PhoneUsageWithSpeedingMileage": 0.0,
                    "DayHours": 17.233333587646484,
                    "RushHours": 0.0,
                    "NightHours": 0.0,
                    "AverageSpeed": 11.416121791501084,
                    "MaxSpeed": 19.790273235742262
                },
                "Scores": {
                    "Safety": 97.0,
                    "Acceleration": 100.0,
                    "Braking": 100.0,
                    "Cornering": 56.0,
                    "Speeding": 100.0,
                    "PhoneUsage": 40.0,
                    "Eco": 77.0,
                    "EcoBrakes": 100.0,
                    "EcoDepreciation": 25.0,
                    "EcoFuel": 100.0,
                    "EcoTyres": 100.0
                },
                "Related": [
                    {
                        "Type": "Waypoints",
                        "Uri": "https://api.telematicssdk.com/trips/get/admin/v1/trip_id/waypoints"
                    },
                    {
                        "Type": "Trip",
                        "Uri": "https://api.telematicssdk.com/trips/get/v1/trip_id"
                    }
                ]
            }
        ]
    },
    "Status": 200,
    "Title": "",
    "Errors": []
}

`get_trip_details`

Retrieves waypoint details of a specific trip by its unique ID.

Parameters:
- trip_id: (Required)
- user_id: (Required)
- include_details: Include detailed trip data.
- include_statistics: Include statistics related to the trip.
- include_scores: Include scores associated with the trip.
- include_waypoints: Include waypoints of the trip.
- include_events: Include events associated with the trip.
- include_related: Include related trip data.
- locale: Locale settings (e.g., "EN").
- unit_system: Measurement unit system (e.g., "Si" or "Imperial").

Example:

Request

    trip_details = trip.get_trip_details(
    trip_id="trip_id",
    user_id="user_id",
    include_details=True, 
    include_statistics=True, 
    include_scores=True, 
    include_waypoints=True,
    include_events=True, 
    include_related=True, 
    locale="EN", 
    unit_system="Imperial"
    )

Response

{
    "Result": {
        "Trip": {
            "Id": "trip_id",
            "DateUpdated": "2023-10-11T07:34:31+00:00",
            "Identifiers": {
                "CompanyId": "company_id",
                "ApplicationId": "application_id",
                "InstanceId": "instance_id",
                "UserId": "user_id"
            },
            "Data": {
                "StartDate": "2023-10-09T08:19:23+01:00",
                "StartDateUnixMilliseconds": 1696835963000,
                "EndDate": "2023-10-09T08:36:44+01:00",
                "EndDateUnixMilliseconds": 1696837004000,
                "UnitSystem": "Imperial",
                "Addresses": {
                    "Start": {
                        "Full": "Avenida Marechal Gomes da Costa 17, 1800-253 Lisbon, Portugal",
                        "Parts": {
                            "CountryCode": "PRT",
                            "Country": "Portugal",
                            "County": "Lisbon",
                            "City": "Lisbon",
                            "District": "Lisbon",
                            "Street": "Avenida Marechal Gomes da Costa",
                            "House": "17"
                        }
                    },
                    "End": {
                        "Full": "Rua do Arco do Cego 177, 1000-020 Lisbon, Portugal",
                        "Parts": {
                            "CountryCode": "PRT",
                            "Country": "Portugal",
                            "County": "Lisbon",
                            "City": "Lisbon",
                            "District": "Lisbon",
                            "Street": "Rua do Arco do Cego",
                            "House": "177"
                        }
                    }
                },
                "TransportType": {
                    "Current": "OriginalDriver",
                    "ConfirmNeeded": true
                },
                "Tags": []
            },
            "Statistics": {
                "Mileage": 3.111590678261461,
                "DurationMinutes": 17.35,
                "AccelerationsCount": 1.0,
                "BrakingsCount": 0.0,
                "CorneringsCount": 0.0,
                "TotalSpeedingMileage": 0.021650736620396006,
                "MidSpeedingMileage": 0.06389130188092126,
                "HighSpeedingMileage": 0.0,
                "PhoneUsageDurationMinutes": 0.0,
                "PhoneUsageMileage": 0.0,
                "PhoneUsageWithSpeedingDurationMinutes": 0.0,
                "PhoneUsageWithSpeedingMileage": 0.0,
                "DayHours": 0.0,
                "RushHours": 17.270366668701172,
                "NightHours": 0.0,
                "AverageSpeed": 20.500146429454027,
                "MaxSpeed": 47.186389247420195
            },
            "Scores": {
                "Safety": 79.0,
                "Acceleration": 53.0,
                "Braking": 100.0,
                "Cornering": 100.0,
                "Speeding": 48.0,
                "PhoneUsage": 100.0,
                "Eco": 91.0,
                "EcoBrakes": 100.0,
                "EcoDepreciation": 75.0,
                "EcoFuel": 98.94907,
                "EcoTyres": 100.0
            },
              "Waypoints": [
                {
                    "Index": 0,
                    "SecSinceStart": 0,
                    "PointDateUnixMilliseconds": 0,
                    "Lat": 0,
                    "Long": 0,
                    "Speed": 0,
                    "SpeedLimit": 0,
                    "Speeding":status ,
                    "PhoneUsage": true
                }
              ],
            "Events": [
                {
                    "Id": "",
                    "Type": "Acceleration",
                    "Date": "2023-10-09T08:22:10+01:00",
                    "Lat": 38.74998,
                    "Long": -9.10616,
                    "Value": 3.353325366973877
                }
            ],
            "Related": [
                {
                    "Type": "Waypoints",
                    "Uri": "https://api.telematicssdk.com/trips/get/admin/v1/300665e1-e415-46ab-892f-1cd25afd650d/waypoints"
                }
            ]
        }
    },
    "Status": 200,
    "Title": "",
    "Errors": []
}

3. Note

In all methods, if there's a HTTPError, the error will be printed, and the response will be handled accordingly.
For daily statistics, scores, and list of trips, the methods automatically modify the requested period to 14 days if the original request spans a period longer than that.

4. Response

The TripsResponse processes and provides easy access to specific parts of the data returned by the Trips module. Here's a detailed breakdown of its properties:

`result`

Returns the 'Result' part from the response.

Return Type: dict

`trips`

Provides the list of 'Trip' items from the response. If the result is not a list, an empty list is returned.

Return Type: list

`statistics`

Provides the 'Statistics' information for a trip.

Return Type: dict

`details`

Returns the detailed data for the 'Trip'.

Return Type: dict

`transporttype`

Provides the 'TransportType' information for a trip.

Return Type: dict

`scores`

Returns the 'Scores' for the trip.

Return Type: dict

`events`

Provides the 'Events' for the trip.

Return Type: dict

`waypoints`

Returns the 'Waypoints' for the trip.

Return Type: dict

`paging_info`

Provides the paging information if available.

Return Type: dict

`status`

Returns the 'Status' from the response.

Return Type: dict

`datetime`

Provides the 'Data' (usually representing datetime) from the response.

Return Type: dict

`trip_id`

Returns the unique ID for the trip.

Return Type: Depends on data (e.g., str, None)

5. Usage

After making calls to the Trips module to retrieve trip-related data, you can pass the returned data to TripsResponse to further process and easily access specific parts of the response.

# Import and initial initialization

from damoov_admin import trips
email="[email protected]"
password="YOUR PASSWORD"

trips_mngt = trips.DamoovAuth(email=email, password=password)

# Method to get a list of trips for selected period of time
user_trip_details=trip.get_list_trips(
    user_id='7623f515-b867-4325-bc63-3a0248d4f774',
    # start_date='2023-09-09', 
    # end_date='2023-10-10', 
    start_date_timestamp_sec=1696704060, 
    end_date_timestamp_sec=1696713840,
    sort_by='StartDateUtc',
    tags_included=['Business'],
    include_details=True, 
    include_statistics=True, 
    include_scores=True, 
    include_related=True, 
    locale="EN", 
    unit_system="Imperial", 
    limit=1
    )

print('status: ', user_trip_details.status)
print('details: ', user_trip_details.details)
print('trips: ',user_trip_details.trips)
print('trip id: ',user_trip_details.trip_id)
print('date and time: ', user_trip_details.datetime)
print(user_trip_details.paging_info)
print(user_trip_details) # prints full response in JSON format
    

# Methods to fetch trip details, including waypoints, for a specific trip ID.
trip_details = trip_mngt.get_trip_details(
      trip_id="trip_id",
      user_id="user_id",
      include_details=True, 
      include_statistics=True, 
      include_scores=True, 
      include_waypoints=True,
      include_events=True, 
      include_related=True, 
      locale="EN", 
      unit_system="Imperial"
    )

print(trip_details) # prints full response in JSON format
print('Status: ', trip_details.status)
print('Result: ',trip_details.result)
print('Statistics: ',trip_details.statistics)
print('Scores: ',trip_details.scores)
print('Events: ',trip_details.events)
print('Waypoints: ',trip_details.waypoints)
print('Details: ',trip_details.details)
print('Transportation mode: ',trip_details.transporttype)