Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Reverted from v. 24

...

Using HTTP GET, you'll send all BidRequest parameters and values encoded in the URL. The sections below show the Required parameters, followed by the Optional parameters, and a brief example for each.

...

Info
titleInfo

The BidRequest object supports ad pods. See AdPod object for details.

Source object

...

The Imp object is a child of BidRequest described above, and Imp objects are typically the parent of Video. The next table shows the OpenWrap key to reference Imp objects, and for comparison, the equivalent OpenRTB 2.5 key to reference Impression objects.

...

Info
titleInfo

The Impression object supports ad pods. See AdPod object for details.

PMP object

The PMP object is a parameter object of the Imp object. PMP objects in turn may encapsulate Deal and Extension objects, as described below.

ParameterTypeDescriptionExample

private_auction

Integer

Default: 0

Indicator of auction eligibility to seats named in the Direct Deals object

0 = all bids are accepted

1 = bids are restricted to the deals specified and the terms thereof.

1
deals Object ArrayArray of Deal objects that convey the specific deals applicable to an impressionSee  Deals section below.
extObjectPlaceholder for exchange-specific extensions to OpenRTB.See  Ext section below.

Deal object

The Deal object contains configuration details for Deals belonging to the current Imp, and are encapsulated by a PMP object.

ParameterTypeDescriptionExample
id

String:

Required

A unique identifier for the direct deal.1234
bidfloor

Float

Default: 0

Minimum bid for this impression expressed in CPM.1.2
bidfloorcur

String

Default: USD

Currency specified using ISO-4217 alpha codes. This may be different from bid currency returned by bidder if this is allowed by the exchange.USD
atInteger

Optional override of the overall auction type of the bid request

1 = First Price

2 = Second Price Plus

3 = the value passed in bidfloor is the agreed upon deal price.

Additional auction types can be defined by the exchange.

1
wseatString Array

Allowlist of buyer seats (for example, advertisers, agencies) allowed to bid on this deal.

IDs of seats and the buyer’s customers to which they refer must be coordinated between bidders and the exchange a priori.

Omission implies no seat restrictions.

nike,puma
wadomainString Array

Array of advertiser domains (for example, advertiser.com) allowed to bid on this deal.

Omission implies no advertiser restrictions.

ad.com,page.com
extObjectPlaceholder for exchange-specific extensions to OpenRTB.See  Ext section below.

Video object

The Video object is a child of the Impression object, described above. The next table shows the OpenWrap key to reference Vid objects, and for comparison, the equivalent OpenRTB 2.5 key to reference Video objects.

...

ParameterTypeDescriptionExample
mindurationIntegerMinimum video duration of ad (or ad pod) in seconds.5
maxdurationIntegerMaximum video duration of ad (or ad pod) in seconds . 120
protocolsInteger Array

Array of supported video protocols.

Specify at least one supported protocol in either the protocol or protocols attribute.

2,3,5,6,7,8
wIntegerWidth of the video player in device independent pixels (DIPS).320
hIntegerHeight of the video player in device independent pixels (DIPS).480
startdelayInteger

Indicates the start delay in seconds for pre, mid, or post-roll ad placements.

0
placementInteger Placement type for the impression.5
linearityInteger

Determines whether the impression is linear, nonlinear, and so on. Leaving unspecified implies all are allowed.

1
skipInteger

Determines whether the user can skip the video ad.

0 = No

1 = Yes

If a bidder sends markup/creative that is skippable, the Bid object must include the attr array with an element of 16 to flag that the video is skippable.

1
skipminIntegerVideos of total duration greater than this number of seconds can be skippable; only applicable if the ad is skippable.1
skipafterIntegerNumber of seconds a video must play before skipping is enabled; only applicable if the ad is skippable.1
sequenceIntegerIf the BidRequest offers multiple ad impressions, the sequence number facilitates coordinated delivery of multiple creatives.1
battrInteger ArrayBlocked creative attributes.1,2,3
maxextendedInteger

