Cab Search API

Overview

The Partner Analytics team is working on a new highly searchable cab API that includes many of the dimensions that are available in the Reliability report. This page will describe how to use the Cab Search API. There is a cab search page on the Partner Analytics site within Partner Center that you can use to help create queries for the API. (Link coming soon). The API uses ODATA style queries to perform the searches. The following table lists the different parameters that can be used in the URL. All parameters are optional.

Parameter

Description

filter

This filters the cabs to what you have specifically requested. Look at the dimensions table below to see what dimensions you can filter by.

orderBy

This is a comma delimited string of dimension names to order the results by.

groupBy

This is a comma delimited string of dimensions to group by. This will also return a count of sorts with the results.

select

This is a comma delimited string of dimensions to return in the results. Not specifying anything will return all dimensions. Use this to limit the resulting dataset to what you care about.

continuationToken

This is used to continue searches beyond the initial query results

Filtering Cabs

The Cab Search API allows the users to filter the available cabs in order to find cabs for the exact set of parameters you are looking for. Filtering is done with odata filter conventions. You can find the specifications here.

Multiple filters

If you want to two conditions to be met, you can use theandoperator. For example, the following query is used to find cabs on 4/15/2022 and are for incident 1234567.

?filter=CabDate eq '2022-04-15' and Incident_IncidentId eq 1234567

If you want to return results for two possible values, you can use theoroperator. The following query will return results for cabs on 4/15 or 4/16.

?filter CabDate eq '2022-04-15' or CabDate eq '2022-04-16'

Important Note: Has is not supported.

Ordering Results

The Cab Search API provides the ability to order the results using the orderBy parameter. This will return the search results sorting by the specified list of columns in ascending order. For example, if you want to sort by CabDate, you can specify the following on the URL:

?orderBy=CabDate

If you want to sort by a list of columns, specify the columns in comma delimited format. For example:

?orderBy=Incident_FailureHash,CabDate

Grouping by columns/dimensions

The Cab Search API provides the group by feature for those that want to get a list of values for a set of dimensions and/or a count of cabs for each of those values. For example, if you wanted to get a list of driver versions that match a filter, you would add the following to the URL:

?groupBy=Driver_Version

This will return results such as

[ { "Driver_Version": "1.0.0.0", "Count": 15 }, { "Driver_Version": "1.0.3.1", "Count": 300 } ]

This allows you to quickly find what buckets have the most cabs that you need or want.

Important Note #1: the Cab Search API is a search API. It is not an analytics engine. The Reliability Report is the place of record for getting accurate crash counts.

Important Note #2: The counts that are returned are per partition counts. If you continue the search, you will get multiple duplicate values back with different counts. You will need to sum all of the counts with the matching buckets. For example, given the prior search above, if you continue the search, you will see "1.0.0.0" again in the results. You will need to sum all counts for "1.0.0.0" to get an approximate count for how many cabs are available in that bucket.

Important Note #3: This data source is concurrent. The cabs are being loaded at the same time that queries are occuring and so you may get different counts for consecutive queries. The API and underlying data store is built to be concurrency safe. The data sets are not locked while queries are happening.

Important Note #4: orderBy and groupBy cannot be used on the same query. The underlying system does not support it.

Selecting Columns

The Cab Search API supports selecting a list of columns/dimensions in the returned results. If your queries only need to have a few items or you only need to get the Cab IDs, you can use the select parameter. For example, if you want to select a single column such as CabId, you would use the following in the URL:

?select=CabId

If you want to return multiple columns such as CabId, Driver_Name, and Driver_Version, you would add the following to the URL:

?select=CabId,Driver_Name,Driver_Version

Continuing Searches/Pagination

This API supports pagination by default. It will return up to 1000 results for each query. Each query will return a continuation token, a full URL for continuing the query, and whether the query has more results or not. The continuation tokens will remain for 24 hours. To continue a query, you can use the continuationLink returned in the response.

Searchable Dimensions

Here is a table that maps the dimensions that are in the Reliability report to the dimensions that are available in the new cab API: