You are here: Developers > Ad Request API > Ad request parameters

Ad request parameters

Last updated on June 7, 2017

OpenX uses parameter values (also known as "query args") during ad selection to target the most appropriate ads to your ad space. Depending on the type of ad requestCommunication from a web browser or app to an ad server to display an ad., OpenX may do one of the following:

  • Ignore parameters that are not applicable to the type of ad request. For example, the vmaxd video ad request parameter is ignored if included in an image ad request.

  • Return an error if one or more parameters are not valid for the ad request.

You can set parameters for your ad requests by including key-value pairs: key=value For example, auid=1234 specifies the ad unitThe smallest inventory component that represents the space on a site where ads display. ID, which is required in all standalone ad requests.

The following table describes the parameters that OpenX supports in its ad requests. Depending on the type of ad request that you are using, some of the parameters are required, while others are optional. Unless described as required, all parameters are optional (if applicable to the type of ad request) or ignored (when not applicable).

Note: The OpenX JavaScript Tag Library does not support all of the following parameters. For information about what parameters each method supports, see the corresponding reference page for the specific method.

Ad request parameters

Parameter

Description

auid

(Required) Ad unit ID, which indicates the unique ID for the ad unit where you want to serve an ad.

For example:

  • For a single ad unit: auid=1234
  • For multiple ad units: auid=1234,4321,9876
aus

Ad unit sizes. Indicates a comma-delimited list of available ad sizes.

To use this parameter, you must include additional ad unit sizes when you create your ad unit. For details, see flexible ad units.

For example: aus=728x90,970x90

c.key=value

Custom variable, communicates additional information about the ad space, such as details of app content, ad space location, or user-specific information.

For details, see custom variables in ad requests.

For example: c.gender=1

callback

Indicates the JavaScript function call with which to wrap the JSON structure using JSON with padding (JSONP) standards.

Required only for JSONP responses to /arj (JSONP) and /avj (video JSONP) requests.

cb

Cache bustingThe process whereby a random number is added to a banner’s HTML each time the page is reloaded. This results in the server being sent a separate banner request every time and guarantees that the banner is not cached, and therefore that ad impressions remain accurate. AKA “defeating cache.”. A dynamically-generated random number assigned to the request to avoid browser caching.

If you generate an HTML ad tagA small piece of code that defines the ad space where ads display on a website. It includes parameters that describe the inventory advertising campaigns can target, which may in turn display ads in the ad space. in the UI, OpenX includes the cb parameter in the ad tag as follows: cb=INSERT_RANDOM_NUMBER_HERE.

When implementing image and iFrame ad tags for HTML ad requests, replace the INSERT_RANDOM_NUMBER_HERE value with a random number, such as a timestamp or a number automatically generated by your CMS. If a user requests the same page again, the browser will invoke a new ad request rather than serving an ad from the cacheThis is a temporary storage area that houses frequently accessed data and keeps it ready for speedy access. This saves the computer from having to retrieve the information from main memory every time it’s required. In online terms, a cache can store much of a web page’s content instead of requesting all the data from the server again..

ch Character encoding. Indicates the character set for the current page.
cs

Client state. Indicates a unique ID for the ad unit and user to communicate between the click URL and the ad.

This parameter is required for image ad tags and ignored for all other types of ad requests.

This parameter only accepts values which use the following characters: a-z, A-Z, 0-9, _ (underscore), or - (hyphen).

ip

Client IP address

For example: 69.89.31.226

lat

Indicates the GPS latitude location, in decimal form, of the end-user. You should send the lt parameter with lat/lon.

For example: lat=37.530676

lon

Indicates the GPS longitude location, in decimal form, of the end-user. You should send the lt parameter with lat/lon.

For example: lon=-122.262447

lt

