You are here: Developers > Ad Request API > Ad request parameters > OpenRTB supply-side ad request parameter values

OpenRTB supply-side ad request parameter values

Last updated on September 21, 2017

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.

Commonly-targeted OpenRTB fields

OpenX strongly recommends the following fields because many buyers target them:

  • BidRequest.app.bundle

  • BidRequest.app.name

  • BidRequest.imp.banner.api

  • BidRequest.imp.native.api

Recommended OpenRTB fields

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

 

Object name Field name Data type Description

BidRequest.app

bundle

string

The unique ID of the app's packageA bundle of targeting criteria for similar inventory segments which you can offer at a predetermined price (typically to facilitate regular sales efforts) and automatically create line items from in OpenX. (Android), bundle (iOS), or its AppStore ID.

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

BidRequest.app

cat array (string)

The list of IAB content categories for the app, as defined in the OpenRTB API specification

BidRequest.app

domain

string

Domain of the app

For example: yourapp.com

BidRequest.app

keywords string

A comma-separated list of keywords describing the app

BidRequest.app

name

string The name of the app
BidRequest.app storeurl string

The app store URL for this app

BidRequest.app.content keywords string

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

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

BidRequest.device

connectiontype

integer Indicates the detected data connection type for the user’s device as defined in the OpenRTB specification
BidRequest.device devicetype integer

Indicates the detected device category for the user’s device as defined in the OpenRTB API specification

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

BidRequest.device

didsha1

string

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

For example: 2b6f0cc904d137be2e1730235f5664094b831186

BidRequest.device

dpidmd5

string

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

BidRequest.device

dpidsha1

string

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

BidRequest.device

ifa

string

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

This is the ID sanctioned for advertiserIn OpenX, an account type that represents a business that runs advertising campaigns to display ads on websites. use in the clear (not hashed).

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

BidRequest.device

macmd5

string

The MD5 hash of the device's MAC address

BidRequest.device

macsha1

string

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

BidRequest.device.geo

lat

float

The user’s latitude

For example: 33.684

BidRequest.device.geo

lon

float

The user’s longitude

For example: -117.793

BidRequest.device.geo

type

integer

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

BidRequest.imp

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

BidRequest.imp.banner

api

 

array (integer)

One of the supported API standards or frameworks:

For example: 2

For details, see the OpenRTB API specification.

BidRequest.imp.native

api

 

array (integer)

One of the supported API standards or frameworks:

  • 2 - VPAID 2.0

  • 3 - MRAID 1.0

  • 4 - ORMMA

  • 5 - MRAID 2.0

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

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

BidRequest.site

keywords

string

A comma-separated list of keywords describing the site

BidRequest.site.content keywords string

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

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

lat

float

The user’s latitude

For example: 33.684

BidRequest.user.geo

lon

float

The user’s longitude

For example: -117.793

BidRequest.user.geo

type

integer

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

See also

Feedback form