OpenRTB fields passed by publishers

Last updated January 16, 2019

You can pass as many supported OpenRTB values as you find useful to characterize your inventoryClosedAd space available on a website or app. The basic unit of inventory for OpenX is an ad unit. except for those that cannot be passed by publishers. However, passing too many fields can negatively impact the performance of the ad requestClosedCommunication from a web browser or app to an ad server to display an ad., so only add fields that will help buyers to target your inventory.

Below is a reference of OpenRTB fields that you can pass as a publisherClosedAn account type that represents a business with ad space to sell.:

BidRequest fields

Field name Data type Description
app App object

An object containing properties that describe the app where the ad will display if the bid request is for an impressionClosedA 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 appClosedSynonymous with mobile. Refers to the use of an app via a mobile device, specifically to differentiate from mobile web..

A bid requestClosedWhen 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. can only have an App or a Site object.

badv array (string)

The list of top-level advertiser domains blocked for this publisher as derived from the click URL. Domains are not case-sensitive.

For example: blockeddomain.com

bcat array (string)

The list of advertiser categories that the publisher wants to block for the ad request.

Use the IAB categories listed in the IAB's OpenRTB 2.5 specification in this field.

For example: "bcat": [ "IAB17-18", "IAB24", "IAB25", "IAB25-3", ],

device Device object

An object containing properties that describe the device through which the impression is viewed, such as on a specific type of mobile phone.

imp array (Imp object)

An object containing properties that describe the ad impression for which OpenX Ad ServerClosedA complete digital advertising platform where publishers sell, manage, and deliver their advertising inventory across all digital formats. is soliciting bids.

OpenX supports only one impression per bid request, which is expressed as an array with a single Imp object. This is because OpenX handles each ad unitClosedThe smallest inventory component that represents the space on a site where ads display. as a separate ad request.

regs Regs object

An object containing properties that describe any regulations applicable to the request.

site Site object

An object containing properties that describe the website where the ad will display if the bid request is for an impression on a website.

The bid request can only have a Site or an App object.

test

integer

Indicates test mode (1), which is not billable.

The default is 0, which indicates that the auction is billable.

user User object

An object containing properties that describe the user viewing the impression.

Field name Data type Description
banner Banner object
float
string
string
integer
Native object
integer
string
Field name Data type Description
array (integer)
battr array (integer)
array (integer)
array (integer)
integer
integer
array (string)
integer
integer
integer
Field name Data type Description
array (integer)
battr array (integer)
request string
ver string

Site fields

BidRequest.site

If the available impression is on a website, OpenX Ad Server may include a SiteClosedAn OpenX component that represents top-level domains or subdomains and is used to organize ad units. Sites enable you to target and report on inventory performance. object to describe the website.

A BidRequest can only contain a single Site or App object, not both.

A Site object can reference the Publisher object.

Field name Data type Description

content

Content object

An object containing properties that describe the site's content.

keywords

(recommended)

string

A comma-separated list of keywords describing the site's content.

mobile

integer

Indicates whether the site has been programmed to optimize layout when viewed on mobile devices.

  • 0 = false (the default)

  • 1 = true (the site uses responsive web design)

page string

The URL of the webpage where the impression will display.

pagecat

array (string)

The list of IAB content categories for the webpage as defined in the IAB's OpenRTB 2.5 specification.

privacypolicy

integer

Indicates whether the site has a privacy policy (1) or not (0).

publisher Publisher object

An object containing properties that describe the publisher of the Site or App for this impression opportunity.

ref string

The referrer URL that navigated the end-user to the current page.

search

string

The search string that brought the end-user to the current page (if available).

sectioncat

array (string)

The list of IAB content categories for the site sectionClosedA way of classifying inventory, for example into vertical segments of content. as defined in the IAB's OpenRTB 2.5 specification.

App fields

BidRequest.app

If the available impression is within a mobile app, the BidRequest includes the App object to describe the mobile app.

A BidRequest can only contain a single App or Site object, not both.

Field name Data type Description

bundle

(strongly recommended)

string

The unique ID of the app's package (Android), bundle (iOS), or its AppStore ID.

For example: "com.demo.openx" or "123456789"

cat

(recommended)

array (string)

The list of IAB content categories for the app, as defined in the IAB's OpenRTB 2.5 specification.

content

Content

An object containing properties that describe the app's content.

keywords

(recommended)

string

A comma-separated list of keywords describing the app's content.

