Reporting API V1

<!-- 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

<!-- theme: warning -->

Support for adama_cookie will be removed later this year. We ask all of our clients who have not yet migrated to OAuth2 authorization to do so as soon as possible.

The Reports API on MediaMath Platform allows advertisers to access, query and aggregate reporting data. It is also the API that powers all reporting seen on our MediaMath Platform flagship UI.

The Reports API offers a number of reports. Each report offers its own pre-aggregated, time-based metrics on entities that users can query. A query can filter, aggregate, sort, paginate, and format this data.

It is a read-only system meaning no request against it can alter the data in any way.

It is also a metadata-driven system. The supported reports are described in a human- and machine-readable format. This ensures easy one-off and repeatable programmatic data querying. It also provides a way for clients to adapt to changes in reports programmatically. This gives client-developers the ability to create UIs that provide useful operational feedback in a navigable and understandable way.

The $API_BASE for the latest version of Reports API is

https://api.mediamath.com/reporting/v1/std

Authentication

Fields

Report data is stored and output in a tabular format. This means that the output consists of rows and columns. Every row has a value for every column.

The structure object can be used to determine the columns a report can output. Its fields are divided among three mappings - time_field, dimensions, and metrics. Each mapping, maps field name to #model:Fqbi8siNTuFGqA2W5.

{
  
  "time_rollups" : [ "by_day", "by_week", "by_month", "all" ],
  "time_windows" : [ "yesterday", "last_X_days", "month_to_date", "campaign_to_date" ],
  "timezone" : "campaign timezone",
  "time_aggregation" : "by_day",
  "structure" : { 
    "time_field" : { 
      "date" : { 
        "name" : "Date",
        "type" : "datetime"
      }
    },  
    "dimensions" : {
      "campaign_id" : { ... },
      "campaign_name" : { ... },
      "strategy_id" : { ... },
      "strategy_name" : { ... }
    },  
    "metrics" : { 
      "clicks" : { ... },
      "impressions" : { ... }
    }
  }
  ...
}

Time Field

The time field represents the time-component of the report's metrics. There is (currently) only one time field for each report. It can be of one of these data types: datetime or interval. Its data type determines the type of report (datetime or interval based report).

Note: The type of report is not to be confused with the Type attribute. The Type attribute is purely informational.

The time field was distinguished from the dimension fields to allow its use in grouping and filtering rows easier to understand. It gets its own set of parameters and language.

datetime-typed Time Fields

Datetime-typed time fields contains a combination of year, month, day, and possibly down to hour, minute and second. The time_aggregation property indicates the field's finest grain (by_hour, by_day, etc). The time_rollups property indicates the available grouping options that can go beyond the time_aggregation of the report.

time_rollup=by_week     ### group rows by the week  -  week starts on Monday 
time_rollup=by_month    ### group rows by the month
time_rollup=all         ### produces at most one row of output per combination of dimension fields
                        ### listed in the dimensions parameter

The time field for these reports are typically represented in the output by a start_date and end_date column. The format of the column will depend on the time window and time_rollup.

  • YYYY-MM-DD
  • YYYY-MM-DD hh:mi:ss

The only exception to this rule is detailed in the Special Time Windows section.

The timezone of the start_date and end_date columns will match the timezone property.

interval-typed Time Fields

interval-typed time fields, contain a predefined non-calendar date based aggregation (1 day, 7 days, 30 days, and so on). In this case, the only accepted way to specify a time interval is by using the parameter time_window. The only value supported for the parameter time_rollup for interval-based reports is all.

The time field for these reports are represented in the output by a interval column. The value of the column will depend on the time_window chosen. The following gives example column values based on the time_window.

  • yesterday - 1
  • last_7_days - 7
  • last_30_days - 30
  • campaign_to_date - CTD
  • flight_to_date - FTD

Filtering with the Time Field

The API requires the specification of a time window in order to narrow the data set operated on. A time window must be specified in one of the two possible ways.

  • start_date and end_date (optional - defaults to "yesterday").
  • time_window may be set to one of the formats defined by the time_windows attribute.
###  operate on data timestamped between Jan 01, 2013 and Feb 01, 2013, inclusive
start_date=2013-01-01&end_date=2013-02-01  
###  operate on data timestamped between May 05, 2013 and yesterday, inclusive
start_date=2013-05-01  
###  other usage examples 
time_window=last_30_days 
time_window=month_to_date 
time_window=yesterday 
start_date and end_date

start_date and end_date may only be used when the report's time field is of the datetime type. They may not be used when the report's time field is of the interval data type. This is because the time_windows are pre-defined intervals that cannot be split.

The start_date and end_date parameters define inclusive boundaries for the data. In order to ease the burden of calculating an inclusive end, the inputs may be specified at various granularities.

  • month - YYYY-MM
  • day - YYYY-MM-DD
  • hour - YYYY-MM-DDThh
  • minute - YYYY-MM-DDThh:mi
  • second - YYYY-MM-DDThh:mi:ss

Each granularity matches a substring of the ISO 8601 format.