Maximum extended ad duration, if allowed.

blank/0 = extension is not allowed.

-1 = extension allowed, without time limit.

1 or greater = represents the number of seconds playback extends beyond maxduration.

10
minbitrateIntegerMinimum bit rate in Kbps.1200
maxbitrateIntegerMaximum bit rate in Kbps.2000
boxingallowedInteger

Determines whether 4:3 content is letter-boxed into 16:9 aspect ratio.

0 = No.

1 = Yes.

1
playbackmethodInteger Array

Playback methods that may be in use. Unspecified implies that any method is possible.

Typically only one method ever used. As a result, a future version of the specification may define this parameter as an integer.  The best practice is to use only the first element of this array in preparation for this change.

1
deliveryInteger Array Supported delivery methods; for example, streaming, progressive. Unspecified implies that all are supported.2
posInteger Ad position on screen.7
apiInteger ArrayList of supported API frameworks for this impression. Unlisted APIs equal unsupported.2

...

ObjectOpenWrap KeyORTB 2.5 Key
Contentsite.cnt.[param]bidrequest.site.content.[param]
Publishersite.pub.[param]bidrequest.site.publisher.[param]

...

ObjectOpenWrap KeyORTB 2.5 Key
Contentapp.cnt.[param]bidrequest.app.content.[param]
Publisherapp.pub.[param]bidrequest.app.publisher.[param]

...

The Publisher object is a child of the Site and App objects, described above. The next table shows the OpenWrap keys to reference Pub objects, and for comparison, the equivalent OpenRTB 2.5 keys to reference Publisher objects.

...

The Content object is a child of the Site and App objects, described above. The next table shows the OpenWrap keys to reference Cnt objects, and for comparison, the equivalent OpenRTB 2.5 keys to reference Content objects.

...

ParameterTypeDescriptionExample
idStringID uniquely identifying the content.381d2e0b-548d-4f27-bfdd-e6e66f43557e
episodeIntegerEpisode number.1
titleString

Content title.

Video Examples: “Search Committee” (television), “A New Hope” (movie), or “Endgame” (made for web).

Non-Video Example: “Why an Antarctic Glacier Is Melting So Quickly” (Time magazine article)

StarWars
seriesString

Content series.

Video Examples: “The Office” (television), “Star Wars” (movie), or “Arby ‘N’ The Chief” (made for web).

Non-Video Example: “Ecocentric” (Time Magazine blog).

StarWars
seasonStringContent season (for example, “Season 3”).Season3
artistStringArtist credited with the content.GeorgeLucas
genreStringGenre that best describes the content (for example, rock, pop, etc).Action
albumStringAlbum to which the content belongs; typically for audio.Action
isrcStringInternational Standard Recording Code conforming to ISO-3901.2
urlStringURL of the content, for buy-side contextualization or review.http://www.pubmatic.com/test/
catString ArrayArray of IAB content categories that describe the content producer.IAB1-1,IAB1-2
prodqIntegerProduction quality.1
contextIntegerType of content (game, video, text, etc.).1
contentratingStringContent rating (for example, MPAA).MPAA
userratingStringUser rating of the content (for example, number of stars, likes, etc.).9-Stars
qagmediaratingIntegerMedia rating per IQG guidelines.1
keywordsStringComma separated list of keywords describing the content.ActionMovies
livestreamInteger

0 = Not Live

1 = Content is Live (for example, stream, live blog).

1
sourcerelationshipInteger

0 = Indirect

1 = Direct.

1
lenIntegerLength of content in seconds; appropriate for video or audio.12000
languageStringContent language using ISO-639-1-alpha-2.en-US
embeddableInteger

Indicator of whether or not the content is embeddable (for example, an embeddable video player).

0 = No

1 = Yes

1

The Content object can also contain the Producer parameter object.

