See first: Customizing an API Request

In this more detailed guide, we'll cover:

R2 is MNTN’s self-service reporting platform. R2 allows MNTN to rapidly build reports for customers. It gives customers a self-service method of customizing those reports and also provides an Application Programming Interface (API) to access data programmatically so that customers and partners can easily move data into their own reporting infrastructure.

The R2 Application Programming Interface (API) is an HTTP request service to retrieve data from R2 Data Service (R2DS). Data can be returned
in four formats, including JSON, CSV, Excel and Human Readable. Requests are in the form of an HTTP request.

There are two types of requests that can be made to the R2 API—a data request and a list request. A data request returns the data you ask for. The list request returns a list of the data that can be requested.

The R2 API has a number of different arguments to retrieve data. A sample request looks like the following:

To make a data request, the url in your request should start with https://api.mountain.com/ apidata and then append the parameters for the request. The following parameters are supported, beginning with the mandatory parameters.

The key is a unique encrypted key that is assigned to an advertiser. The key is required to issue a valid request to R2 and will only allow access to each advertiser’s specific data.

You can retrieve your key in the Account Settings page of the MNTN user interface.

This is the begin time to get data for. Dates are specified in YYYY-MM-DD format. Year first, then month and then day. You can also specify time in the following way. YYYY-MM-DDTHH:MM:SS. That is year first, then month, day, the letter T, hour, min and seconds.

Alternatively, you can utilize the time shortcuts outlined below. Note that all time shortcuts are T-1 and will not provide the current day’s data in the final output:

You don’t need to specify an ‘End’ time argument when you use a time shortcut. Here’s an example of the earlier request specifying the current week of data.

This is the end time to get data for. End times are specified in the same format as begin times and are inclusive of the time specified. For example, specifying an end time of 2018-01-31 will include data for that date. The End parameter is ignored when a begin time shortcut, such as MTD is used.

The data parameter is a comma separated list of Table.Column arguments that you want to receive data back from the request. You can access a full list of available tables (also referred to as Dimensions) and columns (also referred to as Metrics) using the list request referenced in R2 API List Request.

For example, if you wanted to receive a list of impressions, visits, and conversions for an advertiser, the data parameter would be:

To receive the same data but for a campaign the data parameter would be:

Note that when generating a data request, you can only pull data from a single table (or dimension).

The Format argument specifies how you want the results of your request returned. Available formats include:

The default format returned from R2 is Human readable.

JSON is the most commonly requested format for API access.

The AllowNull parameter allows you to control whether you want to know whether there is no data for a given period of time. The default behavior is to turn null data to zero’s or blanks. If you want nulls, which would exist when there was no data for a specified period of time, set AllowNull=true

The filter argument provides a way to constrain results. For example, if you’re querying the campaign table you may not want every campaign. You can follow the below format to include only a single campaign in your results.

If you want to filter by multiple items, you can follow the below format to include multiple campaigns in your results.

The FormatData argument specifies that data should be returned formatted to the Locale of the advertiser. The formatting is for currency and time. The default behavior is to format but if you can specify FormatData=False to have data returned without formatting.

The FullName argument returns Table.Column names in the JSON format if FullName=true. If FullName is false or not specified, only the column name is returned in the JSON response.

The Limit argument specifies a maximum number of rows to return.

Note that the limit for all CSV or excel exports is 65,535 rows of data. Beyond that limit, the report will not export.

The Offset argument specifies a starting point for the number of rows to return.

The Sort argument specifies what column you want to sort results on and in what direction. The default is to sort by Day. If no Day column is specified, the first column that is specified in the Data argument will sort in ascending order.

To specify a different column to sort, or to sort in descending order, you can specify in the Sort arguement:

Ascending is the default sort order. To sort by impressions in ascending order you would not need to specify.

The Sum argument specifies what column to total results on if you want to get back one row rather than a row per day. For example if you wanted to receive the totals for each campaign by campaign name, you would specify:

R2 allows you to specify formulas in the list of Table.Column’s you would like to request. A number of metrics in the list of available data are predefined formulas, but you can also define your own formula on the fly. An example of a predefined formula is VisitRate. VisitRate is Visits divided by Users Reached. To specify a formula on the fly, you can start the Table.Column specification with an equal ‘=’ sign. Here’s an example that both queries the predefined VisitRate but also calculated it on the fly.

The result of that request is the same but one thing you’ll see is the resulting numbers
are formatted differently. The Advertiser.VisitRate is formatted as a percentage while
the formula defaults to numeric formatting. You can optionally specify the formatting
and other metadata as part of specifying a formula, by using the Formula function. This function is also specified using the equal sign but it also supports one mandatory argument and three optional arguments. The mandatory argument is content, where you specify

the formula. The three optional arguments are Format, Name.

The Content argument is always required when using the Formula function and is where the formula expression is specified. All arguments are specified with the name of the argument and colon ‘:’ separator. For example, Content:Advertiser.Visits / Advertiser. UsersReached. Each argument is separated with a comma.

The Format argument tells R2 how you would like the results formatted. The following formats are supported:

The Name argument specifies the name to show when returning data in Human, Excel and CSV formats.

R2 has a /list request, which returns the data available in R2. An example list request is:

That will return a list of all Tables (or Dimensions) and Columns (or Metrics) you can request data from, along with descriptions. If you wanted to receive back a list of columns for specific tables, you can specify a table argument. The following example shows how to get a list of columns available for the Advertiser table.

Note that when generating a data request, you can only request from a single table.

R2 has three types of tables, that each return a different type of data. The table types include:

Info tables provide information on objects that have been created in the MNTN User Interface. Info tables generally end with Info in their name. For example, you can ask for the impressions on a campaign by specifying CampaignGroup.Impressions, which is a Summary table. To get the name of that campaign you can request CampaignGroupInfo.Name.

Info tables include:

Detail tables provide log level access to data. For example, if you want a list of the conversions that were generated for a campaign you can request data from the Conversions table, which is a detailed table.

Detail tables include:

Summary tables primarily contain numeric data like Visits, impressions and conversions. They also have a significant number of calculated columns like visit rate, ROAS, eCPA and others. The most commonly used summary tables are Advertiser, CampaignGroup and CreativeGroup.

Summary tables include: