/
10 minute read
October 6, 2021

Response Customization

The DiVA API provides view endpoints for requesting aggregated data from the Marqeta platform. You can retrieve data as a JSON object or export the data in a file.

For 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
Copied

Is this helpful?

Yes
No

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.

Name Description

field

Field name in the view.

type

Data type of the field. See possible data types in the following table.

display

Column name in the related report in the Marqeta Dashboard, if applicable.

enum_values

List of allowable values, if applicable.

units

Type of currency, if applicable; otherwise null.

has_total

True if the field value can be used to compute a total value (for example, most integer fields, except for the last four numbers of a card).

date_format

Format of the string for a date field.

is_filter_only

True if the field is not part of the view schema and is used only for filtering results.

The following table lists the possible data types for fields.

Type Description

integer

Number for integer data.

numeric(x,y)

Number with x digits, y decimals.

bigint

Number for integer data that may exceed the range supported by int.

character varying(x)

String with max length x.

timestamp without time zone

Date-formatted string (e.g. 2017-01-18T09:44:54.000Z).

date

Date-formatted string with zeros as the time (e.g. 2017-01-18T00:00:00.000Z).

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=2018-02-01..2018-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=2018-02-01..2018-02-28

The filter syntax supports the following operators.

Operator Description Example

~

Like, interprets a wildcard on both sides of the operator.

company=Mar~eta

..

Range between, includes the start and end values of the range.

date=2016-10-01..2016-10-03

includes dates from 10/01/16 to 10/03/16

<, <=

Less than, Less than or equal to.

request_amount=<=100

>, >=

Greater than, Greater than or equal to.

date=>=2018-04-01

=

For numeric values, equal to. For string values, in list.

amount=0

country="United States of America",Mexico,Canada

=!

For numeric values, not equal to. For string values, not in list.

amount=!0

last_name=!Summers,Rosenberg,Harris

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 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 the fields 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

Sorting and pagination

The DiVA API supports sorting and pagination for customized responses. You can use sorting to choose the order of the records and pagination to return a specific range or a specific number of the ordered records. You control sorting and pagination 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=2017-10-21&sort_by=-request_amount&count=100

To ensure that pagination is working as intended, do not request a subset of fields that are fewer than the default. To loop programmatically through paged records, use either when is_more is false or when total == count to determine when to exit the loop.

Query parameter details

The following table provides details on the URL query parameters that control sorting and pagination.

Tip
For deterministic sort results—that is, results that are consistent every time you sort—use sort_by on fields with unique values. Sorting on fields with non-unique values may produce inconsistent results.
Note
When using the start_index parameter for a JSON request, the value of count must be less than or equal to 10,000.
Fields Description

sort_by

string
Optional

Fields by which to sort. Use any fields in the view schema, or one of the system fields lastModifiedTime or createdTime. Prefix a field name with a hyphen (-) to sort in descending order. Omit the hyphen to sort in ascending order.

Allowable Values:

Any field in the schema

Default value:
Varies by view

count

integer
Optional

Maximum number of records to return. Corresponds to a LIMIT clause in SQL.

Allowable Values:

Up to 10,000 for JSON

Up to 5,000,000 for file exports

Default value:
10,000

start_index

integer
Optional

Sort order index from which to begin returning data. Corresponds to an OFFSET clause in SQL.

Allowable Values:

Any integer

Default value:
0 (the first row)

Response field details

The following table describes metadata returned with query results.

Fields Description

total

integer
Optional

Number of records that match the filter query.

Allowable Values:

Any integer

is_more

boolean
Optional

Indicates whether more unreturned records exist that match the filter query. Returns false if the optional count filter is used.

Allowable Values:

true, false

count

integer
Optional

Number of records returned.

Allowable Values:

Up to 10,000 for JSON; up to 1,048,576 for file exports

info

object
Optional

Error messages for the request, if applicable.

Allowable Values:

JSON object

start_date

string
Optional

Creation date and time of earliest record returned.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ssZ

end_date

string
Optional

Creation date and time of latest record returned.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ssZ

last_run_time

string
Optional

Date and time this query was run. Applies when the data is cached from a recent query. For more information, see Data Caching.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ssZ

schema

array of objects
Optional

Array containing the schema for the returned records.

Allowable Values:

JSON object

records

array of objects
Optional

Array containing the returned records.

Allowable Values:

JSON object that matches the schema

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

The time_agg path parameter specifies the available levels for data that can be aggregated by time period, such as transactions.

Name Description

detail

Each row contains details about a single event, such as a transaction.

day

Each row contains data aggregated over a day.

week

Each row contains data aggregated over a week.

month

Each row contains data aggregated over a month.

By account

The account_agg path parameter specifies the available levels for data that can be aggregated by account, such as balances.

Name Description

actor

Each row contains data aggregated by acting cardholder.

accountholder

Each row contains data aggregated by account.

business

Each row contains data aggregated by business account.

By level of card network detail

The column_detail path parameter specifies the available levels for data that can be aggregated by card network, such as loads and purchases.

Name Description

overview

Shows data aggregated across card networks.

networkdetail

Shows data broken out by card network.

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 the fields 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=2018-04-05

JSON
Copied

Is this helpful?

Yes
No

As the sample indicates, you should include your 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.

Subscribe to our developer newsletter