# Report Data
The new API docs can be found here: [https://apidocs.mediamath.com/apis/reporting-api](https://apidocs.mediamath.com/apis/reporting-api)
# 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/apis/reporting-api-v1/section/fields](https://apidocs.mediamath.com/apis/reporting-api-v1/section/fields) 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
| Operators | Operation | Field Data Type |
| --- | --- | --- |
| =, != | equality, non-equality check | all |
| >, <, >=, <= | inequality check | numeric |
| ~, =~ | contains, case sensitive | string |
| =: | contains, case insensitive | string |
| !~ | does not contain, case sensitive | string |
| !: | does not contain, case insensitive | string |
##### 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/apis/reporting-api-v1/metadata/get_report-meta](https://apidocs.mediamath.com/apis/reporting-api-v1/metadata/get_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](http://www.w3.org/Protocols/rfc2616/rfc2616-sec6.html#sec6.1.1)). 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](http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.6.1) 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](http://www.w3.org/Protocols/rfc2616/rfc2616-sec6.html#sec6.1.1)). 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
Authentication Required
```
```
HTTP/1.0 403 Forbidden
Content-Type: text/xml; charset=UTF-8
Insufficient permissions
```
### Parameter validation errors (malformed values, unknown fields, missing required parameters, etc)
```
HTTP/1.0 400 Bad Request
Content-Type: text/xml; charset=UTF-8
a time window is required
```
### Non-existent entities
```
HTTP/1.0 404 Not Found
Content-Type: text/xml; charset=UTF-8
Entity Not Found
```
### Server errors (internal error, request timeout, scheduled maintenance, server overloaded)
```
HTTP/1.0 500 Internal Server Error
Content-Type: text/xml; charset=UTF-8
Internal Server Error
```
```
HTTP/1.0 500 Internal Server Error
Content-Type: text/xml; charset=UTF-8
The request timed out
```
```
HTTP/1.0 503 Service Unavailable
Content-Type: text/xml; charset=UTF-8
The server is temporarily unavailable due to maintenance downtime.
```
Endpoint: GET /{report}
## Path parameters:
- `report` (string, required)
This must be a report discoverable from https://apidocs.mediamath.com/apis/reporting-api-v1/metadata/get_meta.
## Query parameters:
- `dimensions` (string, required)
Selects the dimension fields to use in grouping rows.
This should be a comma-separated list of dimension field names.
The position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.
- `metrics` (string)
Controls the selection of metric fields.
This should be a comma-separated list of metric field names.
If not specified, this will default to the metric fields specified by the `default_metrics` property of the .
The position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.
- `filter` (string, required)
Controls filtering against dimension fields. The filtering is performed before row grouping. See the Predicate Parameters section of for more information about interpretation and accepted formats.
- `having` (string)
Controls filtering against metric and dimension fields. The filtering is performed after row grouping and metric calculation. See the Predicate Parameters section of for more information about interpretation and accepted formats.
- `time_rollup` (string, required)
The allowed values are specified by the time_rollups report meta property. See the Time Field section of for more information.
- `time_window` (string, required)
Controls filtering against the time field for the report. See the Time Field section of for more information.
- `start_date` (string, required)
Controls filtering against the time field for the report. See the Time Field section of for more information.
- `end_date` (string)
Controls filtering against the time field for the report. See the Time Field section of for more information.
- `order` (string)
Controls the sorting of the groups.
This should be a comma-separated list of field names. Each field name may optionally be prefixed with a minus sign to indicate descending order. Otherwise, ascending order is assumed.
The first field has the most significance in sorting.
- `page_limit` (integer)
Controls the maximum number of rows of data.
This parameter is required, if page_offset is one or greater.
- `page_offset` (integer)
Controls how many pages to skip.
- `precision` (integer)
Controls how many digits to the right of the decimal places to display for float types.
## Header parameters:
- `Cookie` (string, required)
_
- `Accept-Encoding:` (string)
If the client supports the compression methods also supported by the server (currently `gzip` and `deflate`), the response data set (`text`\/`csv`) will be returned in a compressed format. The metadata and error responses will not be compressed.
In order to receive the data in compressed format, the client must use the HTTP request header `Accept-Encoding`, and enumerate the preferred compression methods (see [RFC 2616](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)). If the header `Accept-Encoding` is not present in the request, or if it contains only compression methods not supported by the system, the data will be returned in an uncompressed format.
### request
Accept-Encoding: gzip,deflate
### response
Content-Encoding: gzip
Content-Type: text/csv; charset=UTF-8
- `If-Modified-Since` (string)
If the data has not changed, the server responds with a 304 Not Modified status code and an empty response body.
If the same request was issued and the data had been updated since the specified time, the server responds with the data requested and a new Last-Modified header.