Report

Overview

The Reports API provides powerful analytics and insights derived from your fleet's telematics data. These endpoints enable you to access various metrics, statistics, and trends to inform decision-making, measure performance, and identify opportunities for improvement across your entire fleet or specific vehicles.

Available Report Types

The Reports API includes several specialized endpoints:

Event Accuracy Report - Analyze detection accuracy of safety events
Incident Report - Review normalized incident counts per distance driven
Global Report - Access anonymized industry benchmarks across all clients
Usage Report - Examine daily distance metrics and hourly driving patterns
Behavioral Report - Evaluate detailed driver behavior metrics and trends
Environmental Report - Understand road usage, weather impact, and intersection analytics

Common Parameters

Many report endpoints support these common parameters:

Parameter	Type	Description
`connectionId`	UUID	(Optional) Filter report by specific connection
`vehicleId`	UUID	(Optional) Filter report by specific vehicle
`from`	date-time	Start date for the report period (ISO 8601 format)
`to`	date-time	End date for the report period (ISO 8601 format)

Event Accuracy Report

GET /reports/event-accuracy

Retrieve comprehensive statistics on the accuracy of detected events within your fleet. This report provides insights into event detection reliability, categorized by incident type and evaluated across different intensity levels. The data includes comparative metrics from both the telematics service provider (TSP) and Manifold's AI validation system.

Request Parameters

Parameter	Type	Location	Required	Description
`x-api-key`	String	Header	Yes	API authentication key
`Connection-Id`	UUID	Header	No	Connection identifier (if filtering by connection)
`connectionId`	UUID	Query	No	Filter results by specific connection ID
`providerId`	UUID	Query	No	Filter results by specific telematics provider ID
`from`	date-time	Query	No	Start date for report data (ISO 8601 format)
`to`	date-time	Query	No	End date for report data (ISO 8601 format)

Example Request

curl --request GET \
  --url "https://api.analytics.autos/reports/event-accuracy?from=2024-10-01T00:00:00Z&to=2024-10-12T23:59:59Z&eventTypes=Crash" \
  --header "x-api-key: YOUR-API-KEY" \
  --header "Connection-Id: YOUR-CONNECTION-ID"

Response Structure

{
  "status": 200,
  "message": null,
  "data": [
    {
      "incidentType": "Tailgating",
      "accuracy": {
        "tsp": {
          "accurateCount": 3,
          "inaccurateCount": 0
        },
        "manifold": 2
      },
      "intensity": {
        "veryLow": 0,
        "low": 0,
        "medium": 3,
        "high": 2,
        "critical": 0
      }
    },
    {
      "incidentType": "Hard Braking",
      "accuracy": {
        "tsp": {
          "accurateCount": 48,
          "inaccurateCount": 3
        },
        "manifold": 2
      },
      "intensity": {
        "veryLow": 7,
        "low": 24,
        "medium": 18,
        "high": 4,
        "critical": 0
      }
    }
  ],
  "next": null
}

Response Fields

Field	Type	Description
`status`	Integer	HTTP status code (200 for success)
`message`	String	Response message (null if successful)
`data`	Array	Array of event accuracy objects
`data[].incidentType`	String	Type of incident being analyzed (e.g., "Tailgating", "Hard Braking")
`data[].accuracy.tsp.accurateCount`	Integer	Number of events correctly detected by the telematics service provider
`data[].accuracy.tsp.inaccurateCount`	Integer	Number of events incorrectly detected by the telematics service provider
`data[].accuracy.manifold`	Integer	Number of additional events validated or identified by Manifold's AI system
`data[].intensity.veryLow`	Integer	Count of events with very low intensity classification
`data[].intensity.low`	Integer	Count of events with low intensity classification
`data[].intensity.medium`	Integer	Count of events with medium intensity classification
`data[].intensity.high`	Integer	Count of events with high intensity classification
`data[].intensity.critical`	Integer	Count of events with critical intensity classification
`next`	String	Pagination cursor (null if no additional pages)