name

(strongly recommended)

string

The name of the app.

pagecat

array (string)

The list of IAB content categories for the current page of the app, as defined in the IAB's OpenRTB 2.5 specification.

paid

integer

Indicates whether the app is a paid version (1) or free (0).

privacypolicy

integer

Indicates whether the app has a privacy policy (1) or not (0).

publisher

Publisher object

An object containing properties that describe the publisher of the app.

sectioncat

array (string)

The list of IAB content categories for the current section of the app, as defined in the IAB's OpenRTB 2.5 specification.

storeurl

(recommended)

string

The app store URL for this app.

ver

string

The version of the app.

Publisher fields

BidRequest.app.publisher orBidRequest.site.publisher

The Publisher object describes the seller of the ad space (for the App or Site) in which the ad will be displayed.

For more details, refer to the IAB's OpenRTB 2.5 specification.

Field name Data type Description

cat

array (string)

The list of IAB content categories for the publisher.

For details, see the IAB's OpenRTB 2.5 specification.

Content fields

BidRequest.app.content orBidRequest.site.content

The Content object describes the type of content of the App or Site in which the ad will be displayed.

For more details about the Content object, refer to the IAB's OpenRTB 2.5 specification.

Field name Data type Description

cat

string

The list of IAB content categories for the content.

For details, see the IAB's OpenRTB 2.5 specification.

context

string

The type of content.

For details, see the IAB's OpenRTB 2.5 specification.

embeddable

integer

Indicates whether the content is embeddable (1) or not (0).

episode

integer

An episode number.

keywords

(recommended)

string

A comma-separated list of keywords describing the content.

language

string

Content language using ISO-639-1-alpha-2.

len

integer

The length of the content in seconds (if applicable).

livestream

integer
  • 0. Not a live stream

  • 1. Content is a live stream

season

string

The content's season.

series

string

The content's series.

sourcerelationship

integer
  • 0. Indirect relationship

  • 1. Direct relationship

title

string

The title of the content.

url

string

The URL where the content is located.

userating

string

User rating of the content.

videoquality

integer

The video quality classification.

For details, see the IAB's OpenRTB 2.5 specification.

Device fields

BidRequest.device

Each BidRequest object may contain a Device object, which provides details about the end-user's computing environment.

The Device object can reference the Geo object. Passing device.geo data can provide valuable information to buyers about where the device (and therefore, the user) is currently located.

Field name Data type Description
ua string

The HTTP user agent, which typically indicates the user’s browser.

For example: "Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_2; en-us)"

geo Geo object

An object containing properties that describe the geographic location of the user as derived from the device.

dnt integer

Do not track flag.

If the user’s web browser is set for private browsing, a dnt value of 1 is passed. If dnt has a value of 0, the browser is not set for private browsing.

lmt

(recommended)

integer

If the user’s mobile device is set for private browsing, the LMT (limit tracking) flag is passed.

  • 0 = false

  • 1 = true (the user does not want to be tracked.)

ip string

The ipv4 address closest to the user’s device.

For example: "238.122.7.1"

ipv6

string

The ipv6 address closest to the user’s device.

devicetype

(recommended)

integer

Indicates the detected device category for the user’s device as defined in the IAB's OpenRTB 2.5 specification.

Note: OpenX OpenRTB uses a devicetype value of 1001 to indicate text (SMS).

make string

The make for the user’s device.

For example: "Apple"

model string

The model for the user’s device.

For example: "iPhone"

os string

The operating system for the user’s device.

osv string

The version number for the user’s operating system.

hwv

string

The device's hardware version.

For example: "5S" (for iPhone 5S)

h

integer

The height of the device's screen, in pixels.

w

integer

The width of the device's screen, in pixels.

ppi

integer

The size of the device's screen expressed in pixels per inch.

pxratio

float

The ratio of device pixels to device-independent pixels.

js

integer

Indicates whether the device supports JavaScript (1) or not (0).

flashver

string

The version of Flash supported by the device's browser.

language string

The two letter code (ISO 639-1) for the user’s preferred browsing language on their device.

For example: "en"

carrier

(recommended)

string

Carrier or ISP using exchange-curated string names.

For example: "VERIZON"

mccmnc

(recommended)

string

Mobile carrier as the concatenated mobile country code-mobile network code, or MCC-MNC (for example, "310-005" identifies Verizon Wireless CDMA in the USA). Note that the dash between the MCC and MNC parts is required to remove parsing ambiguity. For a user-friendly list of codes, see https://en.wikipedia.org/wiki/Mobile_country_code.

