ads¶

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 replaces two columns (spent, cpc) that used to be in the tenant local currency (EUR, $) with their corresponding spentMicros and bidMicros shown in micros unit.

This URL returns an ads performance report either in Excel or in CSV format depending on the Accept header. The report represents a timeseries breakdown of the performance of each ad which has had performance-related activity in the requested period.

If the Accept header is application/vnd.ms-excel;v=2 an Excel document is created, in .xlsx format.

If the Accept header is text/csv;v=2 a CSV document is created, in the standard RFC-4180 format. Fields with a comma, fields with a quote or newline, and fields which start with a space will be enclosed in quotes. Empty strings are not enclosed in quotes.

All dates and times are in the tenant timezone.

The Accept-Language header advertises the preferred client locales (language and region) for the report column names. Both language_REGION and language-REGION are supported formats, and can be assigned optional weights. If the preferred locale(s) are not available, a default one is used. Currently available locales are tenant-specific, and are listed below:

Scope	`console_ro` or `api_ro`
Accept	`application/vnd.ms-excel;v=2` or `text/csv;v=2`
Accept-Language	preferred locale (e.g., `nl-NL`, `fr-BE`, `en-CA`)

Tenant	Locales
Marktplaats	`nl_NL`
2dehands	`nl_BE`, `fr_BE`
Kijiji	`en_CA`, `fr_CA`

Parameters¶

Name	Type	Mandatory	Description
aggregate	string	no	Granularity of the timeseries breakdown. Possible values are: `daily`, `weekly`, `monthly`, and `yearly`. Default is `daily`.
startDate	string	yes	Start date of the report in `YYYY-MM-DD` format (inclusive). Tenant timezone is assumed.
endDate	string	yes	End date of the report in `YYYY-MM-DD` (inclusive). Tenant timezone is assumed.
includeDeleted	bool	no	Deleted ads are included/excluded. Default is `false`
query	string	no	Search phrase to filter on ad titles
fields	list of strings	no	Comma-separated list of column fields to include in the report. Possible values are listed in the `Field` column in the table below. By default all fields are included, and this may affect the speed of data generation.

Report Columns¶

Both the excel and the csv formats contain the following columns by default:

Name	Field	Version	Description
Date (Aggregated)	`date`	V1, V2	Date of the report row, grouped daily, weekly, monthly, or yearly. For daily and weekly aggregation the format is `YYYY-MM-DD`, for monthly aggregation - `YYYY-MM`, and for yearly - `YYYY`. All dates are in tenant timezone.
Ad ID	`adID`	V1, V2	ID of the ad
L1 Category	`L1Category`	V1, V2	Level 1 category name
L2 Category	`L2Category`	V1, V2	Level 2 category name
L3 Category	`L3Category`	V1, V2	Level 3 category name, if applicable
Title	`title`	V1, V2	Title of the ad
Start Date	`startDate`	V1, V2	Creation date of the ad
End Date	`endDate`	V1, V2	If the ad is deleted, deletion date of the ad
Bid (Micros)	`bidMicros`	V2	Bid of the ad for which performance metrics are calculated, in micros unit
Total Spent (Micros)	`spentMicros`	V2	Total amount spent for this ad, in micros unit
CPC	`CPC`	V1	CPC of the ad for which performance metrics are calculated, in local currency
Total spent	`spent`	V1	Total amount spent for this ad, in Local Currency
Clicks	`clicks`	V1, V2	Number of clicks that the ad received
Impressions	`impressions`	V1, V2	Number of impressions that the ad received
CTR	`viewCTR`	V1, V2	Click-through rate in %
URL clicks	`websiteClicks`	V1, V2	Number of URL clicks that the ad received
Emails	`emails`	V1, V2	Number of email events that the ad received
Engagement CTR	`engagementCTR`	V1, V2	Engagement conversion rate in %. Calculation: `(URL clicks + Emails) / Clicks`
Region	`region`	V1, V2	Region name, of the ad
Vendor ID	`vendorID`	V1, V2	Vendor ID of the ad
External URL	`externalURL`	V1, V2	The external website URL of the ad, if provided

V1¶

Scope	`console_ro` or `api_ro`
Accept	`application/vnd.ms-excel` or `text/csv`
Accept-Language	preferred locale (e.g., `nl-NL`, `fr-BE`, `en-CA`)

Examples¶

GET /api/sellside/metrics/ads?startDate=2018-01-01&endDate=2018-05-01&query=Interesting&aggregate=yearly&fields=date,adID,clicks,spentMicros
Accept: text/csv;v=2

