Object Specification

Object Specification: Bid Request (p. 1)

The top-level bid request object contains a globally unique bid request or auction ID. This id attribute is required as is at least one impression object. Other attributes in this top-level object establish rules and restrictions that apply to all impressions being offered.

Attribute	Type	Description
id	string; required	Unique ID of the bid request, provided by the exchange.
imp	required	Representing the impressions offered. At least 1 Imp object is required.
site	either site or app is required	The publisher’s website.
app	either site or app is required	The publisher’s application (i.e., non-browser applications).
device	required	The user’s device to which the impression will be delivered.
user	optional	The human user of the device; the advertising audience.
at	integer; optional	Auction type, where 1 = First Price, 2 = Second Price. Default: at=2.
tmax	integer; optional	Maximum time in milliseconds to submit a bid to avoid timeout. This value is commonly communicated offline if it is set up on a pub zone.

Object Specification: Bid Request

Attribute	Type	Description
cur	string array	Only USD is supported.
bcat	string array	Blocked advertiser categories using the IAB content categories.
badv	string array	Block list of advertisers by their domains (e.g., “ford.com”).

Object Specification: Impression

Attribute	Type	Description
id	string; required	A unique identifier for this impression within the context of the bid request (typically, starts with 1 and increments).
banner	either banner,native or video required	A Banner object.
native	either banner,native or video required	A Native object.
video	either banner,native or video required	A Video object.
bidfloor	optional; float; default 0	Minimum bid for this impression expressed in CPM
secure	optional; integer	Flag to indicate if the impression requires secure HTTPS URL creative assets and markup, where 0 = non-secure, 1 = secure.

Object Specification: Banner

Attribute	Type	Description
w	integer; required	Width of the impression in pixels.
h	integer; required	Height of the impression in pixels.
battr	integer array; optional	Blocked creative attributes.
pos	integer; optional	Ad position on screen.
btype	integer array; optional	Blocked banner ad types.
mimes	string array; optional	Content MIME types supported. Popular MIME types may include: “application/x-shockwave-flash”, ”image/jpeg” and “image/gif”

Object Specification: Native, User

“Native” as an object represents a native-type impression. Native ad units are intended to blend seamlessly into the surrounding content. As such, the response must be well-structured to afford the publisher fine-grained control over rendering.

“User” as an object contains information known or derived about the human user of the device (i.e., the audience for advertising).

Object	Attribute	Type	Description
Native	request	required	Request payload complying with the Native Ad Specification as a string.
Native	battr	integer array; optional	Blocked creative attributes.
User	id	string; optional	Exchange-specific ID for the user.
User	buyeruid	string; optional	Buyer-specific ID for the user as mapped by the exchange for the buyer.
User	yob	string; optional	Year of birth as a 4-digit integer.

Native Request Markup Object

Native request Markup is an escaped JSON document that should be included to a Native Object’s attribute - request. “User” as an object contains information known or derived about the human user of the device (i.e., the audience for advertising). The Default column dictates how optional parameters should be interpreted if explicit values are not provided.

Field	Scope	Type	Default	Description
ver	optional	string	1	Version of the Native Markup version in use.
layout	recommended	integer	-	The Layout ID of the native ad unit.
adunit	recommended	integer	-	The Ad unit ID of the native ad unit.
plcmtcnt	optional	integer	1	The number of identical placements in this Layout.
seq	optional	integer	0	0 for the first ad, 1 for the second ad, and so on.
assets	optional	an array of Asset Objects	-	Any bid must comply with the array of elements expressed by the Exchange.

Object Specification: Site

This object should be included if the ad-supported content is a website as opposed to a non-browser application.

Attribute	Type	Description
pagecat	string array; optional	Array of IAB content categories that describe the current page or view of the site.
domain	string; optional	Domain of the site (e.g., “mysite.foo.com”).
page	string; optional	URL of the page where the impression will be shown.
cat	string array; optional	Array of IAB content categories of the site.
sectioncat	string array; optional	Array of IAB content categories that describe the current section of the site.

App Object

This object should be included if the ad-supported content is a non-browser application (typically in mobile) as opposed to a website.

Attribute	Type	Description
id	string; optional	Exchange-specific app ID.
name	string; optional	App name (may be aliased at the publisher’s request)
bundle	string; required	Application bundle or package name (e.g., com.foo.mygame for Android apps and 123456 for Apple apps).
domain	string; optional	Domain of the app (e.g., “mygame.foo.com”).
storeurl	string; optional	App store URL for an installed app.
cat	string array; optional	Array of IAB content categories of the app.
sectioncat	string array; optional	Array of IAB content categories that describe the current section of the app.
pagecat	string array; optional	Array of IAB content categories that describe the current page or view of the app.

This object should be included if the ad-supported content is a non-browser application (typically in mobile) as opposed to a website.

Attribute	Type	Description
ver	string; optional	Application version.
privacypolicy	integer; optional	Indicates if the app has a privacy policy, where 0 = no, 1 = yes.
paid	integer; optional	0 = app is free, 1 = the app is a paid version.
keywords	string; optional	Comma separated list of keywords about the app.

Device Object