If the report is at a coarser granularity (see time_aggregation) than the input, the input will be taken to mean the entirety of the time unit.

start_date=2016-04-12T01%3A30%3A00&end_date=2016-04-12T02%3A30%3A00
# ie. start_date=2016-04-12T01:30:00&end_date=2016-04-12T02:30:00
# For a report with a time_aggregation of by_hour:
# 2016-04-12T01:00:00 to 2016-04-12T02:59:59.
 
# For a report with a time_aggregation of by_day:
# 2016-04-12T00:00:00 to 2016-04-12T23:59:59
time_window

All values mentioned in the time_windows array will be accepted verbatim by the time_window parameter with the exception of any time window that starts with last_X_. They may be interpreted as such.

  • The last_X_days time window ends yesterday (inclusive) and starts X days before that.
  • The last_X_hours time window ends at the previous hour (inclusive) and starts X hours before that.

Future windows of this type may be defined following this nomenclature, but for different units. Rules for the time window may vary slightly.

Special Time Windows

The following time_windows are considered to be special time windows.

  • campaign_to_date
  • flight_to_date

For reports with a datetime-typed time_field, the start_date and end_date columns that would normally be present, will be replaced by the interval column. Additionally, the following validation rules apply when a special time_window is chosen.

  • The results will have an interval column instead of start_date and end_date columns.
  • The time_rollup parameter must be set to all.
  • Any mention of the time_field for the report in the order parameter will be rejected.

Dimension Fields

Dimension fields describe an entity. The example reports provide dimension fields for campaign, and strategy entities. Dimension fields are used to group rows during aggregation in conjunction with the time field.

Metric Fields

Once the rows have been grouped. The metric fields are calculated based on the values of the group's underlying rows. These calculations are generally sums or averages. These fields are usually a numeric data type.

Please note that fees (eg: managed_service_fee, optimization_fee, platform_access_fee, and mm_total_fee), cost (eg: adserving_cost, adverification_cost, media_cost, and tota_ad_cost), and margin data are only available to users who have “edit margin” access.

Data Types

The id type allows any character except whitespace.

The datetime type may be filtered by dates, or datetimes in either of the following ISO 8601 based formats.

  • date - YYYY-MM-DD
  • datetime - YYYY-MM-DDThh:mi:ss

Year, month, and day are all 1-based. Hour, minute, and second are all 0-based. Valid hours are 0-23.

The dimension fields of the datetime type will always be output in the aforementioned datetime format. The output columns for the time field will be output in the same format, but without the separating 'T'.

Field Data Type Groupings

This documentation may refer to multiple data types via a group name. The following table details the group names.

GroupData Types
floatfloat, money, percent, ratio
integerinteger, count, rank
numericfloat and integer groups
datedatetime
stringstring, interval
idid
boolbool, boolean
Download OpenAPI description
Languages
Servers
Mock server
https://apidocs.mediamath.com/_mock/apis/reporting-api-v1/
https://api.mediamath.com/reporting/v1/std/

Data Retrieval

_

Operations

Metadata

_

Operations

Reports

_

Operations

App Transparency

Request

<!-- 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

See or query the Meta Endpoint for required fields and parameters.

curl -i -X GET \
  https://apidocs.mediamath.com/_mock/apis/reporting-api-v1/app_transparency

Responses

Body*/*
any

App Transparency Meta

Request

<!-- 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

Get App Transparency Meta

curl -i -X GET \
  https://apidocs.mediamath.com/_mock/apis/reporting-api-v1/app_transparency/meta

Responses

Body*/*
Descriptionstring

Standard performance metrics in campaign currency and broken out by our widest array of dimensions. Available in custom date ranges or intervals with the option to aggregate by day, week, or month.

Namestring

Performance Report in Campaign Currency

Typestring
URI_Datastring
Default "https://api.mediamath.com/reporting/v1/std/performance"
URI_Metastring
Default "https://api.mediamath.com/reporting/v1/std/performance/meta"
Versioninteger
currencystring

campaign currency

data_retentionstring
default_metricsArray of strings
structureobject
time_aggregationstring
time_rollupsArray of strings
time_windowsArray of strings
timezonestring

Audience Index

Request

<!-- 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

The Audience Index Report measures how your site visitors or media viewers compare to the internet population as a whole. It’s created by classifying your Audience (as defined by pixel, campaign, or strategy) cookies according to 3rd party segments, and then comparing the result to how the broader internet fits those segments. Use it to gain a better understanding of the demographics you are reaching.

API Endpoints

The Audience Index Report is divided into two different endpoints, one for media and one for pixels.

Campaign and strategy dimensions are available in:

$API_BASE/audience_index

The pixel dimension is available in:

$API_BASE/audience_index_pixel

Note: Pixels will only appear in the /audience_index_pixel report if they have at least 30 matches with all audience_name fields under a given audience_path. If a pixel has a small number of loads, it will most likely fail to meet this criteria.

Important Fields

Report-Specific Fields

audience_name - this field provides the name of the 3rd party segment that’s being matched. Best practice is to always include audience_name in your report, otherwise audience_index values will be aggregated across selected dimensions, and it won't be a sensical metric.

audience_path - segments are organized in hierarchies. For example, the “dentist” segment lives under the Demographic > Employment > Occupations > Health categories. The audience_path field shows this relationship. It is also used to help calculate the audience index, as shown below.

audience_index - this field is a relative value that describes the composition of your audience as compared to the internet average using segments provided by 3rd party data companies. If the index value for a given segment is 100, it means that your audience contains the same proportion of that demographic as the overall internet. If the value is greater than 100, your audience is over-indexed with that segment - that is, it consists of a greater portion of that segment than the general internet population does. If it’s less than 100, your audience is under-indexed. For example, a sporting goods retailer might hope that the customers they target with a golf supplies campaign would over-index on BlueKai’s “Interest/Sports/Golf” segment. If the index for this segment is 150, it means that the share of customers with an interest in golf is 50% higher in the retailer’s audience than it is in the total internet population.

NOTE: The audience_name dimension and audience_index metric are what make the Audience Index Report unique. In fact, the report would be useless without these fields, so always be sure to include them.

Time Fields

audience_index is available as an interval report. Currently only one time_window is supported: last_14_days. The only time_aggregation available is “all".

Updates

Data is updated weekly (Sunday). Check the Last-Modified date in the header for more specific timing.

Calculations

The audience_index field is calculated as follows:

  • x = unique customers in pixel pool, strategy media viewers, or campaign media viewers
  • y = x in segment / x in segment path
  • z = Total Internet in segment / Total Internet in segment path segment_index = y/z * 100

Example

Here’s how the Audience Index Report would help a youth apparel retailer determine whether they are successfully reaching the “age 18-24” age demographic.

  1. We look at the desired campaign/pixel/strategy and count total matched people against all of the 3rd party provider's age data: 400,000
  2. We look at the same campaign/pixel/strategy data for 18-24: 100,000
  3. So, 25% of your matched strategy, campaign or pixel data falls into the “age 18 to 24” segment
  4. We look at all cookies the 3rd party has matched to the broader internet for ALL of the age segments: 1,000,000
  5. We look at how many cookies the 3rd party has matched to the broader internet for people in the “age 18-24” segment: 200,000
  6. So, the 3rd party says that 20% of all internet cookies are between 18 and 24
  7. Therefore the audience_index is 125 (25/20)
Query
dimensionsstringrequired

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.

metricsstring

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 https://apidocs.mediamath.com/docs/api/e39ffafb5c6cb-report-meta.

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.

filterstringrequired
havingstring
time_rollupstringrequired
time_windowstringrequired
start_datestringrequired
end_datestring
Default "yesterday"
orderstring

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_limitinteger>= 1

Controls the maximum number of rows of data.

This parameter is required, if page_offset is one or greater.

Default 100
page_offsetinteger>= 0

Controls how many pages to skip.

precisioninteger[ 0 .. 8 ]

Controls how many digits to the right of the decimal places to display for float types.

Default 8
Headers
Cookiestringrequired

_

Default adama_session=<<sessionid>>
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). 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

Value"gzip,deflate"
If-Modified-Sincestring(date-time)

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.

curl -i -X GET \
  'https://apidocs.mediamath.com/_mock/apis/reporting-api-v1/audence_index?dimensions=string&end_date=yesterday&filter=string&having=string&metrics=string&order=string&page_limit=100&page_offset=0&precision=8&start_date=string&time_rollup=string&time_window=string' \
  -H 'Accept-Encoding:: gzip,deflate' \
  -H 'Cookie: adama_session=<<sessionid>>' \
  -H 'If-Modified-Since: 2019-08-24T14:15:22Z'

Responses

Audience Index Meta

Request

<!-- 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

Get Audience Index Meta

Headers
Cookiestringrequired

_

Default adama_session=<<sessionid>>
curl -i -X GET \
  https://apidocs.mediamath.com/_mock/apis/reporting-api-v1/audence_index/meta \
  -H 'Cookie: adama_session=<<sessionid>>'

Responses

Body*/*
Namestringrequired

This is the human-readable name of the report. It is not recognized by any API input.

Versionintegerrequired
Descriptionstring
URI_Datastring(uri)required
URI_Metastring(uri)required
Transitionobject
Deprecationobject
Typestring
currencystring

Provides information about the currency of the metrics fields typed as "money".

When set to "campaign currency", the currency varies from record to record. To determine the currency for a particular record, the campaign_currency_code dimensions field should be requested, if available for the report.

Any other value should be taken to be the currency for all records of the report.

data_retentionstring

Indicates how far back data is available. This can be a date, datetime, or time window as specified by the "time_window" and "Special Time Windows" sections of https://apidocs.mediamath.com/docs/api/a726318c29d15-reports-api. This property should be used very loosely. It may not be accurate. It is meant to give a general idea.

default_metricsArray of stringsrequired
structureobjectrequired
structure.​time_fieldobjectrequired
structure.​time_field.​property name*object(Field Description)additional property
structure.​dimensionsobjectrequired
structure.​dimensions.​property name*object(Field Description)additional property
structure.​metricsobjectrequired