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.
Last updated
Was this helpful?