API Introduction
The Metamarkets API is simple, so you don’t have a lot to learn before you can be productive. Start on this page to understand some high-level concepts and make your first request.
Concepts
The Metamarkets API is a stateless, HTTP API with JSON-formatted requests and responses. Each request requires an authentication token, and a correctly-formatted request body. Some key information you need about these calls is in this section.
HTTP connection details
API requests are made using HTTPS to URLs that begin with https://api.mmx.io. SSL is required. All API calls use the HTTP POST method.
Data formats and compression
The body of your API request should be a single JSON object with all required parameters. The examples in this guide format the JSON with generous spacing; that is not required in your requests.
We optionally support compressed requests and responses using the Content-Encoding
and Accept-Encoding headers with the ‘gzip’ format.
For example:
Content-Encoding: gzip Accept-Encoding: gzip
This can increase the efficiency of your data transfers. It does not affect pricing.
Terminology
Each query involves several types of data object. These are:
| Parameter | Description |
|---|---|
| A data view | This is the data view (which includes a data source, and a schema) that you will query. Most customers have access to just a few data views. For example, if you are at an advertising exchange, you may have one data view for auctions data, and another for bids data. |
| One or more metrics | These are values which we will sum or average to give you information about your data. Metrics are identified by unique metric IDs, which are defined as part of the data view. Some example metric IDs are revenue, bids, impressions, or clicks. |
| One or more dimensions | These describe your data in more detail. Dimension are identified by unique dimension IDs, which are defined as part of your data view. Some example dimension IDs for a particular data view are app, site, ad_size, country, publisher, and advertiser. |
| An interval | This defines the period of time to query. Events within that interval will be summarized in the response supply in your request. Interval specifications follow the ISO 8601 standard. See detailed information in the API reference. |
Getting an API token
All Metamarkets API requests require authentication with an API token. If you have a Metamarkets account and have purchased API access, visit your API setup page to customize the documentation and data access. We don’t currently offer test access, but plan to in the future. (Talk to your account manager for details.)
Tokens are JSON Web Tokens (JWT). Present them as an Authorization header as follows:
Authorization: Bearer <token>
We offer a wide range of capabilities and control via API tokens. You can even generate new tokens programmatically if required. See the API reference docs for more details.
Versioning
You will get the latest production version of the API by default. However, you can, if you wish, specify the particular version to use. See the API reference for more details.
Errors
Successful API requests will receive an HTTP 200 response status code. Invalid requests will receive an HTTP 4xx response status code, and errors on our end will have an HTTP 5xx response status code. All errors with a 4xx or 5xx response code will include a JSON error message response of the form:
{ "message": "More detailed description of the problem" }
See the API Errors Reference for detailed information about possible error codes and what they may mean.
Rate limits
Our API has limits on the rates and complexity of permitted requests. These vary depending on your account type and status. Contact your account manager for detailed information about rate limits and what to do if you wish to increase your API usage beyond an applicable limit. (We will be adjusting these during the beta period.)
Your first request
Now that we have introduced you to the concepts, let’s go through your first call to the Metamarkets API. We will request a single metric total. For this example, we will be working with the data view demoexchange/explore, which is a Metamarkets-internal synthetic data source. (You will need to use your own data view.)
The query choice means our HTTP method and route will be:
POST https://api.mmx.io/query/summary
It also gives us a parameter for the body:
dataView: "demoexchange/explore"
First, get an API key. You need to be a Metamarkets user (and a direct customer). Visit the API configuration page within our product, and generate a new token. You will present this token as an Authorization header.
This gives us a header (replace the eyJ0e... portion with your own key):
Authorization: Bearer eyJ0eXAiOiJKV1Qi...
While many programming toolkits will add a Content-Type header by default, if you are hand-rolling your request you will also need to add:
Content-Type: application/json
Next, we will choose the period of time we wish to query. This determines the ‘interval’ parameter. We will make a query over the most recent week of data. This gives us a parameter for the body:
interval: "P1W"
We choose to retrieve a count for the impressions metric, which gives us the final parameter for the body. We will provide a single item for the list of desired metrics:
metrics: ["imp_cnt"]
That’s it! Our final JSON body looks like this:
{
"dataView": "demoexchange/explore",
"metrics": ["imp_cnt"],
"interval": "P1W"
}
When we make the call, we get back the following response:
{
"imp_cnt": 1602465,
"timerange": {
"start": "2016-05-18T20:00:00.000Z",
"end": "2016-05-25T20:00:00.000Z"
}
}
This gives us the answer we wanted: there were 1,602,465 impressions for the week beginning May 18, 2016. You’ve now completed your first Metamarkets API request!