OpenRTB supply-side ad request parameter values

Last updated on May 17, 2018

To better characterize your inventoryAd space available on a website or app. The basic unit of inventory for OpenX is an ad unit., you can send additional data about your ad units to buyers in the OpenX Ad Exchange using OpenRTB values. You do not need to pass all OpenRTB values because OpenX automatically identifies and passes many of them for you.

The openrtb ad requestCommunication from a web browser or app to an ad server to display an ad. parameter supports a percent-encoded string generated from JSON objects with supported OpenRTB values.

Sample openrtb parameter included in an ad request:

The following ad request shows how you can include various ad request parameters—including the openrtb parameter, which specifies a percent-encoded string.

http://delivery_server_domain/w/1.0/acj?
o=7889550390&callback=OX_7889550390&auid=537627288&res=320x568x32&plg=qt%2Cpm&ch=UTF-8&tz=420&ws=320x50&sd=1&openrtb=%7B%22cur%22%3A%20%5B%22USD%22%5D%2C%20%22site%22%3A
%20%7B%22publisher%22%3A%20%7B%
22domain%22%3A%20%22foobar.com%22%2C%20%22cat%22%3A%20%5B%22IAB3-1%22%5D%2C%20%22id%22%3A
%20%228953%22%2C%20%22name%22%
3A%20%22foobar.com%22%7D%2C%20%22domain%22%3A%20%22www.example.com%22%2C%20%22page%22%3A%20%22http
%3A//www.example.com/
1234.html%20%22%2C%20%22id%22%3A%20%22102855%22%2C%20%22cat%22%3A%20%5B%22IAB3-1%22%5D%7D%2C
%20%22imp%22%3A%20%5B%7B%
22banner%22%3A%20%7B%22h%22%3A%20250%2C%20%22pos%22%3A%200%2C%20%22w%22%3A%20300%7D%2C%20%22id
%22%3A%20%221%22%2C%20%
22bidfloor%22%3A%200.03%7D%5D%2C%20%22at%22%3A%201%2C%20%22device%22%3A%20%7B%22ip%22%3A
%20%22123.145.167.10%22%2C%20%
22ua%22%3A%20%22Mozilla/5.0%20%28Macintosh%3B%20Intel%20Mac%20OS%20X
%2010_6_8%29%20AppleWebKit/537.13%20%28KHTML%2C%
20like%20Gecko%29%20Version/5.1.7%20Safari/534.57.2%22%7D%2C%20%22id%22%3A
%20%2280ce30c53c16e6ede735f123ef6e32361bfc7b22
%22%2C%20%22user%22%3A%20%7B%22id%22%3A%20%2255816b39711f9b5acf3b90e313ed29e51665623f%22%7D%7D

Where:

  • http is the protocol. If your ad space uses SSL/TLS, use https instead.

  • delivery_server_domain. The hostname of your OpenX delivery server

  • /w. Indicates the web delivery medium

  • /1.0. Indicates version 1.0 of the OpenX ad request protocol

  • /acj. Asynchronous chain JSON, an asynchronous ad request to serve a structured JSON delivery response which supports chaining

  • ?. Separates the ad request from the ad request parameters

  • auid. The ad unitThe smallest inventory component that represents the space on a site where ads display. ID

  • &. Separates each parameter

  • &openrtb=. Indicates the OpenRTB values that follow in a percent-encoded string

Sample JSON object including OpenRTB values

The following JSON object shows the structure of the OpenRTB data before removing unnecessary white space and before percent encoding.


