BidRequest

Last updated on March 16, 2017

When appropriate, Ad Exchange sends a BidRequest to the URL specified for your account's Real-time Bid URL setting. If you have multiple matching line items, Ad Exchange includes all of them in the BidRequest. The following table describes the required and optional fields for each BidRequest message. Ad Exchange also sets additional HTTP headers in each BidRequest.

The following diagram depicts a high-level view of the structure of each bid requestWhen OpenX Ad Exchange receives an ad request, it sends a communication containing details about the impression to selected real-time bidders to solicit bids for it..

BidRequest

Field name Data type Description Sent?
ad_height int32

The height of the ad space in pixels

For example: 250

If ad_height is set in the AdId object, it will override this value.

Always
ad_width int32

The width of the ad space in pixels

For example: 300

If ad_height is set in the AdId object, it will override this value.

Always
api_version int32

The OpenX proprietary API version that Ad Exchange is using to communicate with the bidder

Always
app App object

An object containing properties that describe the app where the ad will display if the bid request is for an impressionA single display of an ad on a web page, mobile app, or other delivery medium. For deals, impression is a metric to relay the total number of ads that have served. See also billable impression, forecasted impressions. within a mobile appSynonymous with mobile. Refers to the use of an app via a mobile device, specifically to differentiate from mobile web.

Sometimes
auction_id string

A unique ID for the request, which Ad Exchange uses to identify the auction

For example: 888b4a7a-d259-11e0-9912-000c29b0c11a

Always
device Device object

An object containing properties that describe the end-user's computing environment and location

Sometimes
http_referer string

The HTTP referer for the webpage generating the ad requestCommunication from a web browser or app to an ad server to display an ad.

For example: http://www.referer.com/page.html

Sometimes
implementation_type string

The implementation type for the inventoryAd space available on a website or app. The basic unit of inventory for OpenX is an ad unit., such as a mobile app or a website

Note: Currently, the only possible value is undefined.

Sometimes
is_application bool

Indicates that the BidRequest is for an impression within a mobile app

The default value is false.

Sometimes
is_mobile_site bool

Indicates if the siteAn OpenX component that represents top-level domains or sub-domains and is used to organize ad units. Sites enable you to target and report on inventory performance. has been programmed to optimize layout when viewed on mobile devices (true)

The default value is false (the site does not use responsive web design).

Sometimes
is_test bool

Indicates that this is a test BidRequest message

If set, bidders must return a valid BidResponse message, which is used for validation and then discarded.

Sometimes
market_operator string

Indicates one of the following Ad Exchange operators representing the publisherAn account type that represents a business with ad space to sell.:

  • cci (OpenX Market Japan)

  • cci-sea (OpenX Market Southeast Asia)

  • OX-GB (OpenX Market Great Britain)

  • OX (OpenX Market: all other locations)

You can use this value instead of the end-user's geographic information to infer the publisher's location.

Sometimes
matching_ad_ids array (AdId object)

An array of objects describing the matching ads for which Ad Exchange is soliciting bids from the bidder

Always
ox_cat_tier_1 int32

The ID of the top-level tier of the webpage's content category

ox_cat_tier_1 values:

  • 1 (Adult)

  • 2 (Arts & Entertainment)

  • 3 (Automotive)

  • 4 (Business)

  • 5 (Careers)

  • 23 (Education)

  • 7 (Electronics)

  • 9 (Family & Parenting)

  • 10 (Firearms and Weapons)

  • 11 (Food & Drink)

  • 12 (Gambling)

  • 13 (Government, Law & Politics)

  • 14 (Health & Fitness)

  • 15 (Hobbies & Interests)

  • 17 (Home & Garden)

  • 19 (Internet)

  • 20 (Mobile Websites and Apps)

  • 21 (News)

  • 99 (Not Classified)

  • 30 (Personal Finance)

  • 16 (Pets)

  • 22 (Real Estate)

  • 29 (Reference & Directory)

  • 34 (Religion and Spirituality)

  • 24 (Science)

  • 6 (Shopping)

  • 8 (Social Networking)

  • 32 (Social Science)

  • 35 (Society)

  • 25 (Sports)

  • 33 (Style & Fashion)

  • 18 (Technology & Computing)

  • 31 (Telecommunications)

  • 26 (Tobacco and Smoking)

  • 28 (Travel)

Sometimes
ox_cat_tier_2 int32

