API Reference OpenRtbEcto v0.1.3

Modules

Ecto schemas for OpenRTB 2.0 & 3.0 according to the following specifications

In some cases, partners will send boolean values in the JSON payloads for fields that are defined as integers in the spec. This type can handle those cases and properly cast the values.

The top-level bid request object contains a globally unique bid request or auction ID. This id attribute is required as is at least one impression object (Section 3.2.4). Other attributes in this top-level object establish rules and restrictions that apply to all impressions being offered.

This object should be included if the ad supported content is a non-browser application (typically in mobile) as opposed to a website. A bid request must not contain both an App and a Site object. At a minimum, it is useful to provide an App ID or bundle, but this is not strictly required.

This object represents an audio type impression. Many of the fields are non-essential for minimally viable transactions, but are included to offer fine control when needed. Audio in OpenRTB generally assumes compliance with the DAAST standard. As such, the notion of companion ads is supported by optionally including an array of Banner objects (refer to the Banner object in Section 3.2.6) that define these companion ads.

This object represents the most general type of impression. Although the term “banner” may have very specific meaning in other contexts, here it can be many things including a simple static image, an expandable ad unit, or even in-banner video (refer to the Video object in Section 3.2.7 for the more generalized and full featured video ad units). An array of Banner objects can also appear within the Video to describe optional companion ads defined in the VAST specification.

This object describes the content in which the impression will appear, which may be syndicated or nonsyndicated content. This object may be useful when syndicated content contains impressions and does not necessarily match the publisher’s general content. The exchange might or might not have knowledge of the page where the content is running, as a result of the syndication method. For example might be a video impression embedded in an iframe on an unknown web property or device.

The data and segment objects together allow additional data about the related object (e.g., user, content) to be specified. This data may be from multiple sources whether from the exchange itself or third parties as specified by the id field. A bid request can mix data objects from multiple providers. The specific data providers in use should be published by the exchange a priori to its bidders.

This object constitutes a specific deal that was struck a priori between a buyer and a seller. Its presence with the Pmp collection indicates that this impression is available under the terms of that deal. Refer to Section 7.3 for more details.

This object provides information pertaining to the device through which the user is interacting. Device information includes its hardware, platform, location, and carrier data. The device can refer to a mobile handset, a desktop computer, set top box, or other digital device.

This object represents an allowed size (i.e., height and width combination) or Flex Ad parameters for a banner impression. These are typically used in an array where multiple sizes are permitted. It is recommended that either the w/h pair or the wratio/hratio/wmin set (i.e., for Flex Ads) be specified.

This object encapsulates various methods for specifying a geographic location. When subordinate to a Device object, it indicates the location of the device which can also be interpreted as the user’s current location. When subordinate to a User object, it indicates the location of the user’s home base (i.e., not necessarily their current location).

This object describes an ad placement or impression being auctioned. A single bid request can include multiple Imp objects, a use case for which might be an exchange that supports selling all ad positions on a given page. Each Imp object has a required ID so that bids can reference them individually.

This object is associated with an impression as an array of metrics. These metrics can offer insight into the impression to assist with decisioning such as average recent viewability, click-through rate, etc. Each metric is identified by its type, reports the value of the metric, and optionally identifies the source or vendor measuring the value.

This object represents a native type impression. Native ad units are intended to blend seamlessly into the surrounding content (e.g., a sponsored Twitter or Facebook post). As such, the response must be well-structured to afford the publisher fine-grained control over rendering.

This object is the private marketplace container for direct deals between buyers and sellers that may pertain to this impression. The actual deals are represented as a collection of Deal objects. Refer to Section 7.3 for more details.

This object defines the producer of the content in which the ad will be shown. This is particularly useful when the content is syndicated and may be distributed through different publishers and thus when the producer and publisher are not necessarily the same entity.

This object describes the publisher of the media in which the ad will be displayed. The publisher is typically the seller in an OpenRTB transaction.

This object contains any legal, governmental, or industry regulations that apply to the request. The coppa flag signals whether or not the request falls under the United States Federal Trade Commission’s regulations for the United States Children’s Online Privacy Protection Act (“COPPA”).

Segment objects are essentially key-value pairs that convey specific units of data. The parent Data object is a collection of such values from a given data provider. The specific segment names and value options must be published by the exchange a priori to its bidders.

This object should be included if the ad supported content is a website as opposed to a non-browser application. A bid request must not contain both a Site and an App object. At a minimum, it is useful to provide a site ID or page URL, but this is not strictly required.

This object describes the nature and behavior of the entity that is the source of the bid request upstream from the exchange. The primary purpose of this object is to define post-auction or upstream decisioning when the exchange itself does not control the final decision. A common example of this is header bidding, but it can also apply to upstream server entities such as another RTB exchange, a mediation platform, or an ad server combines direct campaigns with 3rd party demand in decisioning.

This object contains information known or derived about the human user of the device (i.e., the audience for advertising). The user id is an exchange artifact and may be subject to rotation or other privacy policies. However, this user ID must be stable long enough to serve reasonably as the basis for frequency capping and retargeting.

This object represents an in-stream video impression. Many of the fields are non-essential for minimally viable transactions, but are included to offer fine control when needed. Video in OpenRTB generally assumes compliance with the VAST standard. As such, the notion of companion ads is supported by optionally including an array of Banner objects (refer to the Banner object in Section 3.2.6) that define these companion ads.

This object is the top-level bid response object (i.e., the unnamed outer JSON object). The id attribute is a reflection of the bid request ID for logging purposes. Similarly, bidid is an optional response tracking ID for bidders. If specified, it can be included in the subsequent win notice call if the bidder wins. At least one seatbid object is required, which contains at least one bid for an impression. Other attributes are optional.

A SeatBid object contains one or more Bid objects, each of which relates to a specific impression in the bid request via the impid attribute and constitutes an offer to buy that impression for a given price.

A bid response can contain multiple SeatBid objects, each on behalf of a different bidder seat and each containing one or more individual bids. If multiple impressions are presented in the request, the group attribute can be used to specify if a seat is willing to accept any impressions that it can win (default) or if it is only interested in winning any if it can win them all as a group.

Bid Request Payload

The request object contains minimal high level attributes (e.g., its ID, test mode, auction type, maximum auction time, buyer restrictions, etc.) and subordinate objects that cover the source of the request and the actual offer of sale. The latter includes the item(s) being offered and any applicable deals.

This object constitutes a specific deal that was struck a priori between a seller and a buyer. Its presence indicates that this item is available under the terms of that deal.

This object represents a unit of goods being offered for sale either on the open market or in relation to a private marketplace deal. The id attribute is required since there may be multiple items being offered in the same bid request and bids must reference the specific item of interest. This object interfaces to Layer-4 domain objects for deeper specification of the item being offered (e.g., an impression).

This object is associated with an item as an array of metrics. These metrics can offer insight to assist with decisioning such as average recent viewability, click-through rate, etc. Each metric is identified by its type, reports the value of the metric, and optionally identifies the source or vendor measuring the value.

The Request object contains a globally unique bid request ID. This id attribute is required as is an Item array with at least one object (i.e., at least one item for sale). Other attributes establish rules and restrictions that apply to all items being offered. This object also interfaces to Layer-4 domain objects for context such as the user, device, site or app, etc.

This object carries data about the source of the transaction including the unique ID of the transaction itself, source authentication information, and the chain of custody.

The response object contains minimal high level attributes (e.g., reference to the request ID, bid currency, etc.) and an array of seat bids, each of which is a set of bids on behalf of a buyer seat.

A Seatbid object contains one or more Bid objects, each of which relates to a specific item in the bid request offer via the “item” attribute and constitutes an offer to buy that item for a given price.

This object constitutes a buyer defined key/value pair used to inject dynamic values into media markup. While they apply to any media markup irrespective of how it is conveyed, the principle use case is for media that was uploaded to the exchange prior to the transaction (e.g., pre-registered for creative quality review) and referenced in bid. The full form of the macro to be substituted at runtime is ${CUSTOM_KEY}, where “KEY” is the name supplied in the key attribute. This ensures no conflict with standard OpenRTB macros.

This object is the bid response object under the Openrtb root. Its id attribute is a reflection of the bid request ID. The bidid attribute is an optional response tracking ID for bidders. If specified, it will be available for use in substitution macros placed in markup and notification URLs. At least one Seatbid object is required, which contains at least one Bid for an item. Other attributes are optional.

A bid response can contain multiple Seatbid objects, each on behalf of a different buyer seat and each containing one or more individual bids. If multiple items are presented in the request offer, the package attribute can be used to specify if a seat is willing to accept any impressions that it can win (default) or if it is interested in winning any only if it can win them all as a group.