📊 Scoring & Statistics

The Statistics module provides a comprehensive suite of functionalities to gather various statistics data, ranging from daily user scores to unique tags. Below is a breakdown of its methods and their usage:

1. Get started

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

pip install damoov-admin

Begin by importing the Statistics module and finalizing the authentication process.

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

stats = statistics.DamoovAuth(email=email, password=password)

2. Methods

Syntaxes:

user_id: ID of the user, also known as a DeviceToken
start_date: Start date in format YYYY-MM-DDTHH:MM:SS
end_date: End date in format YYYY-MM-DDTHH:MM:SS
tag : ['Tag1', '...', 'TagX']

`user_daily_statistics`

Obtain daily statistics of a user.

Parameters:

user_id: ID of the user
start_date: Start date in format YYYY-MM-DDTHH:MM:SS
end_date: End date in format YYYY-MM-DDTHH:MM:SS
tag (optional): Tag to filter

Example:

Request:

user_statistics=stats.user_daily_statistics(
        user_id='2948a036-36f8-4f76-babd-0635874aa3er',
        start_date='2023-09-01T00:00:00',
        end_date='2023-10-02T00:00:00',
  			tag=['Business', 'Personal']
        )

Response:

"Result": [
{
            "UserId": "2948a036-36f8-4f76-babd-0635874aa3er",
            "InstanceId": "",
            "AppId": "",
            "CompanyId": "",
            "ReportDate": "2023-09-02T00:00:00",
            "MileageKm": 200.7945138572461,
            "MileageMile": 124.77371091089272,
            "TripsCount": 8,
            "DriverTripsCount": 8,
            "OtherTripsCount": 0,
            "MaxSpeedKmh": 122.29244232177734,
            "MaxSpeedMileh": 75.99252365875243,
            "AverageSpeedKmh": 54.68438828527036,
            "AverageSpeedMileh": 33.980878880466996,
            "TotalSpeedingKm": 12.483415754279346,
            "TotalSpeedingMile": 7.757194549709185,
            "AccelerationsCount": 4,
            "BrakingsCount": 5,
            "CorneringsCount": 4,
            "PhoneUsageDurationMin": 3.5368999999999997,
            "PhoneUsageMileageKm": 2.2573077536862733,
            "PhoneUsageMileageMile": 1.40269103814065,
            "PhoneUsageSpeedingDurationMin": 0.0,
            "PhoneUsageSpeedingMileageKm": 0.0,
            "PhoneUsageSpeedingMileageMile": 0.0,
            "DrivingTime": 186.96666666666667,
            "NightDrivingTime": 0.0,
            "DayDrivingTime": 45.993165254592896,
            "RushHoursDrivingTime": 140.0721311569214,
            "PermissionsLevel": 92,
            "TrustLevel": 92.0
        },
  ],
    "Status": 200,
    "Title": "",
    "Errors": []
}

`user_daily_ecoscore`

Retrieve a user's daily ecoscore.

Parameters:

user_id: ID of the user
start_date: Start date
end_date: End date

Example:

Request:

user_statistics=stats.user_daily_ecoscore(
        user_id='2948a036-36f8-4f76-babd-0635874aa3er',
        start_date='2023-09-01T00:00:00',
        end_date='2023-10-02T00:00:00',
        )

Response:

"Result": [
         {
            "UserId": "2948a036-36f8-4f76-babd-0635874aa3er",
            "InstanceId": "",
            "AppId": "",
            "CompanyId": "",
            "CalcDate": "2023-10-02T00:00:00",
            "EcoScoreFuel": 97.80603418529739,
            "EcoScoreTyres": 100.0,
            "EcoScoreBrakes": 71.24604879817583,
            "EcoScoreDepreciation": 30.066967347066047,
            "EcoScore": 75.74524464826901,
            "PermissionsLevel": 100,
            "TrustLevel": 100.0
        }
    ],
    "Status": 200,
    "Title": "",
    "Errors": []
}

`user_daily_safetyscore`

