<!-- theme: danger -->

This API is deprecated and will be removed soon

The new API docs can be found here: https://apidocs.mediamath.com/docs/reporting-api-v2

Parameters

Parameter names are case sensitive, (see the table below).

Most parameters will fall under one of the following two formats.

• enumeration of comma-separated items (used in aggregation, selection and sorting);
  • example:
    • dimensions=campaign_id%2Ccampaign_name%2Ccampaign_start_date (in other words, campaign_id,campaign_name,campaign_start_date)
• list of logically AND-ed expressions, joined by ampersand (used in dimension and metric filtering);
  • examples:
    • filter=campaign_id%3D12345%26strategy_id%3D98765 (in other words, campaign_id=12345&strategy_id=98765)
    • having=impressions%3E%3D500%26clicks%3C100 (in other words, impressions>=500&clicks<100)

Query Options

A query can filter, aggregate, sort, paginate, and format a report's data.

Filtering is required. It must be done on the time field, and one or more dimension fields that have their access property set to true. It can be done both before and after aggregation.

Aggregation, like filtering, is also required. The grouping must be performed against the time field and a combination of one or more dimension fields.

Sorting, pagination, and formatting are not required. The features are controlled via the order, page_limit, page_offset, and precision parameters. They are described in full detail in the Definition section at the end of the documentation for this endpoint.

Filtering

Data filtering may be performed before rows are grouped, and afterwards as well.

It can be done before grouping via the time_window, start_date, end_date, and filter parameters. This provides finer control over what rows contribute to the metric fields of a group.

Filtering can also be done after grouping, and metric calculations via the having parameter.

For more information about the time_window, start_date, and end_date parameters see the https://apidocs.mediamath.com/docs/api/a726318c29d15-reports-api section.

For more information about the filter and having parameters see the following section.

Predicate Parameters

filter and having are predicate parameters. One of the two parameters is required. The parameters consist of one or more predicates. A predicate has the following format.

1. a dimension or metric field from the report definition
2. an operator from the Operators supported in filtering expressions table
3. one or more values matching the type of field

At least one predicate parameters is required. This is because at least one of the predicates must use one of the access dimension fields in an equality test (operator =).

The filter parameter filters on dimension fields only, while the having parameter may filter by both dimension and metric fields. The filter parameter is applied before rows are grouped, while the having parameter is applied after rows have been grouped, and metrics have been calculated.

The parameter filter is not required if access dimension fields are used in parameter having. Using dimension fields in the having parameter causes those dimension fields to be used in grouping rows.

Operators supported in filtering expressions

Multiple Predicates

More than one predicate may be specified in a predicate parameter. The predicates need to be joined together with an ampersand (&). The ampersand indicates the predicates are ANDed together. As such, for a record to appear in the results, each predicate must evaluate to true for that record. The following shows an example.

###  filtering aggregated rows by metric or dimension fields
having=impressions%3E%3D500%26clicks%3C100%26campaign_id%3D12345
###  (i.e.  impressions>=500&clicks<100&campaign_id=12345)

###  filtering base rows by dimension fields
filter=campaign_id%3D12345%26strategy_id%3D98765%2Cstrategy_goal_type%3Dcpc
###  (i.e.  campaign_id=12345&strategy_id=98765&strategy_goal_type=cpc)

Predicates with Multiple Values

A predicate is considered true, if one or more values evaluate as true for the given field and comparison operation. This result is then ANDed with any other predicates that exist at that level of filtering. Values must be separated by commas. The following shows an example.

### filtering records for when campaign_id is 11111, 22222, or 33333 and the campaign_name contains "sell"
filter=campaign_id%3D11111%2C22222%2C33333%26campaign_name%7Esell
###  (i.e.  campaign_id=11111,22222,33333&campaign_name~sell)

Encoding Predicates

In order to ensure predicates and values are properly separated, a special encoding is needed for predicate values that contain any of the following characters.

& , " < > = ~ ! :

The encoding is a simple two step process.

1. Double quotes are doubled.
2. The resultant value is surrounded in double quotes.

The following shows an example.

• Unencoded: Jack & Jill "Of All Trades"
• Encoded: "Jack & Jill ""Of All Trades"""

This special encoding may be applied to any value in the predicates. It does not determine the type. The looseness is there to allow for URLs to be more readable. It does however, need to be applied before URL encoding is performed.

Aggregation

Through the dimensions, one can indicate the way the rows must be grouped. One or more dimension fields, may be specified. The order in which the dimension fields are listed is important for the result set.

###  group by these fields in this order dimensions=campaign_id%2Ccampaign_name%2Ccampaign_start_date
###  (i.e.  campaign_id,campaign_name,campaign_start_date) 

See the Time Field section of the https://apidocs.mediamath.com/docs/api/e39ffafb5c6cb-report-meta for grouping options available for the time field.

Grouping by metric fields is not allowed. Metric fields are calculated based on the underlying rows of each group. The metrics can be chosen via the metrics parameter.

###  calculate these metrics per group dimensions=clicks%2Cimpressions
###  (i.e.  clicks,impressions) 

On Success

The system returns an appropriate HTTP return code (2xx or 3xx - see RFC 2616). The response body is CSV-formatted (Content-Type: text/csv), consisting of one header row, and zero or more data rows. The response uses the HTTP 1.1 chunking feature.

