Targeting object

The targeting object is provided as part of the API call when creating line items and creatives. The basic structure of this object is shown below:

{
    "targeting": {
        "deviceTargets": [],
        "adUnitTarget": {},
        "userSegmentTargets": [],
        "dateTarget": {},
        "geospatialTargets": [],
        "keyValueTargets": [],
        "siteTarget": {},
        "adUnitMatchingLabelTargets": [],
        "categoryTargets": [],
        "namedLocationTarget": {},
        "dayPartingTargets": [],
        "retargetingTargets": [],
        "keywordTargets": [],
        "similarKeywordTargets": [],
        "ipAddressTarget": {},
        "siteGroupTarget": {},
        "domainNameTarget": {},
        "viewabilityTarget": {},
        "semanticTargets": [],
        "firstPartyAudienceTarget": {},
        "thirdPartyAudienceTargets": [],
        "publisherTarget": {},
        "articleTarget": {},
        "siteCountryTarget": {},
        "weatherTargets": [],
        "organisationTarget": {}
    }
}

Fields:

Name	Restriction	Description
deviceTargets	Array	deviceTargets
adUnitTarget	Object	adUnitTarget
userSegmentTargets	Array	userSegmentTargets
dateTarget	Object	dateTarget
geospatialTargets	Array	geospatialTargets
keyValueTargets	Array	keyValueTargets
siteTarget	Object	siteTarget
adUnitMatchingLabelTargets	Array	adUnitMatchingLabelTargets
categoryTargets	Array	categoryTargets
namedLocationTarget	Object	namedLocationTarget
dayPartingTargets	Array	dayPartingTargets
retargetingTargets	Array	retargetingTargets
keywordTargets	Array	keywordTargets
similarKeywordTargets	Array	similarKeywordTargets
ipAddressTarget	Object	ipAddressTarget
siteGroupTarget	Object	siteGroupTarget
domainNameTarget	Object	domainNameTarget
viewabilityTarget	Object	viewabilityTarget
semanticTargets	Array	semanticTargets
firstPartyAudienceTarget	Object	firstPartyAudienceTarget
thirdPartyAudienceTargets	Array	thirdPartyAudienceTargets
publisherTarget	Object	publisherTarget
articleTarget	Object	articleTarget
siteCountryTarget	Object	siteCountryTarget
weatherTargets	Array	weatherTargets
organisationTarget	Object	organisationTarget

Device targets

{
"deviceTargets": [
    {
        "targetedBrands": [
                "ACER"
            ],
            "targetedOSes": [
                "ANDROID"
            ],
            "targetedDeviceTypes": [
                "DESKTOP"
            ]
        },
        {
            "targetedBrands": [],
            "targetedOSes": [],
            "targetedDeviceTypes": [
                "MOBILE"
            ]
        }
    ]

}

The device targets can be found with it's endpoint /devices.

Name	Data type	Values
targetedBrands	String	UNKNOWN, DESKTOP, APPLE, NOKIA, HTC, SAMSUNG, SONY_ERICSSON, LG, MOTOROLA, RIM, HUAWEI, ZTE, ASUS, PANASONIC, FUJITSU, SHARP, NEC, KYOCERA, ACER
targetedOSes	String	UNKNOWN, WINDOWS_PHONE, WINDOWS, MACINTOSH, IOS, ANDROID, LINUX, SUNOS, BSD, SYMBIAN, BLACKBERRY
targetedDeviceTypes	String	DESKTOP, TABLET, MOBILE

Ad unit targets

{
    "adUnitTarget": {
        "adUnits": [
            { "id": "d5f6mxj3jbhytmzg" },
            { "id": "jpbnjqy597pvygbm" }
        ]
    }
}

The id of the ad units can be found at this endpoint: /adunits.

Segment targets

{
    "userSegmentTargets": [
        {
            "userSegments": [
                { "id": "xxxxxxxxxxxx" }
            ],
            "notUserSegments": [
                { "id": "yyyyyyyyyyyy" }
            ]
        },
        {
            "userSegments": [
                { "id": "xxxxxxxxxxxx" }
            ],
            "notUserSegments": [
                { "id": "yyyyyyyyyyyy" }
            ]
        }
    ]
}

The id of the segments can be found here at this endpoint: /segments.

When posting targeting data only the id of the adunit is required.

Date targets

