These are the three most common data queries:

• Summary metrics, for overall metric totals or averages
• Time-series data points, for metric totals divided into time intervals
• Dimension tables, for totals over different values of a chosen dimension

Summary Metrics

Time-Series Data points

Dimension Tables

Summary metrics

Use this endpoint to retrieve metric summaries for a given time period. This is the simplest of the data queries you can make to the Metamarkets API. With this query, depending on available data, you could:

• Find the total revenue earned last month
• See the click-through rate (CTR) for all auctions you won in the US
• Calculate the average eCPM for video inventory
• Build a business dashboard that shows total impressions, clicks, conversions, and spend on a rolling daily basis

The query is simple to use: specify the data view, the interval of interest, and the metrics you wish to retrieve. You can optionally add dimension filters to limit the data addressed by the query.

Limits

The column limit from your API pricing package limits the number of metrics you can retrieve with this query. If you require more data, you can make multiple queries and combine the results.

Endpoint

Make the query as follows:

Headers

Include the following required header (more on authentication):

Parameters

Include the following parameters:

The optional dimension filter objects take the following form:

Response

The response will consist of a single object, whose keys will be the metric IDs you requested, and whose values will be the summarized metric of interest. Note that while most metrics (eg revenue or impression counts) are summed, others (eg eCPM or average bid floor) will be averaged in the result.

Example request code

# Run 'gem install rest-client' before running this script.
require 'rest-client'; require 'json'; require 'pp'
url = "https://api.mmx.io/query/summary"

# Adjust this block for your token, data view and query setup.
token = ENV['TOKEN']  # Replace with your token, or set an environment variable.
body = {
  dataView: "demo_exchange/explore",
  metrics: ["imp_cnt"],
  interval: "P1W"
}
# (No edits required below here.)

# Prepare and make the request, and respond to any errors.
headers = {Authorization: "Bearer " + token, content_type: :json, accept: :json}
begin
  response = RestClient.post(url, body.to_json, headers)
rescue RestClient::Exception => e
  puts e.response
else
  # Display the successful result.
  pp JSON.load response
end

export TOKEN="your token here"
curl -v \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  -d '{
    "dataView": "demo_exchange/explore",
    "metrics": "[\"imp_cnt\"]",
    "interval": "P1W"}' \
  https://api.mmx.io/query/summary

# Run 'easy_install requests' before running this script.
import requests, os

# Adjust this block for your token, data view and query setup.
token = os.environ['TOKEN'] # Replace this, or set an environment variable.
url = "https://api.mmx.io/query/summary"
body = {
  "dataView": "demo_exchange/explore",
  "metrics": ["imp_cnt"],
  "interval": "P1W"
}

# Prepare and make the request.
headers = {"Authorization": "Bearer " + token}
response = requests.post(url, json=body, headers=headers)

# Respond to the result:
if response.status_code == 200:
  print response.json()
else:
  print response.text
  raise Exception, "API query failed"

// Adjust this block for your token, data view and query setup.
var token = "eyJ0eXAiOiJKV1Qi..."; // Replace this with your token.
var url = "https://api.mmx.io/query/summary";
var body = {
  "dataView": "demo_exchange/explore",
  "metrics": ["imp_cnt"],
  "interval": "P1W"
};
// (No edits required below here.)

// Prepare the request.
var request = new XMLHttpRequest();
request.open("POST", url);
request.setRequestHeader('Content-Type', 'application/json');
request.setRequestHeader('Authorization', 'Bearer ' + token);

// Respond to the result:
request.onreadystatechange = function (xhr) {
  if (this.readyState === 4) {
    xhr = this;
    if (xhr.status == 200) {
      response = JSON.parse(xhr.response);
      // Just print out the result for now:
      console.log(response);
    } else {
      console.log(xhr.response);
      throw "API query failed"
    }
  }
};

// Make the request:
request.send(JSON.stringify(body));

Example response

{
  "imp_cnt": 4659643350,
  "timerange": {
    "start": "2016-08-23T21:00:00.000Z",
    "end": "2016-08-30T21:00:00.000Z"
  }
}

Time-series data points

Use this endpoint to retrieve time-series data points for one or more metrics, for a given time period. Use it to produce a line chart. With this query, depending on available data, you could:

• Display a chart of weekly revenue from the last quarter
• Tabulate the average click-through rate (CTR) each day last week, for all auctions you won in the US
• Build a business dashboard that shows hourly charts of impressions, clicks, conversions, and spend on a rolling 24-hour basis

The query is simple to use: specify the data view, the interval of interest, and the metric you wish to retrieve. You can optionally add dimension filters to limit the data addressed by the query.

Limits

The row and column limits from your API pricing package apply, respectively, to the maximum number of points in time and maximum number of metrics you can retrieve with this query. If you require more data, you may make multiple queries and join the results together.

Endpoint

Make the query as follows:

Headers

Include the following required header (more on authentication):

Parameters

Include the following parameters:

The optional dimension filter objects take the following form:

Response

The response will consist of an array of data point objects, each of whose keys will be the metric IDs you requested, and whose values will be the summarized metric of interest. There will also be a “timerange” object, which will specify the start and end timestamps associated with each data point. As in the summary metrics query, note that while most metrics (eg revenue or impression counts) are summed, others (eg eCPM or average bid floor) will be averaged in the result.

Each data point object will have the following form:

Example request code

# Run 'gem install rest-client' before running this script.
require 'rest-client'; require 'json'; require 'pp'
url = "https://api.mmx.io/query/timeseries"

# Adjust this block for your token, data view and query setup.
token = ENV['TOKEN']  # Replace with your token, or set an environment variable.
body = {
  dataView: "demo_exchange/explore",
  metrics: ["imp_cnt"],
  interval: "P1W",
  granularity: "P1D"
}
# (No edits required below here.)

# Prepare and make the request, and respond to any errors.
headers = {Authorization: "Bearer " + token, content_type: :json, accept: :json}
begin
  response = RestClient.post(url, body.to_json, headers)
rescue RestClient::Exception => e
  puts e.response
else
  # Display the successful result.
  pp JSON.load response
end

export TOKEN="your token here"
curl -v \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  -d '{
    "dataView": "demo_exchange/explore",
    "metrics": "[\"imp_cnt\"]",
    "interval": "P1W",
    "granularity": "P1D"}' \
  https://api.mmx.io/query/timeseries 

# Run 'easy_install requests' before running this script.
import requests, os

# Adjust this block for your token, data view and query setup.
token = os.environ['TOKEN'] # Replace this, or set an environment variable.
url = "https://api.mmx.io/query/timeseries"
body = {
  "dataView": "demo_exchange/explore",
  "metrics": ["imp_cnt"],
  "interval": "P1W",
  "granularity": "P1D"
}

# Prepare and make the request.
headers = {"Authorization": "Bearer " + token}
response = requests.post(url, json=body, headers=headers)

# Respond to the result:
if response.status_code == 200:
  print response.json()
else:
  print response.text
  raise Exception, "API query failed"

// Adjust this block for your token, data view and query setup.
var token = "eyJ0eXAiOiJKV1Qi..."; // Replace this with your token.
var url = "https://api.mmx.io/query/timeseries";
var body = {
  "dataView": "demo_exchange/explore",
  "metrics": ["imp_cnt"],
  "interval": "P1W",
  "granularity": "P1D"
};
// (No edits required below here.)

// Prepare the request.
var request = new XMLHttpRequest();
request.open("POST", url);
request.setRequestHeader('Content-Type', 'application/json');
request.setRequestHeader('Authorization', 'Bearer ' + token);

// Respond to the result:
request.onreadystatechange = function (xhr) {
  if (this.readyState === 4) {
    xhr = this;
    if (xhr.status == 200) {
      response = JSON.parse(xhr.response);
      // Just print out the result for now:
      console.log(response);
    } else {
      console.log(xhr.response);
      throw "API query failed"
    }
  }
};

// Make the request:
request.send(JSON.stringify(body));

Example response

[
  {
    "imp_cnt": 65999790,
    "timerange": {
      "start": "2016-08-25T00:00:00.000Z",
      "end": "2016-08-26T00:00:00.000Z"
    }
  },
  {
    "imp_cnt": 603230520,
    "timerange": {
      "start": "2016-08-26T00:00:00.000Z",
      "end": "2016-08-27T00:00:00.000Z"
    }
  },
  {
    "imp_cnt": 629058990,
    "timerange": {
      "start": "2016-08-27T00:00:00.000Z",
      "end": "2016-08-28T00:00:00.000Z"
    }
  },
  {
    "imp_cnt": 648700950,
    "timerange": {
      "start": "2016-08-28T00:00:00.000Z",
      "end": "2016-08-29T00:00:00.000Z"
    }
  },
  {
    "imp_cnt": 653262345,
    "timerange": {
      "start": "2016-08-29T00:00:00.000Z",
      "end": "2016-08-30T00:00:00.000Z"
    }
  },
  {
    "imp_cnt": 731837025,
    "timerange": {
      "start": "2016-08-30T00:00:00.000Z",
      "end": "2016-08-31T00:00:00.000Z"
    }
  },
  {
    "imp_cnt": 718600395,
    "timerange": {
      "start": "2016-08-31T00:00:00.000Z",
      "end": "2016-09-01T00:00:00.000Z"
    }
  },
  {
    "imp_cnt": 608953335,
    "timerange": {
      "start": "2016-09-01T00:00:00.000Z",
      "end": "2016-09-02T00:00:00.000Z"
    }
  }
]

Dimension tables

Use this endpoint to retrieve a table whose rows are the different values of a specified dimension, and whose columns are the summary metrics for each dimension value. With this query, depending on available data, you could:

• Show your top publishers, and how much each made in the previous month
• Show the available media formats offered on your platform, and the average cost (eCPM) of each format
• For a particular app, list its most popular countries, and the number of impressions, clicks, and conversions seen in each country for that app

To use this query, choose a dimension (such as publishers, or countries), and a metric (such as revenue, or impressions). The dimension tables query will give you the top values of that dimension, sorted by their individual totals for that metric. (This would give you, for example, a table of the top publishers by revenue, or the top countries by impression counts.) As in the other data queries, you can add dimension filters to limit the data addressed by your query.

Limits

The row and column limits from your API pricing package apply, respectively, to the number of individual dimension values and the number of metrics that may be retrieved by this query. The metric used for sorting is not included in these limits.

Endpoint

Make the query as follows:

Headers

Include the following required header (more on authentication):

Parameters

Include the following parameters:

The optional dimension filter objects take the following form:

Response

The response will consist of an array of dimension value summary objects, each of whose keys will include a dimension value and totals for each of the values of ‘metrics’.

Each object in the returned list will have the following form:

Example request code

# Run 'gem install rest-client' before running this script.
require 'rest-client'; require 'json'; require 'pp'
url = "https://api.mmx.io/query/dimension"

# Adjust this block for your token, data view and query setup.
token = ENV['TOKEN']  # Replace with your token, or set an environment variable.
body = {
  dataView: "demo_exchange/explore",
  dimension: "pub_name",
  orderBy: "imp_cnt",
  metrics: ["imp_cnt"],
  interval: "P1W",
  limit: 10
}
# (No edits required below here.)

# Prepare and make the request, and respond to any errors.
headers = {Authorization: "Bearer " + token, content_type: :json, accept: :json}
begin
  response = RestClient.post(url, body.to_json, headers)
rescue RestClient::Exception => e
  puts e.response
else
  # Display the successful result.
  pp JSON.load response
end

export TOKEN="your token here"
curl -v \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  -d '{
    "dataView": "demo_exchange/explore",
    "dimension": "pub_name",
    "orderBy": "imp_cnt",
    "metrics": "[\"imp_cnt\"]",
    "interval": "P1W",
    "limit": 10}' \
  https://api.mmx.io/query/dimension 

# Run 'easy_install requests' before running this script.
import requests, os

# Adjust this block for your token, data view and query setup.
token = os.environ['TOKEN'] # Replace this, or set an environment variable.
url = "https://api.mmx.io/query/dimension"
body = {
  "dataView": "demo_exchange/explore",
  "dimension": "pub_name",
  "orderBy": "imp_cnt",
  "metrics": ["imp_cnt"],
  "interval": "P1W",
  "limit": 10
}

# Prepare and make the request.
headers = {"Authorization": "Bearer " + token}
response = requests.post(url, json=body, headers=headers)

# Respond to the result:
if response.status_code == 200:
  print response.json()
else:
  print response.text
  raise Exception, "API query failed"

// Adjust this block for your token, data view and query setup.
var token = "eyJ0eXAiOiJKV1Qi..."; // Replace this with your token.
var url = "https://api.mmx.io/query/dimension";
var body = {
  "dataView": "demo_exchange/explore",
  "dimension": "pub_name",
  "orderBy": "imp_cnt",
  "metrics": ["imp_cnt"],
  "interval": "P1W",
  "limit": 10
};
// (No edits required below here.)

// Prepare the request.
var request = new XMLHttpRequest();
request.open("POST", url);
request.setRequestHeader('Content-Type', 'application/json');
request.setRequestHeader('Authorization', 'Bearer ' + token);

// Respond to the result:
request.onreadystatechange = function (xhr) {
  if (this.readyState === 4) {
    xhr = this;
    if (xhr.status == 200) {
      response = JSON.parse(xhr.response);
      // Just print out the result for now:
      console.log(response);
    } else {
      console.log(xhr.response);
      throw "API query failed"
    }
  }
};

// Make the request:
request.send(JSON.stringify(body));

Example response

{
  "result": [
    {
      "pub_name": "Publisher I",
      "imp_cnt": 554631135
    },
    {
      "pub_name": "Publisher A",
      "imp_cnt": 394693410
    },
    {
      "pub_name": "Publisher T",
      "imp_cnt": 364389885
    },
    {
      "pub_name": "Publisher M",
      "imp_cnt": 295927875
    },
    {
      "pub_name": "Publisher J",
      "imp_cnt": 277444680
    },
    {
      "pub_name": "Publisher B",
      "imp_cnt": 246800475
    },
    {
      "pub_name": "Publisher O",
      "imp_cnt": 232579050
    },
    {
      "pub_name": "Publisher G",
      "imp_cnt": 227155185
    },
    {
      "pub_name": "Publisher R",
      "imp_cnt": 189745155
    },
    {
      "pub_name": "Publisher V",
      "imp_cnt": 188928585
    }
  ],
  "timerange": {
    "start": "2016-08-25T19:00:00.000Z",
    "end": "2016-09-01T19:00:00.000Z"
  }
}