Query Parameters
The AnywhereNow Insights API offers an array of optional query parameters that can be used to customize the data that is returned in a response. These parameters allow users to control the amount of data that is returned, as well as the format and structure of the response. By utilizing these query parameters, users can quickly and easily access the data they need without having to sift through an excessive amount of information.
OData system query option
AnywhereNow Insights API operations can support one or more of the OData V4 query options. These query options are compatible with the OData V4 query language and are available for use in GET operations.
|
Name |
Description |
Example |
|---|---|---|
|
Retrieves the total count of matching resources. |
|
|
|
Filters results (rows). |
|
|
|
Orders results. |
|
|
|
Filters properties (columns). |
|
|
|
Sets the page size of results. |
|
|
|
Indexes into a result set. Also used by some APIs to implement paging and can be used together with |
|
Other OData URL capabilities
AnywhereNow Insights API (using OData 4.0) offers a range of URL segments that can be used to access data, rather than query parameters. These capabilities include:
|
Name |
Description |
Example |
|---|---|---|
|
Retrieves the integer total of the collection. |
|
Encoding query parameters
Query parameter values should be percent-encoded in accordance with RFC 3986. This means that all reserved characters in query strings must be encoded. There are many HTTP clients, browsers, and tools (like PostMan) that can help with this. If a query is not working, it could be due to not encoding the query parameter values correctly. In some cases, you may need to encode the values twice.
An unencoded URL looks like this:
The corresponding percent-encoded URL is:
And the double-encoded URL is:
count parameter
The $count query parameter can be used to retrieve the total number of items in a collection or matching an expression. This parameter can be used in a variety of ways:
-
As a query string parameter with the syntax
$count=trueto include a count of the total number of items in a collection alongside the page of data values returned from AnywhereNow Insights API. -
It can be used as a URL segment to retrieve only the integer total of the collection. For example
Dialogues/$count -
In a
$filterexpression with equality operators to retrieve a collection of data where the filtered property is an empty collection. See Using filters
For example, the following request returns both the user collection, and the number of items in the user collection in the @odata.count property. By using the $count parameter, users can quickly and easily determine the size of a collection or the number of items matching an expression. This can be especially useful when dealing with large collections of data, as it allows users to determine the size of the collection without having to manually count each item.
filter parameter
The $filter query parameter can be used to narrow down the results of a collection. It allows you to retrieve only the objects that meet certain criteria. To use the $filter parameter, you must specify the property that you want to filter by, as well as the condition that the property must meet. For example, if you wanted to retrieve only dialogues that where accepted, you would use the following syntax: $filter=ActionType eq 'Accepted'. For more information on how to use the $filter parameter, see Using filters. This will provide you with guidance on how to construct the $filter query and what the available operators are. With the $filter parameter, you can easily retrieve only the objects that meet your criteria, making it a powerful tool for managing collections.
orderby parameter
The $orderby query parameter is a powerful tool that allows you to specify the sort order of the items returned from AnywhereNow Insights. By default, the results are returned in ascending order, but you can also choose to sort the results in descending order by appending either asc or desc to the field name, separated by a space. For example, ?$orderby=name%20desc. If the sort order is not specified, the default (ascending order) is inferred.
You can also order results on multiple properties. For example, the following request orders the dialogues, first by the ActionType in descending order (Z to A), and then by SessionDurationInSec in ascending order (default).
This is a useful feature when you need to quickly and easily sort through large amounts of data. With the $orderby query parameter, you can easily organize and sort your results in a way that makes sense for your specific needs.
select parameter
The $select query parameter allows you to specify a subset or superset of the default properties for a single resource or a collection of resources. For instance, when retrieving Dialogues, you can choose to return only the id and actiontype properties. To do this, you would make a the following request:
This will return only the id and actiontype properties, instead of the default set of properties. This can be a useful tool when you only need a few specific properties from a resource or collection of resources.
top parameter
The $top query parameter is an useful tool for specifying the number of items to be included in the result. This parameter allows a minimum value being 1 and the maximum value depending on the corresponding API. For instance, if you wanted to get the first five dialogues from the API, you could use the following request:
This is an useful feature, as it allows you to quickly and easily get the exact number of items you need for your application. Additionally, you can also use the $top parameter in combination with the $skip parameter to page through a collection, allowing you to get a specific subset of the data you need. To learn more, see Using paging.
skip parameter
If you want to skip a certain number of items at the start of a collection, you can use the $skip query parameter. This will allow you to specify the number of items you want to skip from the beginning of the collection. For example, if you wanted to start with the 21st dialogue in the collection, you could use the following request:
This will return dialogues sorted by datetime started, beginning with the 21st dialogue in the collection. Additionally, you can also use the $top parameter in combination with the $skip parameter to page through a collection, allowing you to get a specific subset of the data you need. To learn more, see Using paging.