{'cur': ['USD'],
 'device': {'ip': '123.145.167.10',
             'ua': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/537.13 (KHTML, like Gecko) Version/5.1.7 Safari/534.57.2'},
 'id': '80ce30c53c16e6ede735f123ef6e32361bfc7b22',
 'imp': [{'banner': {'h': 250, 'pos': 0, 'w': 300},
           'bidfloor': 0.03,
           'id': '1'}],
 'site': {'cat': ['IAB3-1'],
          'domain': 'www.example.com',
          'id': '102855',
          'page': 'http://www.example.com/1234.html ',
          'publisher': {'cat': ['IAB3-1'],
                        'domain': 'example.com',
                        'id': '8953',
                        'name': 'example.com'}}}
       

Where:

To improve performance, remove all unneeded white space and line breaks from your JSON object before generating a percent-encoded version of it as shown in the following example.

JSON string prepared for percent-encoding:

{"cur": ["USD"], "site": {"publisher": {"domain": "example.com", "cat": ["IAB3-1"], "id": "8953", "name": "example.com"}, "domain": 
"www.example.com", "page": "http://www.example.com/1234.html ", "id": "102855", "cat": ["IAB3-1"]}, "imp": [{"banner": {"h": 250, 
"pos": 0, "w": 300}, "id": "1", "bidfloor": 0.03}], "device": {"ip": "123.145.167.10", "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 
10_6_8) AppleWebKit/537.13 (KHTML, like Gecko) Version/5.1.7 Safari/534.57.2"}, "id": "80ce30c53c16e6ede735f123ef6e32361bfc7b22"}

You can pass as many supported OpenRTB fields as you find useful to characterize your inventory except for those that cannot be passed by publishers.

Recommended OpenRTB fields

The following OpenRTB fields are recommended because they provide the most value to buyers.

For a complete list of fields that you can pass, see OpenRTB fields passed by publishers. Also, see OpenRTB fields not passed from publishers to understand which fields are auto-detected or, for other reasons, cannot be passed by publishers.

 

Object name Field name Data type Description

app

bundle

string

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

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

app

cat array (string)

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

app

domain

string

Domain of the app

For example: yourapp.com

app

keywords string

A comma-separated list of keywords describing the app

app

name

string The name of the app
app storeurl string

The app store URL for this app

app.content keywords string

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

device carrier string

The mobile carrier for the user's device as derived from the IP address and expressed by the mobile country code (MCC) and mobile network code (MCC-MNC)

For example: "310-410"

Ad Exchange buyers will expect an MCC-MNC code, so sending the name of the carrier may not be parsed correctly by the buyerA company that pays a demand partner to purchase ad inventory on OpenX Ad Exchange.'s system.

device

connectiontype

integer Indicates the detected data connection type for the user’s device as defined in the IAB's OpenRTB 2.5 specification
device devicetype 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).

device

didsha1

string

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

For example: 2b6f0cc904d137be2e1730235f5664094b831186

device

dpidmd5

string

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

device

dpidsha1

string

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

device

ifa

string

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

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

device

lmt

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.)

device

macmd5

string

The MD5 hash of the device's MAC address

device

macsha1

string

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

device.geo

lat

float

The device’s latitude.

For example: 33.68424

device.geo

lon

float

The device’s longitude.

For example: -117.79312

device.geo

type

integer

Indicates the source of the user’s geographic location details, as defined in the IAB's OpenRTB 2.5 specification. For example, this field can indicate whether the lat or lon is derived from the device's GPS location or an IP address.

imp

displaymanager string The name of the mediation partner or other third party responsible for rendering the ad

imp.banner

api

 

array (integer)

One of the supported API standards or frameworks:

For example: 2

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

regs

coppa

integer

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

  • 0 = false

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

regs.ext

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)

regs.ext

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)

site

keywords

string

A comma-separated list of keywords describing the site

site.content keywords string

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

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

lat

float

The user’s latitude.

For example: 37.530676

user.geo

lon

float

The user’s longitude.

For example: -122.262447

user.geo

type

integer

Indicates the source of the user’s geographic location details, as defined in the IAB's OpenRTB 2.5 specification. For example, this field can indicate whether the lat or lon is derived from the device's GPS location or an IP address.

user.ext.consent

consent

string

Indicates that the user has consented to having his or her data collected by the publisherAn account type that represents a business with ad space to sell.'s site, as mandated by the GDPR. See the IAB's GDPR Consent String Specification for more information.