Get a user's daily safety score.

Parameters:

user_id: ID of the user
start_date: Start date
end_date: End date
tag (optional): Tag to filter

Example:

Request:

    user_statistics=stats.user_daily_safetyscore(
        user_id='2948a036-36f8-4f76-babd-0635874aa3er',
        start_date='2023-09-01T00:00:00',
        end_date='2023-10-02T00:00:00',
        )

Response:

"Result": [     
  {
            "UserId": "2948a036-36f8-4f76-babd-0635874aa3er",
            "InstanceId": "",
            "AppId": "",
            "CompanyId": "",
            "AccelerationScore": 78.0,
            "BrakingScore": 80.0,
            "SpeedingScore": 72.0,
            "PhoneUsageScore": 86.0,
            "CorneringScore": 79.0,
            "SafetyScore": 90.0,
            "CalcDate": "2023-10-02T00:00:00",
            "PermissionsLevel": 100,
            "TrustLevel": 100.0
        }
    ],
    "Status": 200,
    "Title": "",
    "Errors": []
}

`user_accumulated_statistics`

Fetch accumulated statistics for a user.

Parameters:

user_id: ID of the user
start_date: Start date
end_date: End date
tag (optional): Tag to filter

Example:

Request:

    user_statistics=stats.user_accumulated_statistics(
        user_id='2948a036-36f8-4f76-babd-0635874aa3er',
        start_date='2023-09-01T00:00:00',
        end_date='2023-10-02T00:00:00',
        )

Response:

    "Result": [
        {
            "UserId": "2948a036-36f8-4f76-babd-0635874aa3er",
            "InstanceId": "",
            "AppId": "",
            "CompanyId": "",
            "MileageKm": 2111.0221881212033,
            "MileageMile": 1311.789187698516,
            "TripsCount": 153,
            "DriverTripsCount": 153,
            "OtherTripsCount": 0,
            "MaxSpeedKmh": 122.29244232177734,
            "MaxSpeedMileh": 75.99252365875243,
            "AverageSpeedKmh": 43.86747108399977,
            "AverageSpeedMileh": 27.25924653159745,
            "TotalSpeedingKm": 144.23474761841058,
            "TotalSpeedingMile": 89.6274721700803,
            "AccelerationsCount": 94,
            "BrakingsCount": 78,
            "CorneringsCount": 45,
            "PhoneUsageDurationMin": 20.447583333333334,
            "PhoneUsageMileageKm": 17.025709577441788,
            "PhoneUsageMileageMile": 10.579775931422326,
            "PhoneUsageSpeedingDurationMin": 0.2427833333333333,
            "PhoneUsageSpeedingMileageKm": 0.32201192397028167,
            "PhoneUsageSpeedingMileageMile": 0.20009820955513297,
            "DrivingTime": 3301.6166666666663,
            "NightDrivingTime": 0.0,
            "DayDrivingTime": 1807.0491929650307,
            "RushHoursDrivingTime": 1490.29370367527,
            "PermissionsLevel": 93,
            "TrustLevel": 93.0
        }
    ],
    "Status": 200,
    "Title": "",
    "Errors": []
}

`user_accumulated_ecoscore`

Acquire a user's accumulated ecoscore over a range.

Parameters:

user_id: ID of the user
start_date: Start date
end_date: End date

Example:

Request:

    user_statistics.user_accumulated_ecoscore(
        user_id='2948a036-36f8-4f46-babd-0635870aa7ed',
        start_date='2023-09-01T00:00:00',
        end_date='2023-10-02T00:00:00'
        )

Response:

"Result": [
        {
            "UserId": "2948a036-36f8-4f76-babd-0635874aa3er",
            "InstanceId": "",
            "AppId": "",
            "CompanyId": "",
            "EcoScoreFuel": 97.21532847773788,
            "EcoScoreTyres": 100.0,
            "EcoScoreBrakes": 83.25091485161596,
            "EcoScoreDepreciation": 26.5303907938692,
            "EcoScore": 75.00759345586548,
            "PermissionsLevel": 93,
            "TrustLevel": 93.0
        }
      ],
    "Status": 200,
    "Title": "",
    "Errors": []
}