connectiontype

(recommended)

integer

Indicates the detected data connection type for the user’s device as defined in the IAB's OpenRTB 2.5 specification.

ifa

(recommended)

string

ID for advertisers (also referred to as "IDFA").

This is the ID sanctioned for advertiser use in the clear (not hashed).

didsha1

(recommended)

string

The SHA-1 hash identifier for the user’s device, such as the UDID for an iOS device.

For example: 2b6f0cc904d137be2e1730235f5664094b831186

dpidsha1

(recommended)

string

The SHA-1 hash of the Android ID for the end-user's mobile device.

dpidmd5

(recommended)

string

The MD5 hash of the Android ID for the end-user's mobile device.

macsha1

(recommended)

string

The SHA-1 hash of the device's MAC address.

macmd5

(recommended)

string

The MD5 hash of the device's MAC address.

Geo fields

BidRequest.device.geo or BidRequest.user.geo

The Geo object provides details about the device's current location (via the Device object) or the location according to user-provided data (via the User object). Pass these values as device.geo or user.geo depending on which type of geo data you have.

Field name Data type Description
city string

City location (United Nations Code for Trade and Transport Locations).

For example: "los angeles"

country string

Country location expressed as an ISO 3166-1 alpha-3 code.

For example: "USA"

lat

(recommended)

float

Latitude.

For example: 33.684

lon

(recommended)

float

Longitude.

For example: -117.793

metro

string

Google metro code, which are similar to DMA codes.

region

string

Region code per ISO-3166-2 or the two-character state code in the U.S.

For example: "CA"

type

(recommended)

integer

Use this parameter to indicate the source of your lat and lon parameter values:

  • 1 (GPS/location services)
  • 2 (IP address)
  • 3 (user-provided)

utcoffset

integer

Device time as a positive or negative offset, in minutes, from UTC.

zip string

Postal code location. Values are not restricted to the U.S.

For example: "92602"

User fields

BidRequest.user

Each BidRequest object can contain a User object, which provides details about the end-user.

The User object can reference the user's Geo according to user-provided data about their location.

Field name Data type Description

data

array (Data object)

An array of Data objects to provide details about the user.

gender

string

The end-user's gender (M, F, or O).

geo

Geo object

An object containing properties that describe the user's primary location. User geo data should be used for user-provided location data. For the device's current location, use device.geo.

keywords

(recommended)

string

A comma-separated list of keywords describing the user's interests.

yob

integer

The end-user's four digit year of birth.

For example: 1972

User extensions object fields

BidRequest.user.ext

The optional Extensions object can provide additional user details.

Field name Data type Description

consent

string

Indicates that the user has consented to having his or her data collected by the publisher's site, as mandated by the GDPR. See the IAB's GDPR Consent String Specification for more information.

Data fields

The Data object provides details about the user.

Field name Data type Description
id string

A unique OpenX identifier for the data provider.

You can pass a value that may be included in the BidRequest.data.id field if its value is either publisher or it is prefixed with pub- followed by any value of your choosing.

For example: "pub-12345678".

Note: The conventions used by this field will change as OpenX supports additional sources of data.

name string

The name of the data provider.

segment array (Segment object)

A collection of Segment objects, each describing a particular data point available from this data provider.

Segment fields

BidRequest.user.data.segment

The Segment object provides data about the user.

Field name Data type Description
id string

The ID of the data segment specific to the data provider.

name string

The name of the data segment specific to the data provider.

For example: "gender", "dma", or "age"

value string

A string representation of the data segment value.

Regs object fields

BidRequest.regs

The Regs object provides details about any regulations applicable to the request.

Field name Data type Description

coppa

integer

Indicates whether the request is subject to Children’s Online Privacy Protection Act (COPPA) regulations.

ext

Extensions object

An object containing properties that describe custom fields for additional regulations.

Regs extensions object fields

BidRequest.regs.ext

The optional Extensions object can provide additional regulatory details.

Field name Data type Description

sb568

integer

Indicates whether the request is subject to California’s SB-568 regulations.

  • 0 = false

  • 1 = true (the request is subject to SB-568)

gdpr

integer

Indicates whether the request is subject to the General Data Protection Regulation (GDPR).

  • 0 = false

  • 1 = true (the request is subject to GDPR)