This object provides information pertaining to the device through which the user is interacting. Device information includes its hardware, platform, location, and carrier data. The device can refer to a mobile handset, a desktop computer, set-top box, or other digital device. For desktop devices only “ua” and “ip” attributes are required. Mobile devices require “ifa” or “ifa” hashes to be present.

Attribute	Type	Description
ua	string; optional	Browser user agent string.
geo	integer; optional	Location of the device assumed to be the user’s current location defined by a Geo object.
ip	integer; optional	IPv4 address.
devicetype	string; optional	The general type of device.
make	string; optional	Device make (e.g., “Apple”).
model	string; optional	Device model (e.g., “iPhone”).
os	string; optional	Device operating system (e.g., “iOS”).

hwv	string; optional	Hardware version of the device (e.g., “5S” for iPhone 5S).
h	integer; optional	Physical height of the screen in pixels.
w	integer; optional	Physical width of the screen in pixels.
ppi	integer; optional	Screen size as pixels per linear inch.
pxratio	float; optional	The ratio of physical pixels to device independent pixels.
flashver	string; optional	Version of Flash supported by the browser.
language	string; optional	Browser language using ISO-639-1-alpha-2.
carrier	string; optional	Carrier or ISP (e.g., “VERIZON”). “WIFI” is often used in mobile to indicate high bandwidth.
connectiontype	integer; optional	Network connection type.
js	integer; optional	Support for JavaScript, where 0 = no, 1 = yes.

ifa	string; at least 1 must be present; optional	ID sanctioned for advertiser use in the clear (i.e., not hashed). “Apple ID for Advertising” or “Android Advertiser Id”.
didsha1	string; at least 1 must be present; optional	Hardware device ID (e.g., IMEI); hashed via SHA1.
didmd5	string; at least 1 must be present; optional	Hardware device ID (e.g., IMEI); hashed via MD5.
dpidsha1	string; at least 1 must be present; optional	Platform device ID (e.g., Android ID); hashed via SHA1.
dpidmd5	string; at least 1 must be present; optional	Platform device ID (e.g., Android ID); hashed via MD5.
macsha1	string; optional	MAC address of the device; hashed via SHA1.
macmd5	string; optional	MAC address of the device; hashed via MD5.

Geo Object

This object encapsulates various methods for specifying a geographic location.

Attribute	Type	Description
lat	float; optional	Latitude from -90.0 to +90.0, where negative is south.
lon	float; optional	Longitude from -180.0 to +180.0, where negative is west.
type	integer; optional	Source of location data; recommended when passing lat/lon. type=1: GPS/Location Services, type=2: IP Address, type=3: User provided (e.g., registration data).
country	string; optional	Country code using ISO-3166-1-alpha-3.
region	string; optional	Region code using ISO-3166-2; 2-letter state code if USA.
city	string; optional	City from MaxMind geo database.
zip	string; optional	Zip or postal code.
utcoffset	string; optional	Local time as the number +/- of minutes from UTC.

Asset Object

The main container object for each asset requested or supported by Exchange on behalf of the rendering client. Any object that is required is to be flagged as such. Only one of the {title, image, data, video} objects should be present in each object. All others should be null/absent. The id is to be unique within the Asset Object array so that the response can be aligned.

Field	Scope	Type	Default	Description
id	required	integer	-	Unique asset ID, assigned by exchange. Typically a counter for the array.
required	optional	integer	0	Set to 1 if asset is required (exchange will not accept a bid without it).
title	one of the {title, img, data, video}	object	-	Title object for title assets.
data	one of the {title, img, data, video}	object	-	Data object for ratings, prices etc.
img	one of the {title, img, data, video}	object	-	Image object for image assets.
video	one of the {title, img, data, video}	object		Video object for video assets.

Title Object

The Title object is to be used for the title element of the Native ad.

Field	Scope	Type	Default	Description
len	required	integer	-	Maximum length of the text in the title element.

Image Asset Object

Field	Scope	Type	Default	Description
type	optional	integer	-	Type ID of the image element supported by the publisher.
w	optional	integer	-	Width of the image in pixels.
wmin	recommended	integer	-	The minimum requested width of the image in pixels.
h	optional	integer	-	Height of the image in pixels.
hmin	recommended	integer	-	The minimum requested height of the image in pixels.
mimes	optional	array of strings	All types allowed	Whitelist of content MIME types supported. Popular MIME types include, but are not limited to “image/jpg” “image/gif”.

Video Asset Object

The video object to be used for all video elements supported in the Native Ad.

Field	Scope	Type	Default	Description
mimes	required	array of strings	-	Content MIME types supported. Popular MIME types include,but are not limited to “video/x-ms-wmv” for Windows Media, and “video/x-flv” for Flash Video.
minduration	required	integer	-	Minimum video ad duration in seconds.
maxduration	required	integer	-	Maximum video ad duration in seconds.
protocols	required	array of integers	-	An array of video protocols the publisher can accept in the bid response.

Data Asset Object

Field	Scope	Type	Default	Description
type	required	integer	-	Type ID of the element supported by the publisher. The publisher can display this information in an appropriate format.
len	optional	integer	-	Maximum length of the text in the element’s response.