Skip to main content

​
Introduction

The placement category endpoint provides transparency on which categories of domains your ads are being displayed on, as well provides visibility into the number of displays, clicks, and sales that have occurred via a given publisher.

​
How It Works

A single domain can have several categories associated with it because the single page categorization is grouped at the domain level. Also, each individual page can hold several categories. For example, a news website could have pages linked to business, sports, and entertainment.
How Hits are Normalized Into DisplaysOn examplenewssite.com there are 50 hits on the following categories:
  • News 10
  • Travel 15
  • Entertainment 25
Then take the ratio of each category compared to the total number of hits on examplesnewssite.com.
  • News 0.2
  • Travel 0.3
  • Entertainment 0.5
Suppose there are 20 displays on examplenewssite.com and users clicked through 10 times, apply those ratios to both displays and clicks to get accurate category level data.
  • News 4 displays / 2 clicks
  • Travel 6 displays / 3 clicks
  • Entertainment 10 displays / 5 clicks

​
Endpoint

A POST request returns a report on categories based on the query. The query returns a predefined data set that includes displays, clicks, 30 day post click sales, and 1 day post view sales.
Required AttributesThere are 4 required attributes when making a call.
For additional fields see the Attributes table below.
  • startDate
  • endDate
  • advertiserIds
  • format
Request example:
JSON
{
    "data": {
        "startDate": "2020-01-01",
        "endDate": "2020-01-02", 
        "advertiserIds": [
            "123",
            "456",
            "789"
        ],
        "category": "News"
        "domain": "example.com",
        "timezone": "UTC",
        "format": "json",
    }
}
The response is a file dictated by the “format” field in the request. This could be returned in JSON, XML, CSV, or XLS. Response example:
JSON
[
    {
       "advertiserId": 123,
       "category": "News",
       "domain": "example.com",
       "displays": 42,
       "clicks": 12,
       "salesPc30d":5,
	"salesPv1d": 1
    },
    {
       "advertiserId": 456,
       "category": "News",
       "domain": "example.com",
       "displays": 42,
       "clicks": 12,
       "salesPc30d":5,
	"salesPv1d": 1
    },
    {
       "advertiserId": 789,
       "category": "News",
       "domain": "example.com",
       "displays": 42,,
       "clicks": 12,
       "salesPc30d":5,
	"salesPv1d": 1
    }
]
Limitations
  • This reporting is on publisher categories only.
  • This display data is for the web environment only and does not support app display data.
  • URL domains that fall under the category “Unknown” do not fall into any category.
  • URL domains “Undisclosed” are not permitted to be displayed, and will appear as empty strings.
  • If a domain has no category, then number of displays will be reported in the “Unknown” category. Additionally, if a domain has less category hits than displays, we do not correct the number of hits, and report the missing displays in the “Unknown” category.

​
Attributes

Field

Type

Required

Default Value

Description

startDate

DateTime

Yes

Start of the report in YY-MM-DD format

endDate

DateTime

Yes

End of the report in YY-MM-DD format

advertiserIds

string

Yes

Comma separated list of Advertiser IDs in an array

adsetId

string

No

null

Report only on the specified adset Id

category

string

No

Report only on the specified category

domain

string

No

Report only on the specified domain

shoudlDisplayDomainDimension

boolean

No

true

Specify if the domain dimension is displayed in the report

timezone

Timezone

No

UTC

Timezone used for dates

format

string

Yes

CSV

Format of the report: JSON, XML, CSV, XLS

​
Errors and Warnings

API users must be authenticated in order to make calls to the category endpoint.
For more information on authentication, see our Authentication guide.

​
Insufficient Permission

JSON
"errors": [{
  "traceId": "56ed4096-f96a-4944-8881-05468efe0ec9",
  "type": "access-control",
  "code": "insufficient-advertiser-permissions",
  "instance": "/advertisers/placements/report",
  "title": "Insufficient advertisers permissions",
  "detail": "You do not have the rights to report on these advertisers.",
}]

​
Missing Required Fields

There are 4 required fields when making a call: startDate, endDate, advertiserIds, and format.
JSON
"errors": [{
  "traceId": "56ed4096-f96a-4944-8881-05468efe0ec9",
  "type": "validation",
  "code": "required-field",
  "instance": "/advertisers/placements/report",
  "title": "<field> is required.",
}]

​
Invalid Format

Format must be in CSV, XML, XLS, or JSON.
JSON
"errors": [{
  "traceId": "56ed4096-f96a-4944-8881-05468efe0ec9",
  "type": "validation",
  "code": "invalid-format",
  "instance": "/advertisers/placements/report",
  "title": "<field> must be in list of required values",
  "detail": "<field> must be one of 'csv', 'xml', 'excel' or 'json'. Value: '<value>'." ,
}]

​
Invalid Date Range 

Date ranges are required and must have a valid start and end date.
JSON
"errors": [{
  "traceId": "56ed4096-f96a-4944-8881-05468efe0ec9",
  "type": "validation",
  "code": "invalid-date-range",
  "instance": "/advertisers/placements/report",
  "title": "Invalid date range",
  "detail": "The 'startDate' can not be after 'endDate'.",
}]

​
Invalid Time Zone 

The default time zone for requests is UTC. See this page for more information on supported time zones.
JSON
"errors": [{
    "traceId": "56ed4096-f96a-4944-8881-05468efe0ec9",
    "type": "validation",
    "code": "invalid-timezone",
    "instance": "/advertisers/placements/report",
    "title": "Invalid time zone",
    "detail": "Time zone '<value>' is not valid.",
}]