Date Range, Pagination, and Sorting

Our APIs support two sets of date range, pagination, and sorting parameters. Each API's documentation indicates which set to use.

Set 1

Date Range

All endpoints allow lookup of data in a specific date range. APIs that use these parameters must have a date range specified in the API call.

Query Parameter	Description
start_date	The date for which you want data. Date format is YYYY-MM-DD. Time Zone is in UTC. If you choose the week or month interval_type, the start_date will be resolved to the first date of the selected interval. For example, selecting month will change the start_date to the 1st of the month. Selecting week will change the start_date to the date of the Monday of that week.
interval_type	Choose from day, week, or month. Monthly data is available for the previous 6 months. Weekly data is available for the previous 12 weeks. Daily data is available for the previous 30 days.

Since API calls use a cursor_id to traverse the data set, you must provide next_cursor_id to receive more data in your response.

Currently, our Server APIs support serving data for the last six months from date of query. This is to avoid heavy latency in the API. If you need data older than 6 months, please email us at [email protected].

Pagination

Several server API endpoints return a list of resources like drivers or trips. Such lists of resources can be large depending on your fleet size (number of drivers or number of trips) and time window of the query. The API provides pagination and sorting parameters to process responses from these list endpoints. All of them are optional.

The list API methods share a common structure for pagination. Zendrive uses cursor-based pagination, using the parameter cursor_id.

Query Parameter	Default	Description
cursor_id	0	A cursor for use in pagination. cursor_id is the index of object that defines your place in the list.
next_cursor_id	N/A	The list API responses contain the next_cursor_id parameter to fetch the next page. When there are no more elements left in the list, next_cursor_id is missing from the response.
limit	10	A limit on the number of objects to be returned. Limit can range between 1 and 50.

Sorting

The list API methods also allow sorting the list by different numerical attributes in both ascending and descending order. This can be done by the order_byand order_type query parameters.

Query Parameter	Default	Description
order_by	none	Specifies the numerical attribute by which to sort the list of resources in the response. This is supported for the following fields: duration_seconds distance_km driver_start_date trip_count zendrive_score By default, lists in responses are unsorted.
order_type	asc	Specifies the sort order. Use asc for sorting in ascending order and desc for sorting in descending order.

Set 2

Date Range

APIs that use these parameters don't require a date range specified in the API call. If a date range is not specified, API endpoints return data for the last one week.

Query Parameter	Description
start_date	The first date (inclusive) for which you want data. Date format is YYYY-MM-DD. Time Zone is in UTC.
end_date	The last date (inclusive) for which you want data. Date format is YYYY-MM-DD. Time Zone is in UTC.

Currently, our Server APIs support serving data for the last six months from date of query. This is to avoid heavy latency in the API. If you need data older than 6 months, please email us at [email protected].

Pagination

Several server API endpoints return a list of resources like drivers or trips. Such lists of resources can be large depending on your fleet size (number of drivers or number of trips) and time window of the query. The API provides pagination and sorting parameters to process responses from these list endpoints. All of them are optional.

The list API methods share a common structure for pagination. Zendrive uses cursor-based pagination, using the parameters offset and limit.

Query Parameter	Default	Description
offset	0	A cursor for use in pagination. offset is the index of object that defines your place in the list. For instance, if you make a list request and receive first 20 objects, your subsequent call should include offset=20 in order to fetch the next page of the result list.
next_offset	N/A	The list API responses also contains next_offset parameter which can be used to fetch the next page. When there are no more elements left in the list, next_offset is missing from the response.
limit	10	A limit on the number of objects to be returned. Limit can range between 1 and 50.

Sorting

The list API methods also allow sorting the list by different numerical attributes in both ascending and descending order. This can be done by the order_byand order_type query parameters.

Query Parameter	Default	Description
order_by	none	Specifies the numerical attribute by which to sort the list of resources in the response. This is supported for: Zendrive score event_rating types in the driving_behavior section of the response (e.g: zendrive_score, overspeeding_rating, phone_use_rating) Numerical attributes in the info section of the response (e.g: distance_km, duration_seconds). driver_start_date By default, lists in responses are unsorted.
order_type	asc	Specifies the sort order. Use asc for sorting in ascending order and desc for sorting in descending order.