{
    "dateTarget": {
        "dateRanges": [
                        {
                "first": "2018-01-02T00:00:00",
                "second": "2018-01-10T23:30:00"
            },
            {
                "first": "2018-01-11T00:00:00",
                "second": "2018-01-12T00:00:00"
            },
            {
                "first": "2018-01-11T00:00:00",
                "second": "2018-01-11T23:30:00"
            }
        ],
        "timeZoneSetting": "SYSTEM"
    },
}

All dates must be specified as follows: yyyy-mm-ddThh:mm:ss.

Name	Data type	Values
dateTarget	Object	The date target object.
dateRanges	Array	An array containing the range objects.
first	String	Start of the date range.
second	String	End of the date range.

Geospatial targets

{
    "geospatialTargets": [
        {
            "definition": {
                "type": "GeometryCollection",
                "geometries": [
                    {
                        "type": "Polygon",
                        "coordinates": [
                            [
                                [
                                    17.9914856,
                                    59.32968705
                                ],
                                [
                                    18.08074951,
                                    59.34999583
                                ],
                                [
                                    18.13568115,
                                    59.30866518
                                ],
                                [
                                    18.08074951,
                                    59.28622753
                                ],
                                [
                                    17.9914856,
                                    59.32968705
                                ]
                            ]
                        ]
                    }
                ]
            }
        },
        {
            "definition": {
                "type": "GeometryCollection",
                "geometries": [
                    {
                        "type": "Polygon",
                        "coordinates": [
                            [
                                [
                                    17.93380737,
                                    59.24100683
                                ],
                                [
                                    17.93380737,
                                    59.27610573
                                ],
                                [
                                    18.06976318,
                                    59.27610573
                                ],
                                [
                                    18.06976318,
                                    59.24100683
                                ],
                                [
                                    17.93380737,
                                    59.24100683
                                ]
                            ]
                        ]
                    }
                ]
            }
        }
    ],
}

The polygons follow the format of GeoJson.

Key value targets

{
    "keyValueTargets": [
        {
            "entries": {
                "key3": [
                    "value-3"
                ]
            },
            "notEntries": {}
        },
        // OR
        {
            "entries": {
                "key4": [
                    "value-4"
                ]
            },
            "notEntries": {}
        },
        // OR
        {
            "entries": {
                "key": [
                    "value"
                ],
                // AND
                "otherKey": [
                    "othervalue"
                ]
            },
            // AND NOT
            "notEntries": {
                "key2": [
                    "value-2"
                ]
            }
        }
    ]
}

• OR values are separated byt objects in the initial array.

• AND values are separated with keys within entries

• AND-NOTare speccified with notEntries as listed above.

Site targets

{
    "siteTarget": {
        "sites": [
            { "id": "6vjwynnz2ptrvdcc" }
            { "id": "6lk3nvdkaai8a3jn" }
        ]
    }
}

The id of the sites can be found at this endpoint: /sites.

When posting targeting data only the id of the site is required.

Ad unit matching label targets

{
    "adUnitMatchingLabelTargets": [
        {
            "matchingLabels": [
                "adunitLabel1"
            ]
        },
        {
            "matchingLabels": [
                "adunitLabel2"
            ]
        }
    ]
}

The ad unit matching labels has to be present on the ad unit for the matching label targeting to work.

For matching labels to work you will need to divide the targeting into separate objects as specified above.

Category targets

{
    "categoryTargets": [
        {
            "categories": [
                "sport"
            ],
            "notCategories": []
        },
        // OR
        {
            "categories": [
                "color/blue"
            ],
            "notCategories": []
        },
        // OR
        {
            "categories": [
                "color/red/crimson",
                //AND
                "sports"
            ],
            // AND NOT
            "notCategories": [
                "andnot"
            ]
        }
    ]
}

• OR values are separated byt objects in the initial array.

• AND values are added within the array.

• AND-NOTare speccified with notEntries as listed above.

Location targets

{

    "namedLocationTarget": {
        "locations": [
            { "id": 1172995 },
            { "id": 9373443 }
        ],
        "municipalities": [
            { "id": 1421 }
        ],
        "negated": false
    }
}

The id of the location can be found at this endpoint: /location. Municipality ids come from /location/municipalities.

When posting targeting data only the id of the location is required. Both fields accept a bare id as well as an object, so "locations": [1172995] is equivalent to the above.

