data¶

Note

We introduce a new monetary unit of micros across our product, where one cent equals 10000 micros. One micro is 1-millionth of the local tenant currency. This will allow for a higher level of granularity when specifying the cost (per click).

We are substituting the current CPC values across the API with a bid value, and the actual (incurred) billed cost value - this to allow for better differentiation between the two. This split between bid and billed values is currently utilised for an experimental feature which adjusts the bid value for the quality of the traffic.

This new micros unit, as well as the distinction between bid and billed cost, are to become a core part of the product. We will gradually deprecate any fields with cents and local currency units across the API.

V2¶

V2 removes am:cpc from dimensions. It replaces am:spent, am:avgCPC, am:eCPC, am:sessionECPC metrics with their corresponding am:spentMicros, am:avgBidMicros, am:eSpentMicros, am:sessionESpentMicros. It replaces am:currentAdCPC enrichment with am:currentAdBidMicros.

Scope	`console_ro` or `api_ro`
Accept	`application/json`
Content-Type	`application/sellside.metrics.data-v2+json`

This URL returns the requested reporting metrics in a format described in the new Reporting API.

V1¶

Scope	`console_ro` or `api_ro`
Accept	`application/json`
Content-Type	`application/sellside.metrics.data-v1+json`

Query and Response¶

Query¶

The metrics query should be provided as a JSON object of type Metrics Request, which has these minimum requirements:

At least one valid entry in the Time Ranges field.
At least one valid entry in the Metrics field.

Here is a sample request with all top-level query fields expanded:

POST /api/sellside/metrics/data
Content-Type: application/sellside.metrics.data-v1+json
Accept: application/json

{
  "timeRanges": [{
    "period": "lastWeek"
  }],
  "aggregate": "daily",
  "dimensions": ["am:date", "am:adID"],
  "metrics": ["am:clicks", "am:impressions", "am:engagementCTR"],
  "sorts":[{"field":"date","direction":"asc"}],
  "filters": [{
      "field": "am:categoryID",
      "operator": "in",
      "value": [1235]
    },
    {
      "field": "am:regionID",
      "operator": "in",
      "value": [1,2,3,4]
    }
  ],
  "enrichment": [
    "am:currentAdTitle",
    "am:currentAdCategoryL1",
    "am:currentAdStartDate",
    "am:currentAdEndDate",
    "am:currentAdVendorID",
    "am:currentAdRegion",
    "am:currentAdImage"
  ],
  "limit": 5,
  "offset": 2
}

Metrics Request¶

The data model of the request has the following structure:

{
    "timeRanges": [<timeRange>, ...],
    "aggregate": <string>,
    "dimensions": [<string>, ...],
    "metrics": [<string>, ...],
    "sorts": [<sort>, ...],
    "filters": [<filter>, ...],
    "enrichment": [<string>, ...],
    "limit": <integer>,
    "offset": <integer>,
    "searchPhrase": <string>
}

Parameter	Description
`timeRanges`	Array of Time Ranges objects, separated by commas
`aggregate`	One of Time Aggregation string values
`dimensions`	Array of dimensions, separated by commas
`metrics`	Array of metrics, separated by commas. At least one element is mandatory
`sorts`	Array of Sort objects, separated by commas
`filters`	Array of Filters objects, separated by commas
`enrichment`	Array of ad enrichment fields, separated by commas
`limit`	Number of elements in the response, per time range. By default there is no limit
`offset`	Index of first row of the requested data (per time range), beginning with 0
`searchPhrase`	String to match against an ad title

Response¶

The response body of the API request is a JSON object of Metrics Response type. Here is a sample response for the sample request above.