The ID of the subcategory for the webpage content

See ox_cat_tier_2 values.

Sometimes
pub_blocked_ad_languages array (string)

An array of languages that the publisher blocks in ads that display on the webpage

The possible values include:

  • en (English)

  • fr (French)

  • ja (Japanese)

  • others (All other languages)

For example: fr

Sometimes
pub_blocked_cat array (int32)

An array of advertiserIn OpenX, an account type that represents a business that runs advertising campaigns to display ads on websites. category IDs blocked for this publisher in the ad request

pub_blocked_cat IDs and values:

  • 1 (Adult)

  • 2 (Arts & Entertainment)

  • 3 (Automotive)

  • 4 (Business)

  • 5 (Careers)

  • 23 (Education)

  • 7 (Electronics)

  • 9 (Family & Parenting)

  • 10 (Firearms and Weapons)

  • 11 (Food & Drink)

  • 12 (Gambling)

  • 13 (Government, Law & Politics)

  • 14 (Health & Fitness)

  • 15 (Hobbies & Interests)

  • 17 (Home & Garden)

  • 19 (Internet)

  • 20 (Mobile Websites and Apps)

  • 21 (News)

  • 99 (Not Classified)

  • 30 (Personal Finance)

  • 16 (Pets)

  • 22 (Real Estate)

  • 29 (Reference & Directory)

  • 34 (Religion and Spirituality)

  • 24 (Science)

  • 6 (Shopping)

  • 8 (Social Networking)

  • 32 (Social Science)

  • 35 (Society)

  • 25 (Sports)

  • 33 (Style & Fashion)

  • 18 (Technology & Computing)

  • 31 (Telecommunications)

  • 26 (Tobacco and Smoking)

  • 28 (Travel)

Sometimes
pub_blocked_content array (int32)

An array of blocked content IDs for this publisher in the ad request

Sometimes
pub_blocked_type array (int32)

An array of blocked creativeThe media asset associated with an ad, such as an image or video file. type IDs for this request

pub_blocked_type values:

Note: 6, 8, and 9 are not used.

Sometimes
pub_blocked_url array (string)

An array of blocked domains from the click URL

For example: nike.com

Sometimes
pub_website_id string/int32

Unique ID for the publisher’s website where the winning bidder's ad will display

For example:

  • 3f6b1508-75ee-4283-8de5-3ddadf3ab338 (a UUID)

  • 2428 (an integer)

Always
regs Regulations object An object containing properties that describe regulations that apply to this impression Sometimes
ssl_enabled bool

If this impression must be SSL secured, all creative assets that are returned must use the HTTPS protocol, not HTTP.

  • 0 (false - default value)

  • 1 (true - HTTPS URLs are required.)

Sometimes
rtb_data string

Specific user data of a bidder, such as a bidder’s user ID. Ad Exchange also sets this value in the X-OpenX-Rtb custom HTTP header.

Sometimes
site Site object

An object containing properties that describe the website (i.e., the exchange-specific publisher ID)

Sometimes
tp_key_val array (ThirdPartyKeyValue object)

An array of objects containing third-party key value pairs that describe the device where the user is viewing the impression

Sometimes
url string

The URL initiating the ad request

For example: http://www.publisher.com/page.html

Sometimes
user User object

An object containing properties that describe the user viewing the impression

Sometimes
user_agent string

The user agent string for the user

Sometimes
user_cookie_id string

An OpenX ID for the user viewing the web page, which is only returned when OpenX is able to set a cookie for the user.

To protect the identity of the user, this value is different for each bidder. For example, Ad Exchange may send a value of 1234 to bidder A, and a value of 5678 to bidder B, which both represent the same user. Ad Exchange also sets this value in the X-OpenX-Id custom HTTP header.

Sometimes
user_geo_country string

The user’s country location

For example: us

Sometimes
user_geo_dma int32

ID of the user's designated market area (DMA) location

For example: 5

Sometimes
user_geo_state string

The user's state location

For example: california

Sometimes
user_ip_address bytes

IP address for the user viewing the webpage

Sometimes
user_lang array (string)

A list of the user's preferred languages

For example: en (English)

Sometimes
user_screen_height int32

Height of the user's viewing screen (in pixels)

For example: 1200

Sometimes
user_screen_width int32

Width of the user's viewing screen (in pixels)

For example: 1600

Sometimes

See also:

Feedback form