Producer object

The Producer object is a parameter object for the Content, described above. The next table shows the OpenWrap keys to reference Prod objects from App and Site contexts, and for comparison, the equivalent OpenRTB 2.5 keys.

...

ParameterTypeDescriptionExample
uaString

Browser user agent string.

Note

It can be derived from User-Agent header if not specified.


Mozilla%2F5. 0%20
(Windows%20NT%206.
1%3B%20Win64%3B%20x64%3B%20rv%3A47.0)
%20Gecko%2F20100101%20Firefox%2F47.0

dntInteger

Standard “DoNotTrack” flag as set in the header by the browser.

0 = Tracking is unrestricted

1 = Do Not Track.

1
lmtInteger

“Limit Ad Tracking” signal commercially endorsed (for example, iOS, Android)

0 = tracking is unrestricted

1 = tracking must be limited per commercial guidelines.

1
ipString

IPv4 address closest to device.

Note

It can be derived from request headers in following sequence.

* HTTP_RLNCLIENTIPADDR
* HTTP_SOURCE_IP
* HTTP_X_CLUSTER_CLIENT_IP
* HTTP_X_FORWARDED_IP
* REMOTE_ADDR


127.0.0.1
ipv6StringIP address closest to device as IPv6.2001:db8::8a2e:370:7334
devicetype
IntegerThe general type of device.1
makeStringDevice make (for example, “Apple”)Samsung
modelStringDevice model (for example, “iPhone”)Galaxy-A70S
osStringDevice operating system (for example, “iOS”).Android
osvStringDevice operating system version (for example, “3.1.2”)MarshMellow
hwvStringHardware version of the device (for example, “5S” for iPhone 5S).A70s
hIntegerPhysical height of the screen in pixels768
wIntegerPhysical width of the screen in pixels1366
ppiIntegerScreen size as pixels per linear inch.4096
pxratioFloatThe ratio of physical pixels to device independent pixels1.3
jsInteger

Support for JavaScript.

0 = No

1 = Yes

1
geofetchInteger

Indicates if the geolocation API will be available to JavaScript code running in the banner

0 = No

1 = Yes

0
flashverStringVersion of Flash supported by the browser.1.1
languageStringBrowser language using ISO-639-1-alpha-2.en-US
carrierStringCarrier or ISP (for example, “VERIZON”) using exchange-curated string names, which once deduced, should be published to bidders.VERIZON
mccmncString

Mobile carrier as the concatenated MCC-MNC code (for example, “310-005” identifies Verizon Wireless CDMA in the USA).

See the Wikipedia article on Mobile country codes for further examples.

Note that the dash between the MCC and MNC segments is required to ensure accurate parsing.

310-005
connectiontype IntegerNetwork connection type. 2
ifaStringID sanctioned for advertiser use in the clear (that is, not hashed).EA7583CD-A667-48BC-B806-42ECB2B48606
didsha1StringHardware device ID (for example, IMEI); hashed via SHA1. 613b4d2f6a09ee5f820d670a1d5b1cc4ccc08bc2
didmd5StringHardware device ID (for example, IMEI); hashed via MD5.12d2cd0eacd05dae666c4a5ff3067e42
dpidsha1StringPlatform device ID (for example, Android ID); hashed via SHA1. 613b4d2f6a09ee5f820d670a1d5b1cc4ccc08bc2
dpidmd5StringPlatform device ID (for example, Android ID); hashed via MD5.12d2cd0eacd05dae666c4a5ff3067e42
macsha1StringMAC address of the device; hashed via SHA1. 613b4d2f6a09ee5f820d670a1d5b1cc4ccc08bc2
macmd5StringMAC address of the device; hashed via MD5.12d2cd0eacd05dae666c4a5ff3067e42

The Device object can also contain the Geo parameter object.

User object

...

The User object can also contain the Geo parameter object.

Geo object