Usage Notes

Use this endpoint to evaluate the reliability of your fleet's event detection system
Compare TSP detection accuracy with Manifold's enhanced detection capabilities
Analyze intensity distributions to understand the severity patterns of incidents
Monitor accuracy trends over time to measure improvements in detection systems
Filter by specific date ranges to correlate accuracy with other operational variables

Incident Report

GET /reports/incident

Retrieve a normalized report of incident counts per type, calculated per 1000 kilometers of driving distance. This standardized metric allows for fair comparison across different vehicles, time periods, or fleets with varying mileage, making it ideal for benchmarking and trend analysis.

Request Parameters

Parameter	Type	Location	Required	Description
`x-api-key`	String	Header	Yes	API authentication key
`connectionId`	UUID	Query	Yes	Connection ID for which to generate the report
`from`	date-time	Query	No	Start date for data collection (ISO 8601 format)
`to`	date-time	Query	No	End date for data collection (ISO 8601 format)

Example Request

curl --request GET \
  --url "https://api.analytics.autos/reports/incident?connectionId=123e4567-e89b-12d3-a456-426614174000&from=2024-01-01T00:00:00Z&to=2024-01-31T23:59:59Z" \
  --header "x-api-key: YOUR-API-KEY"

Response Structure

[
  {
    "type": "Harsh Braking",
    "count": 12.5
  },
  {
    "type": "Speeding",
    "count": 8.3
  },
  {
    "type": "Tailgating",
    "count": 3.7
  },
  {
    "type": "Hard Cornering",
    "count": 5.9
  },
  {
    "type": "Rapid Acceleration",
    "count": 6.2
  }
]

Response Fields

Field	Type	Description
`type`	String	Human-readable name of the incident type
`count`	Number	Normalized count of incidents per 1000 kilometers driven

Usage Notes

This normalized metric enables equitable comparison across fleets of different sizes
Use this data to establish internal safety benchmarks and set improvement targets
Track metrics over time to assess the effectiveness of safety initiatives and driver training
Compare incident types to identify priority areas for safety improvements
Correlate with behavioral and environmental reports for root cause analysis

Global Report

GET /reports/global

Retrieve a global report containing industry benchmarks and aggregated metrics across all clients in the Manifold system. This data provides valuable context for comparing your fleet's performance against industry standards.

Request Parameters

Parameter	Type	Location	Required	Description
`x-api-key`	String	Header	Yes	API authentication key

Example Request

curl --request GET \
  --url "https://api.analytics.autos/reports/global" \
  --header "x-api-key: YOUR-API-KEY"

Response Structure

{
  "normalizedAccurateIncidentAveragePerType": [
    {
      "type": "Harsh Braking",
      "count": 10.2
    },
    {
      "type": "Speeding",
      "count": 5.8
    },
    {
      "type": "Hard Cornering",
      "count": 4.3
    },
    {
      "type": "Rapid Acceleration",
      "count": 3.9
    },
    {
      "type": "Tailgating",
      "count": 2.4
    },
    {
      "type": "Phone Distraction",
      "count": 3.6
     }
  ]
}

Response Fields

Field	Type	Description
`normalizedAccurateIncidentAveragePerType`	Array	Array of incident types with industry averages
`normalizedAccurateIncidentAveragePerType[].type`	String	Human-readable name of the incident type
`normalizedAccurateIncidentAveragePerType[].count`	Number	Average normalized count of incidents per 1000 kilometers across all clients

Usage Notes

Use global averages as performance benchmarks for your fleet
Identify areas where your fleet exceeds or falls below industry standards
Set realistic safety and performance targets based on industry metrics
Understand your relative position within the broader fleet management landscape
Factor industry benchmarks into your safety and operational improvement strategies

Usage Report

GET /reports/overview/usage

Retrieve comprehensive daily distance-driven statistics and hourly driving patterns for the specified time period. This detailed report helps fleet managers understand vehicle utilization patterns and driving habits, enabling optimized scheduling and resource allocation.