HTTP/1.1 200 OK
Content-Type: text/csv;v=2
Content-Language: nl-NL
Content-Disposition: attachment; filename=mp-report-1-20180202-144340.csv
Datum (geaggregeerde),Advertentie nummer,Totaal besteed (Micros),Clicks

2018,7,0.3000000000,200000
2018,8,0.1500000000,3000000

GET /api/sellside/metrics/ads?startDate=2018-01-01&endDate=2018-05-01&query=Interesting
Accept: text/csv
Accept-Language: nl_NL, fr_NL;q=0.5

HTTP/1.1 200 OK
Content-Type: text/csv
Content-Language: nl-NL
Content-Disposition: attachment; filename=mp-report-1-20180202-144320.csv
Datum (geaggregeerde),Advertentie nummer,Groep,Rubriek,,Advertentietitel,Start,Eind,CPC (EUR),Totaal besteed (EUR),Clicks,Impressies,CTR (%),URL Clicks,E-mails,Engagement CTR (%),Vendor ID,Region
2018-02-02,7,Cd's en Dvd's,Cd's | Country en Western,,"Interesting title, what about ""quotes""",2018-02-02 11:48:52,,0.1500000000,0.3000000000,2,4,50.0000000000,0,0,0.0000000000,someVendor7,Utrecht
2018-02-03,8,Cd's en Dvd's,Cd's | Country en Western,,Interesting CD with country music,2018-02-02 11:48:52,,0.1500000000,0.3000000000,2,4,50.0000000000,0,0,0.0000000000,someVendor8,Amsterdam

GET /api/sellside/metrics/ads?startDate=2018-01-01&endDate=2018-05-01&query=Interesting&aggregate=monthly
Accept: text/csv

HTTP/1.1 200 OK
Content-Type: text/csv
Content-Language: nl-NL
Content-Disposition: attachment; filename=mp-report-1-20180202-144330.csv
Datum (geaggregeerde),Advertentie nummer,Groep,Rubriek,,Advertentietitel,Start,Eind,CPC (EUR),Totaal besteed (EUR),Clicks,Impressies,CTR (%),URL Clicks,E-mails,Engagement CTR (%),Vendor ID,Region
2018-02,7,Cd's en Dvd's,Cd's | Country en Western,,"Interesting title, what about ""quotes""",2018-02-02 11:48:52,,0.1500000000,0.3000000000,20,40,50.0000000000,0,0,0.0000000000,someVendor7,Utrecht
2018-02,8,Cd's en Dvd's,Cd's | Country en Western,,Interesting CD with country music,2018-02-02 11:48:52,,0.1500000000,0.3000000000,20,40,50.0000000000,0,0,0.0000000000,someVendor8,Amsterdam

GET /api/sellside/metrics/ads?startDate=2018-01-01&endDate=2018-05-01&query=Interesting&aggregate=yearly&fields=date,adID,clicks,spent
Accept: text/csv

HTTP/1.1 200 OK
Content-Type: text/csv
Content-Language: nl-NL
Content-Disposition: attachment; filename=mp-report-1-20180202-144340.csv
Datum (geaggregeerde),Advertentie nummer,Totaal besteed (EUR),Clicks
2018,7,0.3000000000,20
2018,8,0.1500000000,0.3000000000

Errors¶

GET /api/sellside/metrics/ads?startDate=2018-01-01&endDate=2018-05-01&query=Interesting
Accept: application/json

HTTP/1.1 415 Unsupported Media Type
[
    {
        "code": 2007,
        "text": "unsupported format",
        "msg": "unsupported media type",
        "field": "",
        "arg": ""
    }
]

GET /api/sellside/metrics/ads?startDate=2018-01-01
Accept: application/vnd.ms-excel

HTTP/1.1 400 Bad Request
[
    {
        "code": 2000,
        "text": "missing argument",
        "msg": "The field 'endDate' was missing",
        "field": "endDate",
        "arg": ""
    }
]

GET /api/sellside/metrics/ads?startDate=2018-07-01&endDate=2018-05-01
Accept: application/vnd.ms-excel

HTTP/1.1 400 Bad Request
[
    {
        "code": 2002,
        "text": "out of range",
        "msg": "The value of the field 'endDate' was out of range (< startDate)",
        "field": "endDate",
        "arg": "< startDate"
    }
]

GET /api/sellside/metrics/ads?startDate=2018-01-01&endDate=2018-05-01&fields=date,adID,clicks,spent
Accept: application/vnd.ms-excel;v=2

HTTP/1.1 400 Bad Request
[
    {
        "code": 2001,
        "text": "invalid argument",
        "msg": "The value of field 'fields' was invalid: unknown column 'spent'",
        "field": "fields",
        "arg": ""
    }
]