Indicates the source of the end-user's location data, which can be one of the following:

  • 1 (GPS/Location Services)
  • 2 (IP Address)
  • 3 (User Provided, e.g. a zip code on a website's registration form)

You should send the lt parameter with lat/lon.

For example: lt=1

Important: For 1 to be available for a mobile appSynonymous with mobile. Refers to the use of an app via a mobile device, specifically to differentiate from mobile web., two criteria must be met. The publisherAn account type that represents a business with ad space to sell. must enable sending location and source in the app, and the end-user must agree to allow location sharing with prompted by the app.

ltsrc Deprecated

Indicates the source of the user’s geographic location details.

If the ltsrc parameter has any value, the latitude and longitude are considered to have been derived from the device's GPS location. Otherwise, the latitude and longitude were derived from an IP address.

maxbitrate

Maximum bitrateThe quantity of data transmitted over time. For video and audio files, quality is measured by the bitrate, similarly to how image quality is measured by resolution. OpenX provides min and max bitrate settings, so that you can determine a balance between video quality (high bitrate) and load time (low bitrate).. For a video ad unit, indicates the maximum bitrate (in Kbps) of video ads that can serve.

Default: maxbitrate=4000

minbitrate

Minimum bitrate. For a video ad unit, indicates the minimum bitrate (in Kbps) of video ads that can serve.

Default: minbitrate=240

o

Indicates a random number assigned to the request that helps scope the response from the server.

This ensures that multiple server responses do not collide and is useful if you are writing your own synchronous JavaScript ad tags and do not use the OpenX JavaScript tag library.

For example, when you build your own tag library, send OpenX the required inputs, and parse its output.

This parameter is optional for JavaScript ad tags, mobile ad requests, mobile video ad requests, and video ad requests. It is ignored by other types of ad requests.

openrtb Specifies a string with supply-side OpenRTB data to be passed to OpenX Ad Exchange buyers.
pgid

Page ID. Indicates the unique ID for the predefined ad unit group.

This parameter is optional for JavaScript ad tags, mobile video ad requests, and video ad requests.

Note: Do not specify this parameter for iFrame or image ad requests. It will cause an error.

plg

Plugins. Indicates any plugins enabled in the user's browser, such as:

  • pdf (Adobe Acrobat Reader)

  • qt (QuickTime)

  • rp (Real Media Player)

  • shk (Adobe Shockwave)

  • sl (Silverlight)

  • swf (Flash)

  • wmp (Windows Media Player)

r, r0, r1, or r2

Redirect. Indicates the click redirect URL:

  • r is a single-escaped URL. For example:

    http%3A%2F%2Fwww.clickredirectURL.com%3Fsome%3D1%26others%3D2F
  • r0 is an unescaped URL. For example:

    http://www.clickredirectURL.com?some=1&others=2 
  • r1 is a single-escaped URL (same as r).

  • r2 is a double-escaped URL. For example:

    http%253A%252F%252Fwww.clickredirectURL.com%253Fsome%253D1%2526others%253D2

Note: Any of these redirect parameters must be the last parameter in an ad request URL or click URL string.

rc

Refresh count. Indicates the current number of refreshes for ads served through the ad tag, as counted by OpenX.

This parameter is not initially set in the ad tag. For image, iFrame, JavaScript, and video ad requests, OpenX adds it and then automatically sets it with each refresh. See also: Structured response.

For custom implementations, your client application adds it and sets it with each refresh.

rd

Refresh delay (in seconds) for refreshing an iFrame.

This value must be an integer ≥ 1. If you explicitly pass this parameter in an ad tag, OpenX ignores any server-side refresh delay setting for this ad unit (as set when creating or editing the ad unit or its container site).

ref

Referrer. Indicates the URL that directed the user to the current page.

Setting this parameter overrides any referrer information passed in the HTTP headers.

res Resolution. Indicates the screen resolution of the user's browser (screen width x height x color depth).
rm

Refresh max. Indicates the maximum number of refreshes for ads displayed through the ad request.

This value must be an integer ≥ 1.

For example, setting this parameter to a value of 5 would result in the display of a total of 6 ads (which includes the initial display of the ad (non-refresh) and the 5 subsequent displays of the ad (refreshes)). If you explicitly pass this parameter in an ad tag, OpenX ignores any server-side refresh max setting for this ad unit, as set when creating or editing the ad unit or its container site.

This optional parameter only applies to iFrame tags, JavaScript tags, and structured ad responses.

tfcd

Enables Child's Online Privacy Protection Act (COPPA) regulations.

  • 1 (COPPA regulations enabled)
  • 0 (COPPA regulations not enabled)

Refer to the OpenRTB API specification for more detailed information on COPPA compliance and regulations.

For example: tfcd=1

tg

Click target. Indicates the browser window target when a user clicks an ad on the page, which can be one of the following:

  • _blank (New window)

  • _parent (Parent window)

  • _self (Current window)

  • _top (Top window)

Note: This parameter is only used for image creatives that display in iFrame and JavaScript ad tags.

tid Topic ID. Indicates the content topicDescribes the main subject of the online content surrounding the ad space, such as sports or automotive. for the page.
tz Timezone. Indicates the time zone of the user's web browser.

url

Full HTTP path of the user's current page.

For example: http://yoursite.net/home.html

vbw

Video bandwidth. Indicates the maximum bandwidth for the video ad, in bits per second.

Use this parameter as an override for the ad unit setting.

vht

Video height. Indicates the expected height dimension of the video ad, in pixels.

Use this as an override for the ad unit setting.

For example: 320

vmaxd

Video maximum duration. Indicates the maximum length of the video ad, in seconds.

Use this as an override for the ad unit setting.

vos

Video out-streamA standalone video ad that is not within video content. It can present anywhere, for example, a video ad in your Facebook news feed.. Indicates video out-stream inventoryAd space available on a website or app. The basic unit of inventory for OpenX is an ad unit. when the following values are passed:

vrw

Video - Rewarded. Indicates the inventory is rewarded video, based on the following:

  • 1 (Yes)
  • 0 (No)

For example: vrw=1

vstrm

Video streaming protocol. Indicates the streaming protocol to use for the video ad.

Use this as an override for the ad unit setting.

vwd

Video width. Indicates the expected width dimension for the video ad, in pixels.

Use this as an override for the ad unit setting.

For example: 480

xid

User ID. Indicates the customer-provided user ID, if different from the Device ID.

For example: xid=234hskhjfdkhjs

The following types of ad request have their own parameters:

In addition, there are some parameters specific to certain OX instance and OX static methods.

Refer to the topics for each type of ad request for more information about how to incorporate these parameters in your specific ad requests.

If you are performing HTML ad requests with image, iFrame, or JavaScript ad tags, you may be able to specify various HTML attributes that are specific to the tag type that you are using. For example, for an image ad tag, this may include the border attribute. This guide does not go into detail about how to use common HTML attributes. For more information, refer to www.w3schools.com.

Note: In cases where a web browser is used to make an ad request, the browser may truncate the an ad request if the resulting URL exceeds its character limits. These limits vary by browser. Set required parameters first, then incorporate optional parameters in your tags.

Feedback form