A data row will represent a group. It will have a start_date/end_date format, or an interval format. Always use the header line to determine the order of columns, as they may not match the order listed in the parameters.

start_date/end_date Format

• two columns of type datetime:
  • start_date - the start of the time rollup interval (inclusive)
  • end_date - the end of the time rollup interval (inclusive)
• all dimension fields specified in the parameters dimensions
• all metric fields specified in the parameter metrics
• all fields, dimension or metric, specified in the parameters having and order

Note that the start_date and end_date will cover the whole interval specified by the parameter time_window (or start_date / end_date equivalents), or the intervals generated according to the parameter time_rollup, even though data may not exist for the whole interval.

start_date,end_date,campaign_id,campaign_name,creative_id,creative_name,clicks,impressions,total_spend
"2013-05-01","2013-05-22",123456,"My Campaign Nr 10",98765432,"Creative No 12",17701,171981779,45266.65
"2013-04-24","2013-04-30",123456,"My Campaign Nr 10",11223344,"Creative Nr Five",4101,45076933,7566.57
"2013-04-24","2013-04-30",123456,"My Campaign Nr 10",12121212,"Creative Ten",5220,42592353,6360.86
"2013-05-01","2013-05-22",123456,"My Campaign Nr 10",99887766,"Creative One",21912,41691908,61644.34 

interval Format

• one field of type interval:
  • interval - the pre-aggregated interval of the group.
• all dimension fields specified in the parameters dimensions
• all metric fields specified in the parameter metrics
• all fields, dimension or metric, specified in the parameters having and order

interval,campaign_id,campaign_name,creative_id,creative_name,clicks,impressions,total_spend
7,123456,"My Campaign Nr 10",98765432,"Creative No 12",17701,171981779,45266.65
7,123456,"My Campaign Nr 10",11223344,"Creative Nr Five",4101,45076933,7566.57
7,123456,"My Campaign Nr 10",12121212,"Creative Ten",5220,42592353,6360.86
7,123456,"My Campaign Nr 10",99887766,"Creative One",21912,41691908,61644.34 

Predicting the Format

interval based report queries will return the interval format.

datetime based report queries:

• using a special time window will return the interval format.
• using a normal time window will return the start_date/end_date format.

On Error

On error, an appropriate HTTP status code is returned (4xx or 5xx - see RFC 2616). The response body, which of type XML (Content-Type: text/xml) will contain, at the minimum (see examples below), the root element result, with at least one element named status, which in turn has an attribute named code, and a human readable text. Some error responses also contain an attribute reason, which adds more information regarding the error.

There are several types of errors:

Authentication and authorization errors

HTTP/1.0 401 Unauthorized
Content-Type: text/xml; charset=UTF-8

<result>
  <status code="auth_required" reason="not_logged_in">Authentication Required</status>
</result>

HTTP/1.0 403 Forbidden
Content-Type: text/xml; charset=UTF-8

<result>
  <entity id="12345" type="campaign" />
  <status code="denied">Insufficient permissions</status>
</result>

Parameter validation errors (malformed values, unknown fields, missing required parameters, etc)

HTTP/1.0 400 Bad Request
Content-Type: text/xml; charset=UTF-8

<result>
  <status code="bad_request" reason="missing_time_window">a time window is required</status>
</result>

Non-existent entities

HTTP/1.0 404 Not Found
Content-Type: text/xml; charset=UTF-8

<result>
  <entity id="12345" type="campaign" />
  <status code="not_found">Entity Not Found</status>
</result>

Server errors (internal error, request timeout, scheduled maintenance, server overloaded)

HTTP/1.0 500 Internal Server Error
Content-Type: text/xml; charset=UTF-8

<result>
  <status code="error">Internal Server Error</status>
</result>

HTTP/1.0 500 Internal Server Error
Content-Type: text/xml; charset=UTF-8

<result>
  <status code="request_timeout">The request timed out</status>
</result>

HTTP/1.0 503 Service Unavailable
Content-Type: text/xml; charset=UTF-8

<result>
  <status code="unavailable">The server is temporarily unavailable due to maintenance downtime.</status>
</result>

<!-- theme: danger -->

This API is deprecated and will be removed soon

The new API docs can be found here: https://apidocs.mediamath.com/docs/reporting-api-v2

Validating Data Retrieval Requests

Data retrieval requests can be validated and authenticated without actually requesting data, by simply appending a /validate path segment to the URI. Important: The validation process takes into account the current user's permissions. The error responses that are returned in case of validation failure are the same as the ones that would have been returned by the regular API call.

The following shows an example validation request for a request with an erroneous organization_id filtering parameter:

GET /reporting/v1/std/{report}/validate?filter=organization_id%3D12345&dimensions=campaign_id%2Corganization_id&time_window=last_7_days&time_rollup=by_day

HTTP/1.0 404 Not Found
Content-Type: text/xml; charset=UTF-8

<?xml version='1.0' ?>
<result>
  <entity id="12345" type="organization" />
  <status code="not_found">Entity Not Found</status>
</result>

By contrast, this call shows a validation response for a valid call:

GET /reporting/v1/std/{report}/validate?filter=organization_id%3D12346&dimensions=campaign_id%2Corganization_id&time_window=last_7_days&time_rollup=by_day

HTTP/1.0 200 OK
Content-Type: text/xml; charset=UTF-8

<?xml version='1.0' ?>
<result>
  <status code="ok" />
</result>