`user_accumulated_safetyscore`

Obtain a user's accumulated safety score.

Parameters:

user_id: ID of the user
start_date: Start date
end_date: End date
tag (optional): Tag to filter

Example:

Request:

    user_statistics=stats.user_accumulated_safetyscore(
        user_id='2948a036-36f8-4f76-babd-0635874aa3er',
        start_date='2023-09-01T00:00:00',
        end_date='2023-10-02T00:00:00',
        tag='')

Response:

"Result": [
        {
            "UserId": "2948a036-36f8-4f76-babd-0635874aa3er",
            "InstanceId": "",
            "AppId": "",
            "CompanyId": "",
            "AccelerationScore": 77.625,
            "BrakingScore": 81.96875,
            "SpeedingScore": 70.125,
            "PhoneUsageScore": 86.46875,
            "CorneringScore": 85.71875,
            "SafetyScore": 89.53125,
            "PermissionsLevel": 93,
            "TrustLevel": 93.0
        }
    ],
    "Status": 200,
    "Title": "",
    "Errors": []

`entity_accumulated_ecoscore`

Retrieve the accumulated ecoscore for an entity.

Parameters:

start_date: Start date
end_date: End date
tag (optional): Tag to filter
One of the following must be provided:
- instance_id: Instance ID
- app_id: Application ID
- company_id: Company ID

Example:

Request:

    instance_statistics=stats.entity_accumulated_ecoscore(
        start_date='2023-09-01T00:00:00',
        end_date='2023-10-02T00:00:00',
        instance_id="your_instance_id",

    )

Response:

    "Result": {
        "UserId": null,
        "InstanceId": "your_instance_id",
        "AppId": null,
        "CompanyId": null,
        "EcoScoreFuel": 97.52329737487166,
        "EcoScoreTyres": 100.0,
        "EcoScoreBrakes": 75.59935000534821,
        "EcoScoreDepreciation": 44.719564784133794,
        "EcoScore": 80.30344045080935,
        "PermissionsLevel": 94,
        "TrustLevel": 94.0
    },
    "Status": 200,
    "Title": "",
    "Errors": []

`entity_daily_statistics`

Fetch daily statistics for an entity.

Parameters:

start_date: Start date
end_date: End date
tag (optional): Tag to filter
One of the following must be provided:
- instance_id: Instance ID
- app_id: Application ID
- company_id: Company ID

Example:

Request:

company_d_statistics=stats.entity_daily_statistics(
        start_date='2023-09-01T00:00:00',
        end_date='2023-10-02T00:00:00',
        company_id='your_company_id'
    )

Response:

"Result": [
        {
            "InstanceId": null,
            "AppId": null,
            "CompanyId": "your_company_id",
            "ReportDate": "2023-09-18T00:00:00",
            "RegisteredUsers": 12,
            "ActiveUsers": 282,
            "MileageKm": 25382.13108184097,
            "MileageMile": 15772.456254255985,
            "TripsCount": 1789,
            "DriverTripsCount": 1786,
            "OtherTripsCount": 3,
            "MaxSpeedKmh": 146.1915283203125,
            "MaxSpeedMileh": 90.84341569824218,
            "AverageSpeedKmh": 36.002057830035696,
            "AverageSpeedMileh": 22.371678735584183,
            "TotalSpeedingKm": 560.9847620514762,
            "TotalSpeedingMile": 348.595931138787,
            "AccelerationsCount": 1139,
            "BrakingsCount": 1326,
            "CorneringsCount": 1474,
            "PhoneUsageDurationMin": 3800.4465833333334,
            "PhoneUsageMileageKm": 2284.020002380001,
            "PhoneUsageMileageMile": 1419.290029478932,
            "PhoneUsageSpeedingDurationMin": 12.098366666666667,
            "PhoneUsageSpeedingMileageKm": 10.980101468687467,
            "PhoneUsageSpeedingMileageMile": 6.823035052642389,
            "DrivingTime": 35077.866666666676,
            "NightDrivingTime": 1351.4007195532322,
            "DayDrivingTime": 21381.867682458833,
            "RushHoursDrivingTime": 12418.06661722064,
            "PermissionsLevel": 95,
            "TrustLevel": 95.0
        },
  ],
    "Status": 200,
    "Title": "",
    "Errors": []
}