A municipality is targeted as an indivisible whole: it expands to all of its locations. locations and municipalities share the single negated flag. The municipalities field is omitted from responses when nothing is selected.

Use locations and municipalities when posting. The locationIds and municipalityIds names shown by the interactive API explorer are the internal field names and are ignored on input.

Day parting targets

{
    "dayPartingTargets": [
        {
            "daysOfWeek": [
                "TUESDAY",
                "FRIDAY",
                "WEDNESDAY",
                "SATURDAY",
                "MONDAY",
                "THURSDAY",
                "SUNDAY"
            ],
            "hoursOfDay": [
                1,
                19,
                20,
                5,
                21,
                22,
                23
            ],
            "timeZoneSetting": "SYSTEM"
        },
        {
            "daysOfWeek": [
                "TUESDAY",
                "WEDNESDAY",
                "MONDAY",
                "THURSDAY"
            ],
            "hoursOfDay": [
                2,
                3,
                23
            ],
            "timeZoneSetting": "USER"
        }
    ]
}

you can add multiple dayparts by adding multiple objects.

The daypart object is divided in these paramters:

Name	Data type	Values
daysOfWeek	Array	"MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY", "SUNDAY"
hoursOfDay	Array	An array containing numbers 0 for 00:00 - 00:59, 1 for 01:00 - 01:59 etc. up to 23 for 23:00 - 23:59.
timeZoneSetting	String	"USER" for user time zone and "SYSTEM" for the system time zone.

Keyword targets

{
    "keywordTargets": [
        {
            //AND
            "keywords": [
                "games",
                "gambling"
            ],
            "notKeywords": []
        },
        {
            "keywords": [
                "car"
            ],
            "notKeywords": [
                "ferrari",
                "mazda"
            ]
        },
        {
            "keywords": [
                "sport"
            ],
            "notKeywords": []
        }
    ]
}

• OR values are separated byt objects in the initial array.

• AND values are added within the array.

• AND-NOTare speccified with notEntries as listed above.

Retargeting targets

{
    "retargetingTargets": [
        {
            "entries": {
                "or-key": [
                    "or-value"
                ]
            },
            "notEntries": {}
        },
        // OR
        {
            "entries": {
                "the-key": [
                    "value"
                ],
                // AND
                "and-key": [
                    "and-value"
                ]
            },
            // AND NOT
            "notEntries": {
                "and-not-key": [
                    "and-not-value"
                ]
            }
        }
    ]
}

• OR values are separated byt objects in the initial array.

• AND values are added within the array.

• AND-NOTare speccified with notEntries as listed above.

IP targets

{
    "ipAddressTarget": {
        "addresses": [
            "205.112.45.0/24",
            "118.16.78.34"
        ]
    },
}

Contains addresses which is a comma seperated array of IP values. You can add multiple IP addresses by separating each individual one by a comma. For instance, inputting 118.16.78.34, 205.112.45.0/24 will match any of 118.16.78.34 and 205.112.45.0 through to 205.112.45.255. The IP targets follow the CIDR notation.

Site group targets

{
    "siteGroupTarget": {
        "siteGroups": [
            { "id": "8zh8lh7n81s6l2m7" },
            { "id": "j38bl01t2pbtmzkg" }
        ]
    }
}

The id of the sites can be found at this endpoint: /sitegroups.

When posting targeting data only the id of the site is required.

Similar keyword targets

{
    "similarKeywordTargets": [
        {
            "keyword": 4471,
            "match": "NARROW",
            "language": "en",
            "negated": false
        }
    ]
}

Matches content related to a keyword rather than only the keyword itself. keyword is the numeric id of a keyword. match sets how far the meaning may stray, and is one of VERY_NARROW, NARROW, BROAD or VERY_BROAD.

Domain name targets

{
    "domainNameTarget": {
        "names": ["example.com"],
        "negated": false
    }
}

Matches the domain the ad request came from.

Viewability targets

{
    "viewabilityTarget": {
        "viewability": 70
    }
}

Shows the ad only on ad units whose viewability meets a minimum standard. viewability is that minimum, as a percentage from 0 to 100. Leaving it unset, null or zero applies no viewability restriction.

Semantic targets

{
    "semanticTargets": [
        {
            "sentence": 55,
            "score": 0.4,
            "positiveSentimentOnly": false,
            "negated": false
        }
    ]
}

Matches page content by meaning rather than by exact words. sentence is the numeric id of a target sentence, and score is how close the match must be, from 0 to 1, defaulting to 0.4. Set positiveSentimentOnly to only match content whose sentiment is positive.

Audience targets

{
    "firstPartyAudienceTarget": {
        "firstPartyAudiences": ["<audienceId>"]
    },
    "thirdPartyAudienceTargets": [
        {
            "thirdPartyAudiences": ["<audienceId>"],
            "notThirdPartyAudienceIds": []
        }
    ]
}

firstPartyAudienceTarget matches audiences built from your own data. thirdPartyAudienceTargets matches audiences bought from a data provider, and notThirdPartyAudienceIds excludes them.

Publisher targets

{
    "publisherTarget": {
        "earningsAccounts": ["<earningsAccountId>"],
        "negated": false
    }
}

Matches all inventory belonging to a publisher. The id of the earnings account can be found at this endpoint: /earningsaccounts.

Article targets

{
    "articleTarget": {
        "urls": ["https://example.com/news/a-story"],
        "negated": false
    }
}

Matches specific articles by their URL.

Site country targets

{
    "siteCountryTarget": {
        "countries": ["NO", "SE"]
    }
}

Matches inventory by the country of the site, using ISO 3166-1 alpha-2 country codes. This is the country the site belongs to, not the country the reader is in. To target where the reader is, use location targets.

Weather targets

{
    "weatherTargets": [
        {
            "type": "ABOVE_CELSIUS",
            "value": 20,
            "location": 1172995
        }
    ]
}

Matches on the weather at a location. type is ABOVE_CELSIUS or BELOW_CELSIUS and value is the temperature in degrees Celsius. location is a named location id, from the /location endpoint; omit it to use the reader's own location.

Organisation targets

{
    "organisationTarget": {
        "organisations": ["Example Corp"],
        "negated": false
    }
}

Matches the organisation that owns the reader's IP address, which is usually an internet provider or a company network. Names are matched without regard to case. This target has no user interface and is set through the API only.

Examples

A GET request for a targeting object:

