GET requests to the /views endpoint, the DiVA API provides a filter syntax and query parameters that allow you to customize the responses. You can obtain the field names and associated data types for a given view by retrieving a JSON representation of the schema.
Response formats
JSON results
The default response format is a JSON object that contains metadata about the query results and an array of records matching your query. The API processes the request synchronously and returns up to a limit of 10,000 result records. The following sample shows a JSON response. For a description of the metadata returned with query results, see Response field details on this page.JSON
File exports
As an alternative to returning your dataset as a JSON object, you can export it as a CSV file. The export mechanism operates asynchronously and returns up to 1,048,576 rows in the file. You can choose between Zip and Gzip file compression. See Exporting and Downloading Datasets for more information.Schema object
You can retrieve the JSON-formatted schema for any view by appending/schema to the endpoint URL. The schema contains an array of objects that describe the fields available in the view, including the data type of each field. For example, to retrieve the view schema for authorization transaction data aggregated by week, send a GET request to the /views/authorizations/week/schema endpoint.
The following table lists the possible properties for a field in the view schema.
The following table lists the possible data types for fields.
Query filtering
You can filter the results by values in any fields of a view. If you do not include a date range in your query, the API returns matching data for a recent period of time. For example, suppose you want to query the load data for February (post_date=2023-02-01..2023-02-28), and you only want to retrieve results for days on which the load amount was greater than $1000 (amount=>1000). You send a GET request to the following endpoint:
/views/loads/day?program=my_program&transaction_amount=>1000&post_date=2023-02-01..2023-02-28
The filter syntax supports the following operators.
Create lists by combining values with a comma (
,). You can use lists with the in (=) and not in (=!) operators only.
Use double quotes (") around strings that contain spaces.
Warning
The filter logic must be compatible with the data type of the field. If you use an operator that is not compatible with the data type of a field, the API returns a
The filter logic must be compatible with the data type of the field. If you use an operator that is not compatible with the data type of a field, the API returns a
400 HTTP error code. To obtain the field names and associated data types, retrieve the schema object. For more details, see Schema Object on this page.Field filtering
You can select which fields to return and in what order by appending thefields query parameter to your request and specifying a comma delimited list of field names. For example:
/views/authorizations/detail?program=my_program&fields=transaction_timestamp,state,transaction_amount
Record sorting and counting
The DiVA API supports sorting and counting for customized responses. You can usesort_by to choose the order of the records and count to return a specific range or a specific number of the ordered records. You control sorting and counting by appending query parameters to your request.
For example, to return the 100 largest authorization requests for a day, send a GET request to the following endpoint:
/views/authorizations/detail?program=myprogram&transaction_timestamp=2023-10-21&sort_by=-request_amount&count=100
Query parameter details
The following table provides details on the URL query parameters that control sorting and counting.Response field details
The following table describes metadata returned with query results.Data aggregation levels
For some view endpoints, you must specify the aggregation level for data in the response. For example, you may want to aggregate transactional data by day or by month. The available aggregation options vary based on the type of data in the view.By time period
Thetime_agg path parameter specifies the available levels for data that can be aggregated by time period, such as transactions.
By level of card network detail
Thecolumn_detail path parameter specifies the available levels for data that can be aggregated by card network, such as loads and purchases.
Grouping and aggregating
The DiVA API enables you to sum and group numeric data. In a general sense, this functionality lets you answer the question: How much of quantity X exists per category Y? Quantity X represents your numeric data, and category Y represents your grouping. For example, you might like to know the total amount of money your cardholders spent per merchant over some time period. To construct a query that answers this question, you use both thefields and the group_by query parameters in your URL. The fields parameter specifies your numeric data, which in this case is the transaction amount. The group_by parameter specifies how you want your numeric data grouped. In this case, you want it grouped per merchant. You can then add an additional parameter to filter your results to fall within your desired time period. Here is a URL that performs that query and a sample record from the returned dataset:
/views/authorizations/detail?program=my_program&fields=merchant,transaction_amount&group_by=merchant&transaction_timestamp=2023-04-05
JSON
group_by value (in this case, merchant) in the fields parameter. The order of fields within the fields parameter controls the ordering of fields in the returned records.