Request Parameters

Parameter	Type	Location	Required	Description
`x-api-key`	String	Header	Yes	API authentication key
`from`	date-time	Query	No	Start date-time for the report in UTC (ISO 8601 format). Limited to a 90 day window with respect to `from` and `to`.
`to`	date-time	Query	No	End date-time for the report in UTC (ISO 8601 format)
`connectionId`	UUID	Query	No	Filter by specific connection
`vehicleId`	UUID	Query	No	Filter by specific vehicle

Example Request

curl --request GET \
  --url "https://api.analytics.autos/reports/overview/usage?from=2024-01-01T00:00:00Z&to=2024-01-31T23:59:59Z&vehicleId=123e4567-e89b-12d3-a456-426614174000" \
  --header "x-api-key: YOUR-API-KEY"

Response Structure

{
  "dailyDistanceDriven": [
    {
      "dateTime": "2024-01-01T00:00:00Z",
      "distanceInMeter": 125000
    },
    {
      "dateTime": "2024-01-02T00:00:00Z",
      "distanceInMeter": 85000
    },
    {
      "dateTime": "2024-01-03T00:00:00Z",
      "distanceInMeter": 142000
    },
    {
      "dateTime": "2024-01-04T00:00:00Z",
      "distanceInMeter": 97500
    }
  ],
  "hourlyKilometerPercentage": [
    {
      "time": "08:00:00",
      "percent": 12.5,
      "rushHourTrafficType": 1
    },
    {
      "time": "09:00:00",
      "percent": 9.2,
      "rushHourTrafficType": 1
    },
    {
      "time": "17:00:00",
      "percent": 15.3,
      "rushHourTrafficType": 2
    },
    {
      "time": "18:00:00",
      "percent": 14.1,
      "rushHourTrafficType": 2
    }
  ]
}

Response Fields

Field	Type	Description
`dailyDistanceDriven`	Array	Array of daily distance measurements
`dailyDistanceDriven[].dateTime`	String	ISO 8601 date for the distance measurement
`dailyDistanceDriven[].distanceInMeter`	Number	Distance driven in meters for that day
`hourlyKilometerPercentage`	Array	Array of hourly driving distribution data
`hourlyKilometerPercentage[].time`	String	Time in format "HH:MM:SS" indicating the hour
`hourlyKilometerPercentage[].percent`	Number	Percentage of total kilometers driven during this hour
`hourlyKilometerPercentage[].rushHourTrafficType`	Integer	Traffic condition indicator: 0 (Normal), 1 (High Traffic), 2 (Very High Traffic)

Usage Notes

Analyze daily distance patterns to identify usage anomalies and optimization opportunities
Examine hourly distribution to understand rush hour exposure for more efficient scheduling
Compare multiple vehicles to identify utilization disparities within your fleet
Track changes over time to assess the impact of policy or route changes
Use rush hour traffic indicators to optimize scheduling for fuel efficiency and reduced idle time
Monitor days without activity to improve asset utilization
Correlate peak usage days with business operations for better resource planning

Behavioral Report

GET /reports/overview/behavioral

Retrieve comprehensive behavioral analytics data, including incident risk metrics, speeding patterns, and detailed analytics comparing fleet-specific data against client-wide benchmarks. This in-depth report provides valuable insights into driver behavior trends, risk factors, and safety performance over time.

Request Parameters

Parameter	Type	Location	Required	Description
`x-api-key`	String	Header	Yes	API authentication key
`from`	date-time	Query	Yes	Start date for the behavioral analysis (ISO 8601 format). Limited to a 90 day window with respect to `from` and `to`.
`to`	date-time	Query	Yes	End date for the behavioral analysis (ISO 8601 format)
`vehicleId`	UUID	Query	No	Filter by specific vehicle
`connectionId`	UUID	Query	No	Filter by specific connection
`incidentType`	String	Query	No	Filter by specific incident type

Example Request

