SIGN INSIGN UP

📊 Scoring & Statistics

Suggest Edits

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)

Updated 5 months ago