{
    "targeting": {
        "deviceTargets": [
            {
                "targetedBrands": [
                    "ACER"
                ],
                "targetedOSes": [
                    "ANDROID"
                ],
                "targetedDeviceTypes": [
                    "DESKTOP"
                ]
            },
            {
                "targetedBrands": [],
                "targetedOSes": [],
                "targetedDeviceTypes": [
                    "MOBILE"
                ]
            }
        ],
        "adUnitTarget": {
            "adUnits": [
                {
                    "id": "d5f6mxj3jbhytmzg",
                    "name": "demo.adnuntius.com - 300 x 250",
                    "url": "/api/v1/adunits/d5f6mxj3jbhytmzg"
                },
                {
                    "id": "jpbnjqy597pvygbm",
                    "name": "demo.adnuntius.com - 980x240 - Panorama 02",
                    "url": "/api/v1/adunits/jpbnjqy597pvygbm"
                }
            ]
        },
        "userSegmentTargets": [
            {
                "userSegments": [
                    {
                        "id": "xxxxxxxxxxxx",
                        "name": "Travel",
                        "description": "People interested in travel"
                    }
                ]
            },
            {
                "userSegments": [
                    {
                        "id": "xxxxxxxxxxxx",
                        "name": "culture",
                        "description": "People interested in culture"
                    }
                ]
            }
        ],
        "dateTarget": {
            "dateRanges": [
                            {
                    "first": "2018-01-02T00:00:00",
                    "second": "2018-01-10T23:30:00"
                },
                {
                    "first": "2018-01-11T00:00:00",
                    "second": "2018-01-12T00:00:00"
                },
                {
                    "first": "2018-01-11T00:00:00",
                    "second": "2018-01-11T23:30:00"
                }
            ],
            "timeZoneSetting": "SYSTEM"
        },
        "geospatialTargets": [
            {
                "definition": {
                    "type": "GeometryCollection",
                    "geometries": [
                        {
                            "type": "Polygon",
                            "coordinates": [
                                [
                                    [
                                        17.9914856,
                                        59.32968705
                                    ],
                                    [
                                        18.08074951,
                                        59.34999583
                                    ],
                                    [
                                        18.13568115,
                                        59.30866518
                                    ],
                                    [
                                        18.08074951,
                                        59.28622753
                                    ],
                                    [
                                        17.9914856,
                                        59.32968705
                                    ]
                                ]
                            ]
                        }
                    ]
                }
            },
            {
                "definition": {
                    "type": "GeometryCollection",
                    "geometries": [
                        {
                            "type": "Polygon",
                            "coordinates": [
                                [
                                    [
                                        17.93380737,
                                        59.24100683
                                    ],
                                    [
                                        17.93380737,
                                        59.27610573
                                    ],
                                    [
                                        18.06976318,
                                        59.27610573
                                    ],
                                    [
                                        18.06976318,
                                        59.24100683
                                    ],
                                    [
                                        17.93380737,
                                        59.24100683
                                    ]
                                ]
                            ]
                        }
                    ]
                }
            }
        ],
        "keyValueTargets": [
            {
                "entries": {
                    "key3": [
                        "value-3"
                    ]
                },
                "notEntries": {}
            },
            {
                "entries": {
                    "key4": [
                        "value-4"
                    ]
                },
                "notEntries": {}
            },
            {
                "entries": {
                    "key": [
                        "value"
                    ],
                    "otherKey": [
                        "othervalue"
                    ]
                },
                "notEntries": {
                    "key2": [
                        "value-2"
                    ]
                }
            }
        ],
        "siteTarget": {
            "sites": [
                {
                    "id": "6vjwynnz2ptrvdcc",
                    "name": "demo.adnuntius.com",
                    "url": "/api/v1/sites/6vjwynnz2ptrvdcc"
                },
                {
                    "id": "6lk3nvdkaai8a3jn",
                    "name": "Other site for My test account",
                    "url": "/api/v1/sites/6lk3nvdkaai8a3jn"
                }
            ]
        },
        "adUnitMatchingLabelTargets": [
            {
                "matchingLabels": [
                    "adunitLabel1"
                ]
            },
            {
                "matchingLabels": [
                    "adunitLabel2"
                ]
            }
        ],
        "categoryTargets": [
            {
                "categories": [
                    "sport"
                ],
                "notCategories": []
            },
            {
                "categories": [
                    "color/blue"
                ],
                "notCategories": []
            },
            {
                "categories": [
                    "color/red/crimson",
                    "sports"
                ],
                "notCategories": [
                    "andnot"
                ]
            }
        ],
        "namedLocationTarget": {
            "locations": [
                {
                    "id": 1172995,
                    "type": "CITY",
                    "name": "Norrköping",
                    "context": "Östergötland, Sweden, Europe"
                },
                {
                    "id": 9373443,
                    "type": "CITY",
                    "name": "Norrköping Ö",
                    "context": "Östergötland, Sweden, Europe"
                }
            ]
        },
        "dayPartingTargets": [
            {
                "daysOfWeek": [
                    "SATURDAY",
                    "WEDNESDAY",
                    "THURSDAY",
                    "FRIDAY",
                    "SUNDAY",
                    "MONDAY",
                    "TUESDAY"
                ],
                "hoursOfDay": [
                    0,
                    16,
                    1,
                    17
                ],
                "timeZoneSetting": "SYSTEM"
            }
        ],
        "retargetingTargets": [
            {
                "entries": {
                    "or-key": [
                        "or-value"
                    ]
                },
                "notEntries": {}
            },
            {
                "entries": {
                    "the-key": [
                        "value"
                    ],
                    "and-key": [
                        "and-value"
                    ]
                },
                "notEntries": {
                    "and-not-key": [
                        "and-not-value"
                    ]
                }
            }
        ],
        "keywordTargets": [
            {
                "keywords": [
                    "games",
                    "gambling"
                ],
                "notKeywords": []
            },
            {
                "keywords": [
                    "car"
                ],
                "notKeywords": []
            },
            {
                "keywords": [
                    "sport"
                ],
                "notKeywords": []
            }
        ],
        "ipAddressTarget": {
            "addresses": [
                "205.112.45.0/24",
                "118.16.78.34"
            ]
        },
        "siteGroupTarget": {
            "siteGroups": [
                {
                    "id": "8zh8lh7n81s6l2m7",
                    "name": "Additional site group",
                    "url": "/api/v1/sitegroups/8zh8lh7n81s6l2m7"
                },
                {
                    "id": "j38bl01t2pbtmzkg",
                    "name": "General Site Group",
                    "url": "/api/v1/sitegroups/j38bl01t2pbtmzkg"
                }
            ]
        }
    }
}