`entity_accumulated_safetyscore`

Obtain safety score for an entity.

Parameters:

start_date: Start date
end_date: End date
tag (optional): Tag to filter
One of the following must be provided:
- instance_id: Instance ID
- app_id: Application ID
- company_id: Company ID

Example:

Request:

instance_statistics=stats.entity_accumulated_safetyscore(
        start_date='2023-09-20T00:00:00',
        end_date='2023-10-02T00:00:00',
        app_id="your_app_id",
    )

Response:

"Result": [
			{
            "InstanceId": null,
            "AppId": "your_app_id",
            "CompanyId": null,
            "ReportDate": "2023-10-02T00:00:00",
            "AccelerationScore": 76.99007444168734,
            "BrakingScore": 76.41935483870968,
            "SpeedingScore": 90.21339950372209,
            "PhoneUsageScore": 74.04466501240695,
            "CorneringScore": 74.01488833746899,
            "SafetyScore": 83.22332506203475,
            "PermissionsLevel": 95,
            "TrustLevel": 95.0
        }
    ],
    "Status": 200,
    "Title": "",
    "Errors": []
}

`entity_accumulated_statistics`

Get accumulated statistics for an entity.

Parameters:

start_date: Start date
end_date: End date
tag (optional): Tag to filter
One of the following must be provided:
- instance_id: Instance ID
- app_id: Application ID
- company_id: Company ID

Example:

Request:

    company_statistics=stats.entity_accumulated_statistics(
        start_date='2023-09-01T00:00:00',
        end_date='2023-10-02T00:00:00',
        company_id='your_company_id'
    )

Response

{
    "Result": {
        "InstanceId": null,
        "AppId": null,
        "CompanyId": "your_company_id",
        "TotalRegisteredUsers": 299,
        "ActiveUsers": 491,
        "MileageKm": 765112.3461886081,
        "MileageMile": 475440.8119216011,
        "TripsCount": 47429,
        "DriverTripsCount": 47200,
        "OtherTripsCount": 229,
        "MaxSpeedKmh": 235.80712890625,
        "MaxSpeedMileh": 146.53054990234375,
        "AverageSpeedKmh": 37.49730203560512,
        "AverageSpeedMileh": 23.300823484925015,
        "TotalSpeedingKm": 18645.076059143215,
        "TotalSpeedingMile": 11586.050263151588,
        "AccelerationsCount": 31278,
        "BrakingsCount": 39863,
        "CorneringsCount": 40161,
        "PhoneUsageDurationMin": 117555.1976166667,
        "PhoneUsageMileageKm": 67128.67055363058,
        "PhoneUsageMileageMile": 41713.75588202606,
        "PhoneUsageSpeedingDurationMin": 347.51840000000016,
        "PhoneUsageSpeedingMileageKm": 357.2293322990894,
        "PhoneUsageSpeedingMileageMile": 221.98230709065405,
        "DrivingTime": 1014552.5333333339,
        "NightDrivingTime": 43901.92194293812,
        "DayDrivingTime": 636574.804801112,
        "RushHoursDrivingTime": 341089.71085665515,
        "PermissionsLevel": 95,
        "TrustLevel": 95.0
    },
    "Status": 200,
    "Title": "",
    "Errors": []
}

`entity_daily_safetyscore`

Fetch daily safety score for an entity.

Parameters:

start_date: Start date
end_date: End date
tag (optional): Tag to filter
One of the following must be provided:
- instance_id: Instance ID
- app_id: Application ID
- company_id: Company ID

