Data Queries

Most of the time, you will be using one of the three basic data queries as part of our API. There are also several metadata and setup queries (for getting information about your schema or about your API usage), but the primary calls return data itself.

These are the three most common data queries:

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:

HTTP method Query Endpoint Base URL
POST /query/summary https://api.mmx.io/

Headers

Include the following required header (more on authentication):

Key Value
Authorization Bearer <API key>
Content-Type application/json

Parameters

Include the following parameters:

Parameter Type Description
dataView String (required) The data view ID to query
interval ISO 8601 time interval (required) The data and time interval to query (learn more)
metrics Array of strings (required) The IDs of individual metrics you wish to query. Most metrics will be totalled; certain others will be averaged, based on the data view’s configuration
dimensionFilters Array of dimension filter objects (optional) Filters limiting the query to specific dimension values (see below). You may combine multiple dimension filter objects, all of which must apply (they are ANDed together)

The optional dimension filter objects take the following form:

Parameter Type Description
dimension String (required) The Dimension ID for use in this dimension filter
exclude Boolean (optional) Whether data must match the filter values (default when omitted, or when false) or not match the filter values (when true)
values Array of strings (required) Individual dimension values, any of which may match (exclude: "false"), or all of which must not match (exclude: "true") for data to be included in the query

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.

Property Type Description
<metric_id> Number The summarized value for this particular metric, identified by its ID. There will be one metric ID and value per metric ID specified in the request.

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:

HTTP method Query Endpoint Base URL
POST /query/timeseries https://api.mmx.io/

Headers

Include the following required header (more on authentication):

Key Value
Authorization Bearer <API key>
Content-Type application/json

Parameters

Include the following parameters:

Parameter Type Description
dataView String (required) The data view ID to query
interval ISO 8601 time interval (required) The data and time interval to query (learn more)
granularity String (required) The spacing between data points in the time-series. Must be PT1H (for hourly data points) or P1D (for daily data points). Certain customers may have minutely granularity available, with PT1M.
metrics Array of strings (required) The IDs of individual metrics you wish to query. Most metrics will be totalled; certain others will be averaged, based on the data view’s configuration (see metrics available to you)
dimensionFilters Array of dimension filter objects (optional) Filters limiting the query to specific dimension values (see below). You may combine multiple dimension filter objects, all of which must apply (they are ANDed together)

The optional dimension filter objects take the following form:

Parameter Type Description
dimension String (required) The Dimension ID for use in this dimension filter
exclude Boolean (optional) Whether data must match the filter values (default when omitted, or when false) or not match the filter values (when true)
values Array of strings (required) Individual dimension values, any of which may match (exclude: "false"), or all of which must not match (exclude: "true") for data to be included in the query

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:

Property Type Description
<metric_id> Number The summarized value for this particular metric and particular data point, identified by its ID. There will be one metric ID and value per metric ID specified in the request
timerange Object Contains the start and end timestamps associated with this data point object. The above metric summaries will be for data between the start and end of this range

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:

HTTP method Query Endpoint Base URL
POST /query/dimension https://api.mmx.io/

Headers

Include the following required header (more on authentication):

Key Value
Authorization Bearer <API key>
Content-Type application/json

Parameters

Include the following parameters:

Parameter Type Description
dataView String (required) The data view ID to query
dimension String (required) The dimension ID for the rows of the table
orderBy String (required) The metric ID used to sort and return the top values for the dimension of interest. (This will not, by default, be added to metrics, so include it there if you wish to see the values)
metrics Array of strings (required) The IDs of the metrics you wish to query. Most metrics will be totalled; certain others will be averaged, based on the data view’s configuration (see metrics available to you). Excluding this parameter (or providing an empty list) will simply return the top dimension values
interval ISO 8601 time interval (required) The data and time interval to query (learn more)
limit Integer (optional) The maximum number of top values to retrieve. If excluded, this will default to 20. Separate limits apply based on the type of API package you have purchased
dimensionFilters Array of dimension filter objects (optional) Filters limiting the query to specific dimension values (see below). You may combine multiple dimension filter objects, all of which must apply (they are ANDed together)

The optional dimension filter objects take the following form:

Parameter Type Description
dimension String (required) The Dimension ID for use in this dimension filter
exclude Boolean (optional) Whether data must match the filter values (default when omitted, or when false) or not match the filter values (when true)
values Array of strings (required) Individual dimension values, any of which may match (exclude: "false"), or all of which must not match (exclude: "true") for data to be included in the query

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:

Property Type Description
<dimension_id> String The value of the dimension that is summarized by this object
<metric_id> Number The summarized value for this particular dimension value. For each dimension value, there will be one metric ID and value per metric ID specified in the request

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"
  }
}