curl --request GET \
  --url "https://api.analytics.autos/reports/overview/behavioral?from=2024-01-01T00:00:00Z&to=2024-01-31T23:59:59Z" \
  --header "x-api-key: YOUR-API-KEY"

Response Structure

{
  "incidentRiskAndRates": [
    {
      "type": "Late Braking",
      "risk": 0,
      "rate": 0.113515
    },
    {
      "type": "Lane Departure",
      "risk": 2.98287,
      "rate": 0.158921
    },
    {
      "type": "Hard Brake",
      "risk": 3156.18142,
      "rate": 6.311428
    },
    {
      "type": "Harsh Motion",
      "risk": 62.43325,
      "rate": 0.249733
    },
    {
      "type": "Stop Sign Pass",
      "risk": 728.883344,
      "rate": 6.833597
    },
    {
      "type": "Distracted Driving",
      "risk": 11081.3238,
      "rate": 221.626476
    },
    {
      "type": "Accident",
      "risk": 2224.894,
      "rate": 0.317842
    },
    {
      "type": "Malfunction",
      "risk": 0,
      "rate": 154.19863
    }
  ],
  "speedingAnalytics": {
    "totalSpeedingDistanceDriven": 10976045.894263,
    "totalDistanceDriven": 4404708396.175931,
    "dayTimeSpeedingDistance": 2712773988.974922,
    "clientAveragePercent": 0.249189,
    "filteredSpeedingDistanceTrendOverTime": {
      "2025-02-01T00:00:00Z": 0.002939759915409048,
      "2025-03-01T00:00:00Z": 0.002109952362244875,
      "2025-04-01T00:00:00Z": 0.0020224219211965105
    },
    "clientSpeedingDistanceTrendOverTime": {
      "2025-02-01T00:00:00Z": 0.002939759915409048,
      "2025-03-01T00:00:00Z": 0.002109952362244875,
      "2025-04-01T00:00:00Z": 0.0020224219211965105
    }
  },
  "incidentAnalytics": {
    "incidentType": "allIncident",
    "filteredRate": 568.800423,
    "clientRate": 568.800423,
    "filteredRisk": 0,
    "clientRisk": 0,
    "filteredRiskTrendOverTime": {
      "2025-02-01T00:00:00Z": 0,
      "2025-03-01T00:00:00Z": 0,
      "2025-04-01T00:00:00Z": 0
    },
    "clientRiskTrendOverTime": {
      "2025-02-01T00:00:00Z": 0,
      "2025-03-01T00:00:00Z": 0,
      "2025-04-01T00:00:00Z": 0
    },
    "filteredRateTrendOverTime": {
      "2025-02-01T00:00:00Z": 550.104876,
      "2025-03-01T00:00:00Z": 583.110091,
      "2025-04-01T00:00:00Z": 638.430086
    },
    "clientRateTrendOverTime": {
      "2025-02-01T00:00:00Z": 550.104876,
      "2025-03-01T00:00:00Z": 583.110091,
      "2025-04-01T00:00:00Z": 638.430086
    }
  }
}

Response Fields

Field	Type	Description
`incidentRiskAndRates`	Array	Array of risk and rate metrics for different incident types
`incidentRiskAndRates[].type`	String	Specific type of incident (e.g., "Hard Brake", "Distracted Driving")
`incidentRiskAndRates[].risk`	Number	Risk score calculated for this incident type (higher indicates greater risk)
`incidentRiskAndRates[].rate`	Number	Occurrence rate per 1000 kilometers for this incident type
`speedingAnalytics`	Object	Detailed analysis of speeding behaviors
`speedingAnalytics.totalSpeedingDistanceDriven`	Number	Total distance driven while speeding (meters)
`speedingAnalytics.totalDistanceDriven`	Number	Total distance driven in the analyzed period (meters)
`speedingAnalytics.dayTimeSpeedingDistance`	Number	Distance driven while speeding during daylight hours (meters)
`speedingAnalytics.clientAveragePercent`	Number	Average percentage of distance driven while speeding across all clients
`speedingAnalytics.filteredSpeedingDistanceTrendOverTime`	Object	Temporal trend of speeding distance for the filtered dataset
`speedingAnalytics.clientSpeedingDistanceTrendOverTime`	Object	Temporal trend of speeding distance across all clients
`incidentAnalytics`	Object	Detailed analysis of a specific incident type or all incidents combined
`incidentAnalytics.incidentType`	String	The incident type being analyzed (or "allIncident" for combined analysis)
`incidentAnalytics.filteredRate`	Number	Rate value for filtered data (per 1000 kilometers)
`incidentAnalytics.clientRate`	Number	Average rate across all client data (per 1000 kilometers)
`incidentAnalytics.filteredRisk`	Number	Risk score for filtered data
`incidentAnalytics.clientRisk`	Number	Average risk score across all client data
`incidentAnalytics.filteredRiskTrendOverTime`	Object	Temporal trend of risk values for filtered data
`incidentAnalytics.clientRiskTrendOverTime`	Object	Temporal trend of risk values across all clients
`incidentAnalytics.filteredRateTrendOverTime`	Object	Temporal trend of incident rates for filtered data
`incidentAnalytics.clientRateTrendOverTime`	Object	Temporal trend of incident rates across all clients

Usage Notes

Use comparative metrics between your filtered data and client-wide averages for performance benchmarking
Analyze temporal trends to identify improvement or deterioration patterns
Drill down into specific incident types to focus safety initiatives and driver coaching
Consider daylight vs. nighttime speeding patterns for targeted safety programs
Examine associated factors to understand contextual influences on driver behavior
Track behavior scores over time to measure the effectiveness of safety programs
Use speeding severity breakdowns to prioritize interventions for high-risk behaviors
Correlate behavior metrics with environmental factors for comprehensive risk assessment

Environmental Report

GET /reports/overview/environmental

Retrieve comprehensive environmental analytics including road type usage, weather conditions encountered during trips, and intersection analytics. This report helps understand how external factors affect fleet operations and safety, enabling better route planning and risk management.

Request Parameters

Parameter	Type	Location	Required	Description
`x-api-key`	String	Header	Yes	API authentication key
`from`	date-time	Query	Yes	Start date for the environmental analysis (ISO 8601 format). Limited to a 90 day window with respect to `from` and `to`.
`to`	date-time	Query	Yes	End date for the environmental analysis (ISO 8601 format)
`connectionId`	UUID	Query	No	Filter by specific connection
`vehicleId`	UUID	Query	No	Filter by specific vehicle

Example Request

curl --request GET \
  --url "https://api.analytics.autos/reports/overview/environmental?from=2024-01-01T00:00:00Z&to=2024-01-31T23:59:59Z" \
  --header "x-api-key: YOUR-API-KEY"

Response Structure

{
  "roadTypeAnalytics": [
    {
      "roadType": "Other/Inactive",
      "distancePercentage": 0.17271703314147951
    },
    {
      "roadType": "Special Purpose Roads",
      "distancePercentage": 0.09721514617499712
    },
    {
      "roadType": "Small Ways",
      "distancePercentage": 6.19513863970309303
    },
    {
      "roadType": "Major Roads",
      "distancePercentage": 90.68600371439669
    },
    {
      "roadType": "Local Roads",
      "distancePercentage": 1.2727019952205858
    },
    {
      "roadType": "Secondary Roads",
      "distancePercentage": 1.5762234713631627
    }
  ],
  "weatherAnalytics": [
    {
      "weatherType": "Snow",
      "distance": 130310838.49529277,
      "isSevere": true
    },
    {
      "weatherType": "Rain/Drizzle",
      "distance": 231885495.49258122,
      "isSevere": false
    },
    {
      "weatherType": "Mist/Fog",
      "distance": 323046750.49691814,
      "isSevere": false
    },
    {
      "weatherType": "Ice Pellets",
      "distance": 7133679.96133968,
      "isSevere": true
    },
    {
      "weatherType": "Thunderstorms",
      "distance": 55325020.3920226,
      "isSevere": false
    },
    {
      "weatherType": "Clear/Partly Cloudy",
      "distance": 1676696557.333202,
      "isSevere": false
    },
    {
      "weatherType": "Sleet",
      "distance": 9153790.84128854,
      "isSevere": true
    },
    {
      "weatherType": "Cloudy/Overcast",
      "distance": 1907548852.6034174,
      "isSevere": false
    }
  ],
  "intersectionPassedAnalytics": {
    "intersectionPassedCount": 2943427,
    "distanceWithIntersection": 4023191415.937812,
    "intersectionRate": 731.6149533277633,
    "topIntersectionsDensity": [
      {
        "postalCode": "07033",
        "state": "New Jersey",
        "country": "USA",
        "intersectionRate": 1107397.4854366921
      },
      {
        "postalCode": "07410",
        "state": "New Jersey",
        "country": "USA",
        "intersectionRate": 137207.28907399077
      },
      {
        "postalCode": "07002",
        "state": "New Jersey",
        "country": "USA",
        "intersectionRate": 63319.081312534436
      }
    ]
  }
}

Response Fields

Field	Type	Description
`roadTypeAnalytics`	Array	Array of analytics about road type usage
`roadTypeAnalytics[].roadType`	String	Type of road (e.g., "Major Roads", "Local Roads")
`roadTypeAnalytics[].distancePercentage`	Number	Percentage of total distance traveled on this road type
`weatherAnalytics`	Array	Array of analytics about weather conditions encountered
`weatherAnalytics[].weatherType`	String	Type of weather condition (e.g., "Snow", "Rain/Drizzle")
`weatherAnalytics[].distance`	Number	Distance traveled in this weather condition (meters)
`weatherAnalytics[].isSevere`	Boolean	Indicates if this weather condition is considered severe
`intersectionPassedAnalytics`	Object	Analytics about intersections encountered during trips
`intersectionPassedAnalytics.intersectionPassedCount`	Integer	Total number of intersections passed
`intersectionPassedAnalytics.distanceWithIntersection`	Number	Total distance traveled through intersections (meters)
`intersectionPassedAnalytics.intersectionRate`	Number	Rate of intersections per unit of distance
`intersectionPassedAnalytics.topIntersectionsDensity`	Array	List of areas with highest intersection density
`intersectionPassedAnalytics.topIntersectionsDensity[].postalCode`	String	Postal/ZIP code of the area
`intersectionPassedAnalytics.topIntersectionsDensity[].state`	String	State/province of the area
`intersectionPassedAnalytics.topIntersectionsDensity[].country`	String	Country of the area
`intersectionPassedAnalytics.topIntersectionsDensity[].intersectionRate`	Number	Rate of intersections in this area

Usage Notes

Analyze road type distribution to understand your fleet's typical driving environment and exposure
Correlate weather conditions with safety events to identify environmental risk factors and seasonal patterns
Use intersection analytics to optimize routes and reduce exposure to high-density intersection areas
Consider seasonal variations in environmental factors when planning operations and training
Identify high-risk combinations of road types, weather conditions, and time of day
Use time-of-day analytics to schedule operations during safer time periods
Compare incident rates across different environmental conditions to prioritize safety interventions
Target driver training for specific environmental challenges identified in the report

Best Practices for Reports API

Optimizing Report Requests

Date Range Selection
- Use appropriate time ranges to optimize response times and data relevance
- For large fleets, shorter time ranges (e.g., 1-4 weeks) typically provide more manageable and actionable datasets
- Historical trend analysis may require longer ranges with lower detail levels
Filtering Strategies
- Filter by connection ID when analyzing data from specific telematics providers
- Use vehicle ID filtering for individual vehicle performance assessment
- Apply multiple filters to pinpoint specific patterns or issues
Caching Considerations
- Cache report data for frequently accessed time periods to reduce API load
- Implement time-based cache invalidation aligned with your operational cycles
- Consider incremental updates for long-term trend data