{
  "data": [{
    "rows": [
      {
        "dimensions": ["2018-01-10 00:00:00", "4444"],
        "metrics": [11, 22, 0.634],
        "enrichment": [
          "Some title of ad #4444",
          "Category L1 description",
          "2016-02-10 10:15:15",
          "",
          "fsd23432",
          "City of Toronto",
          "https://mp.images.icas.io/api/v1/a6519ad0/images/cd/cd41d66f-ff99-4abc-8ea8-ef2131c92b8e?rule=r-726x726"
        ]
      },
      {
        "dimensions": ["2018-01-11 00:00:00", "5555"],
        "metrics": [9, 20, 0.244],
        "enrichment": [
          "Some title of ad #5555",
          "Category L1 description",
          "2016-05-11 09:10:15",
          "2016-07-11 06:10:10",
          "123425d",
          "Canada",
          "https://mp.images.icas.io/api/v1/a6519ad0/images/66/6628f902-6c59-4c71-bf37-8d127a53e277?rule=r-726x726"
        ]
      },
      {
        "dimensions": ["2018-01-12 00:00:00", "4444"],
        "metrics": [34, 67, 0.252],
        "enrichment": [
          "Some title of ad #4444",
          "Category L1 description",
          "2016-02-10 10:15:15",
          "",
          "fsd23432",
          "City of Toronto",
          "https://mp.images.icas.io/api/v1/a6519ad0/images/fb/fba866a4-ff7b-4134-bb58-c12cfa02649e?rule=r-726x726"
        ]
      },
      {
        "dimensions": ["2018-01-13 00:00:00", "5555"],
        "metrics": [55, 61, 0.312],
        "enrichment": [
          "Some title of ad #5555",
          "Category L1 description",
          "2016-05-11 09:10:15",
          "2016-07-11 06:10:10",
          "123425d",
          "Canada",
          "https://mp.images.icas.io/api/v1/a6519ad0/images/d7/d7d25c7b-4494-491c-980a-7f6cdde14c21?rule=r-726x726"
        ]
      },
      {
        "dimensions": ["2018-01-14 00:00:00", "5555"],
        "metrics": [43, 76, 0.543]
        "enrichment": [
          "Some title of ad #5555",
          "Category L1 description",
          "2016-05-11 09:10:15",
          "2016-07-11 06:10:10",
          "123425d",
          "Canada",
          "https://mp.images.icas.io/api/v1/a6519ad0/images/f1/f16052a4-c08a-480a-855e-cbc4cd3a8e59?rule=r-726x726",

        ]
      }
    ],
    "count": 5
  }
]

Metrics Response¶

The data model of the response has the following structure:

{
    "data": [
        {
            "rows": [
                {
                    "dimensions": [<string>, ... ],
                    "metrics": [ <number>, ...]
                    "enrichment": [<string>, ...]
                }
            , ...],
        "count": <integer>
        }
    ]
}

Parameter	Description
`rows`	Array of `dimensions`, `metrics` and `enrichment` values. Each element is one row of a response
`dimensions`	Array of dimension values for this row, in string format
`metrics`	Array of metric values for this row, in number format
`enrichment`	Array of enrichment values for this row, in string format. Valid only if `am:adID` is in the requested dimensions
`count`	Actual number of rows returned

The data field contains an array of objects, one for each of the requested Time Ranges. It is important to remember that the order in which the metrics, dimensions, and enrichment fields are requested is the same order in which they are listed in the response. The order of the objects in the rows array is not guaranteed to be deterministic unless explicit Sorting <Sorts> is used.

Examples¶

To understand the concept of dimensions and metrics, some examples of request and response are provided below, gradually increasing in complexity. In addition, a “tabular” view of the response is provided; in our experience it makes it easier to grasp these concepts.

Example 1:¶

Get all clicks and impressions for category 1234 for the previous week:

POST /api/sellside/metrics/data
Content-Type: application/sellside.metrics.data-v1+json
Accept: application/json
{
    "timeRanges": [{
        "period": "lastWeek"
    }],
    "dimensions": [],
    "metrics": ["am:clicks", "am:impressions"],
    "filters": [{
        "field": "am:categoryID",
        "operator": "in",
        "value": [1234]
    }]
}

{
    "data": [{
        "rows": [{
            "dimensions": [],
            "metrics": [1483, 36623] // 1483 clicks, 36623 impressions
        }],
    "count": 1
    }]
}

am:clicks	am:impressions
1483	36623

Example 2:¶

Get all clicks and impressions for categories 1234 and 5678 for the previous week, but split performance metrics per category:

POST /api/sellside/metrics/data
Content-Type: application/sellside.metrics.data-v1+json
Accept: application/json
{
    "timeRanges": [{
        "period": "lastWeek"
    }],
    "dimensions": ["am:categoryID"],
    "metrics": ["am:clicks", "am:impressions"],
    "filters": [{
        "field": "am:categoryID",
        "operator": "in",
        "value": [1234, 5678]
    }]
}

{
    "data": [{
        "rows": [{
            "dimensions": ["1234"],
            "metrics": [200, 400] // 200 clicks, 400 impressions for category "1234"
        },
        {
            "dimensions": ["5678"],
            "metrics": [300, 400]
        }],
    "count": 2
    }]
}

am:categoryID	am:clicks	am:impressions
1234	200	400
5678	300	400

Example 3:¶

Get all clicks and impressions for categories 1234 and 5678 for the previous week, but split performance metrics per day and category. In addition, sort by date in ascending direction:

POST /api/sellside/metrics/data
Content-Type: application/sellside.metrics.data-v1+json
Accept: application/json
{
    "timeRanges": [{
        "period": "lastWeek"
    }],
    "dimensions": ["am:date", "am:categoryID"],
    "metrics": ["am:clicks", "am:impressions"],
    "filters": [{
        "field": "am:categoryID",
        "operator": "in",
        "value": [1234, 5678]
    }],
    "sorts":[
    {
        "field":"am:date",
        "direction":"asc"
    }],
}

{
    "data": [{
        "rows": [{
            "dimensions": ["2018-12-08 00:00:00", "1234"],
            "metrics": [11, 12]
        },
        {
            "dimensions": ["2018-12-08 00:00:00", "5678"],
            "metrics": [9, 20]
        },
        {
            "dimensions": ["2018-12-09 00:00:00", "1234"],
            "metrics": [34, 67]
        },
                    {
            "dimensions": ["2018-12-09 00:00:00", "5678"],
            "metrics": [19, 20]
        },
        ...
        {
            "dimensions": ["2018-12-14 00:00:00", "1234"],
            "metrics": [12, 90]
        },
        {
            "dimensions": ["2018-12-14 00:00:00", "5678"],
            "metrics": [43, 76]
        }],
    "count": 54
    }]
}

am:date	am:categoryID	am:clicks	am:impressions
2018-12-08 00:00:00	1234	11	12
2018-12-08 00:00:00	5678	9	20
2018-12-09 00:00:00	1234	34	67
2018-12-09 00:00:00	5678	19	20
…
2018-12-14 00:00:00	1234	12	90
2018-12-14 00:00:00	5678	43	76

Example 4:¶

Get all clicks, and average CPC for categories 1234 and 5678 for the previous week, but split performance metrics per ad ID. In addition, enrich the response rows with current ad title and vendorID. Limit to 3 results:

POST /api/sellside/metrics/data
Content-Type: application/sellside.metrics.data-v1+json
Accept: application/json
{
    "timeRanges": [{
        "period": "lastWeek"
    }],
    "dimensions": ["am:adID"],
    "metrics": ["am:clicks", "am:avgCPC"],
    "filters": [{
            "field": "am:categoryID",
            "operator": "in",
            "value": [1234, 5678]
    }],
    "enrichment":["am:currentAdTitle", "am:currentAdVendorID"]
    "limit": 3
}

{
    "data": [{
        "rows": [{
            "dimensions": ["11111"],
            "metrics": [11, 4.5],
            "enrichment": [
                "Ad title #11111",
                "vendor11111"
            ]
        },
        {
            "dimensions": ["33333"],
            "metrics": [9, 3.0],
            "enrichment": [
                "Ad title #33333",
                "vendor33333"
            ]
        },
        {
            "dimensions": ["22222"],
            "metrics": [34,  2.3],
                "enrichment": [
                "Ad title #33333",
                "vendor33333"
            ]
        }],
    "count": 3
    }]
}

am:adID	am:clicks	am:avgCPC	am:currentAdTitle	am:currentAdVendorID
11111	11	4.5	Ad title #11111	vendor11111
33333	9	3.0	Ad title #33333	vendor33333
22222	34	2.3	Ad title #22222	vendor22222

Example 5:¶

Get all clicks, and average spent micros for categories 1234 and 5678 for the previous week, but split performance metrics per ad ID. In addition, enrich the response rows with current ad title and vendorID. Limit to 3 results:

POST /api/sellside/metrics/data
Content-Type: application/sellside.metrics.data-v2+json
Accept: application/json
{
    "timeRanges": [{
        "period": "lastWeek"
    }],
    "dimensions": ["am:adID"],
    "metrics": ["am:clicks", "am:avgSpentMicros"],
    "filters": [{
            "field": "am:categoryID",
            "operator": "in",
            "value": [1234, 5678]
    }],
    "enrichment":["am:currentAdTitle", "am:currentAdVendorID"]
    "limit": 3
}

{
    "data": [{
        "rows": [{
            "dimensions": ["11111"],
            "metrics": [11, 45000.0],
            "enrichment": [
                "Ad title #11111",
                "vendor11111"
            ]
        },
        {
            "dimensions": ["33333"],
            "metrics": [9, 3.0],
            "enrichment": [
                "Ad title #33333",
                "vendor33333"
            ]
        },
        {
            "dimensions": ["22222"],
            "metrics": [34,  2.3],
                "enrichment": [
                "Ad title #33333",
                "vendor33333"
            ]
        }],
    "count": 3
    }]
}

am:adID	am:clicks	am:avgSpentMicros	am:currentAdTitle	am:currentAdVendorID
11111	11	45000.0	Ad title #11111	vendor11111
33333	9	30000.0	Ad title #33333	vendor33333
22222	34	23000.0	Ad title #22222	vendor22222

Final remarks:¶

In the SQL note, the enrichment fields can be seen as a left outer join operation.

The reporting numbers may slightly differ (±0.005%) from the final billing values, due to the nature of the system where we store the reporting data.

The API does not allow to filter on the current status of ads, which means the reporting numbers apply for all ads, including those that have been deleted in the meantime. Depending on API clients feedback, we might revisit the API and add support for such filtering in the future.

Errors¶

Each error contains a code and text attributes providing a numeric error code and a simple English error message. An error may contain a field attribute describing the field where the error occurred and an additonal arg attribute further specifying the error.

Field	Code	Message	Description
entire response object	1000	internal error	Failed to execute query
entire request object	1005	invalid json	Could not parse request data
`am:date`	2000	missing argument	The field ‘aggregate’ was missing
`am:metrics`	2000	missing argument	The field ‘metrics’ was missing
any non-allowed field	2001	invalid argument	The value of field ‘dimensions:[am:wrongDimension]’ was invalid