The Geo object is a child of the Device and User objects, described above. The next table shows the OpenWrap keys to reference the Geo object from Device and User contexts, and for comparison, the equivalent OpenRTB 2.5 keys.

...

ParameterTypeDescriptionExample
latFloatLatitude from -90.0 to +90.0, where negative is south.72.6
lonFloatLongitude from -180.0 to +180.0, where negative is west.72.6
type
Integer Source of location data; recommended when passing lat/lon.1
accuracyInteger

Estimated location accuracy in meters;

Recommended when lat/lonare specified and derived from a device’s location services (that is, type = 1).

Note that this is the accuracy as reported from the device. Consult OS specific documentation (for example, Android, iOS) for exact interpretation.

10
lastfixInteger

Number of seconds since this geolocation fix was established.

Note that devices may cache location data across multiple fetches.

Ideally, this value should be from the time the actual fix was taken.

0
ipservice IntegerService or provider used to determine geolocation from IP address if applicable (that is, type = 2).1
countryStringCountry code using ISO-3166-1-alpha-3India
regionStringRegion code using ISO-3166-2; 2-letter state code if USA.Maharashtra
regionfips104String

Region of a country using FIPS 10-4 notation.

While OpenRTB supports this attribute, it has been withdrawn by NIST in 2008.

MAHA
metroStringGoogle metro code; similar to but not exactly Nielsen DMAs.Mumbai
cityStringCity using United Nations Code for Trade and Transport Locations.Mumbai
zipStringZip or postal code.123456
utcoffsetIntegerLocal time as the number +/- of minutes from UTC.120

...

  • GET API supports single video impression only. It currently does not support multiple impressions.
  • Use standard URL encoding for all String parameters to ensure requested URL doesn't break.
  • The default format for all String Array parameters is comma separated.
  • The dynamic extension parameters currently support only JSON string and JSON object data types. No other JSON data types are supported at this time.

AdPod object

AdPod is an Extension object of the  BidRequest or  Impression.Video objects described above.

...

ParameterTypeMandatory
(with a defined AdPod object)?
DescriptionDefault value
(with a defined AdPod object)
offsetInteger

Defines the position where the AdPod might play in a long video; for example, 30 min from start. This helps define duration based rules to determine when the same ads can/cannot play.

0
minadsInteger

Minimum number of ads to include in the AdPod.21
maxadsInteger

Maximum number of ads to include in the AdPod.3
admindurationInteger

Minimum duration in seconds for each ad in the AdPod.video.minduration/2
admaxdurationInteger

Maximum duration in seconds for each ad in the AdPod.video.maxduration/2
excladvInteger

Percentage of ads allowed to have the same advertiser in the AdPod.100
excliabcatInteger

Percentage of ads allowed to have the same IAB category in the AdPod.100
BIDREQUEST-ONLY PARAMETERS
adpod
(POST method only)
Object

New object for defining an AdPod object.
crosspodexcladvInteger

Percentage of ads allowed to have the same advertiser across all AdPods in the BidRequest.100
crosspodexcliabcatInteger

Percentage of ads allowed to have the same IAB categories across all AdPod s in the BidRequest .100
excliabcatwindowInteger

The number of minutes during which the exclusive IAB rule applies. If two AdPods render within a window, then the rule applies, otherwise the rule resets.

100
excladvwindowInteger

The number of minutes during which the exclusive advertiser rule applies. If two AdPod s render within a window, then the rule applies, otherwise the rule resets.

100


CTV endpoints
Anchor
CTV endpoints
CTV endpoints

EndpointDescription
OpenRTB endpoint returns IAB Standard OpenRTB 2.5 formatted response for a BidRequest.
VAST endpoint returns VAST-format XML response for a video BidRequest.
/video/json This CTV video endpoint will cache individual AdPod creatives and return targeting values in response.

...

The table below describes the parent  BidResponse  object, which encapsulates the SeatBid object array.

...