Example:

Request:

    app_statistics=stats.entity_daily_safetyscore(
        start_date='2023-09-01T00:00:00',
        end_date='2023-10-02T00:00:00',
        app_id="your_app_id", 
    )

Response:

"Result": [
{
            "InstanceId": null,
            "AppId": "your_app_id",
            "CompanyId": null,
            "ReportDate": "2023-10-02T00:00:00",
            "AccelerationScore": 76.99007444168734,
            "BrakingScore": 76.41935483870968,
            "SpeedingScore": 90.21339950372209,
            "PhoneUsageScore": 74.04466501240695,
            "CorneringScore": 74.01488833746899,
            "SafetyScore": 83.22332506203475,
            "PermissionsLevel": 95,
            "TrustLevel": 95.0
        },
    ],
    "Status": 200,
    "Title": "",
    "Errors": []
}

`lastupdates`

Get the last updates for a user.

Parameters:

user_id: ID of the user

Example:

Request:

    metadata=stats.lastupdates(
        user_id='2948a036-36f8-4f46-babd-0635870aa7ed'
        )

Response:

{
    "Result": [
        {
            "UserId": "your_user_id",
            "InstanceId": "your_instance_id",
            "AppId": "your_app_id",
            "CompanyId": "your_company_id",
            "LatestTripDate": "2023-10-11T14:33:40+01:00",
            "LatestScoringDate": "2023-10-11T00:00:00"
        }
    ],
    "Status": 200,
    "Title": "",
    "Errors": []
}

`uniquetags`

Obtain unique tags for a user within a specific range.

Parameters:

user_id: ID of the user
start_date: Start date
end_date: End date

Example:

Request:

   metadata=stats.uniquetags(
        user_id='2948a036-36f8-4f46-babd-0635870aa7ed',
        start_date='2023-09-01T00:00:00',
        end_date='2023-10-02T00:00:00',                                 
    )

Response:

{
    "Result": {
        "UniqueTagsCount": 2,
        "UniqueTagsList": [
            "your_tag_1",
            "your_tag_x"
        ]
    },
    "Status": 200,
    "Title": "",
    "Errors": []
}

4. 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.

5. Response

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

`result`

Provides the 'Result' from the response. If the result is a list with a single item, it returns that item. Otherwise, it returns the full list or results.

Return Type: dict or list

`status`

Returns the 'Status' from the response.

Return Type: dict

`title`

Returns the 'Title' of the response.

Return Type: str

`errors`

Fetches any 'Errors' from the response.

Return Type: list

`latest_trip_date`

Provides the 'LatestTripDate' from the result.

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

`latest_scoring_date`

Retrieves the 'LatestScoringDate' from the result.

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

`tags_count`

Gives the 'UniqueTagsCount' from the result.

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

`tags_list`

Fetches the 'UniqueTagsList' from the result.

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

5. Usage

After you fetch data using methods from the Statistics module, you can pass the returned data to StatisticsResponse to further process and easily access specific parts of the response.

# Import and initial initialization

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

stats = statistics.DamoovAuth(email=email, password=password)

# Methods to fetch user statistics and scores
app_statistics=stats.entity_daily_safetyscore(
        start_date='2023-09-01T00:00:00',
        end_date='2023-10-02T00:00:00',
        app_id="your_app_id", 
    )
  print(app_statistics)
  print(app_statistics.status)
  print(app_statistics.result)
  
  
  metadata=stats.uniquetags(
        user_id='2948a036-36f8-4f46-babd-0635870aa7ed',
        start_date='2023-09-01T00:00:00',
        end_date='2023-10-02T00:00:00',                                 
    )
  print(metadata.tags_list)
  print(metadata.tags_count)
  
  
  metadata=stats.lastupdates(
        user_id='2948a036-36f8-4f46-babd-0635870aa7ed'
        )
  print(metadata.latest_trip_date)
  print(metadata.latest_scoring_date)