Contact support
    • Monetization
    • Developer documentation
    • Supply inventory
    • Supply inventory with server-side header bidding

    Open RTB API integration: bid request specification (2)

    Table of Contents

    Overview Geo object Banner object Banner MIME types Video object Audio object Native object Publisher object Format object Content object Data object Segment object Producer object Channel object Network object

    Overview

    Equativ provides an OpenRTB API for suppliers which is able to receive OpenRTB bid requests. Equativ then runs an auction for each request so Equativ’s demand partners can bid on the opportunity. This article contains the bid request specification (part 2).

    Geo object

    OpenRTB field Data type Necessity Description
    country STRING OPTIONAL The country code following ISO-3166-1 Alpha-3.
    lat FLOAT OPTIONAL The latitude from -90 to 90, where negative is south. The parameter should be passed only if it is known to be accurate.
    lon FLOAT OPTIONAL The longitude from -180 to 180, where west is negative. The parameter should be passed only if it is known to be accurate.
    type INTEGER OPTIONAL The type of geo data source (GPS, IP address, user provided), to be provided when lat / lon is provided. Potential values available here.
    zip STRING OPTIONAL The zip/postal code.

    Banner object

    Bid responses take into account and respond with the bid.adm attribute, which is formatted according to the imp.banner.mimes received in the bid request on which the bid is being made. If not specified, the default value is "text/javascript". 

    It is recommended to use the same MIME type for all banner objects in the same bid request. 

    Example bid.adm attribute for a request MIMEs list including the MIME type "text/javascript" (the adm is an HTML snippet including Equativ’s JavaScript <script> tags; it is intended to be inserted into the DOM): "adm": "<script>document.write("<DIV/>");<script><!-- more creative HTML -->" 

    Example bid.adm attribute for a request MIMEs list including the MIME type "text/html" (the adm is an HTML snippet excluding all of Equativ’s JavaScript <script> tags; it is intended to be inserted into the DOM): "adm": "<img src='…'><!-- more creative HTML -->"" 

    Other MIMEs (or no MIMEs at all) received via imp.banner.mimes are not supported and responses will default in the manner of "text/javascript".

    OpenRTB field Data type Necessity Description
    api INTEGER ARRAY   RECOMMENDED   A list of supported API frameworks for the given impression. If an API is not explicitly listed, it is assumed not to be supported.
    format OBJECT ARRAY RECOMMENDED An array of format objects (section 3.2.10 in the OpenRTB specification) representing the banner sizes permitted. If none are specified, then use of the h and w fields is highly recommended.
    h INTEGER OPTIONAL The height of the impression in pixels. For each size in the format array, an impression object is created. If the format array is empty, the w/h fields are used to create an impression object.
    pos INTEGER OPTIONAL The ad position (possible values in section 5.4 in the OpenRTB specification).
    w INTEGER OPTIONAL The width of the impression in pixels. For each size in the format array, an impression object is created. If the format array is empty, the w/h fields are used to create an impression object.

    Video object

    OpenRTB field Data type Necessity Description
    api INTEGER ARRAY OPTIONAL A list of supported API frameworks for the given impression. If an API is not explicitly listed, it is assumed not to be supported.
    battr INTEGER ARRAY OPTIONAL The blocked creative attributes. If blank, it is assumed that all types are allowed.
    ext.rewarded INTEGER OPTIONAL A custom field for rewarded videos used prior to OpenRTB 2.6. This field is obsolete - using imp.rwdd (as specified in OpenRTB 2.6) instead is strongly recommended.
    h INTEGER RECOMMENDED The height of the player in pixels; strongly recommended.
    linearity INTEGER OPTIONAL A field indicating if the ad impression is linear or non-linear.
    maxduration INTEGER RECOMMENDED The maximum video ad duration in seconds.
    mimes STRING ARRAY REQUIRED

    The supported content MIME types. Popular MIME types:

    • video/x-ms-wmv for Windows Media
    • video/x-flv for Flash Video
    minduration INTEGER RECOMMENDED The minimum video ad duration in seconds.
    placement INTEGER REQUIRED The placement type for the impression (In-Stream, In-Banner, In-Article, In-Feed, Interstitial/Slider/Floating).
    playbackmethod INTEGER OPTIONAL The playback methods that may be in use. If none are specified, any method may be used. In practice, only the first method is used.
    plcmt INTEGER REQUIRED The placement type for the impression. Refer to Plcmt Subtypes - Video in the AdCOM 1.0 specification.
    pos INTEGER OPTIONAL The ad position.
    skip INTEGER RECOMMENDED

    A field indicating if the player will allow the video to be skipped.

    • 1 - skipping is allowed
    • 0 - skipping is not allowed
    startdelay INTEGER RECOMMENDED A field indicating the start delay in seconds for preroll, midroll or postroll ad placement.
    w INTEGER RECOMMENDED The width of the player in pixels; strongly recommended.

    Audio object

    If a demand partner of Equativ is not capable of reading an audio object, the audio object will be converted into a video object with audio mime types.

    OpenRTB field Data type Necessity Description
    api INTEGER ARRAY OPTIONAL A list of supported API frameworks for the given impression. If an API is not explicitly listed, it is assumed not to be supported.
    delivery INTEGER ARRAY OPTIONAL The supported delivery methods (e.g. streaming, progressive). If none are specified, support of all delivery methods is assumed.
    maxbitrate INTEGER OPTIONAL The maximum bit rate in Kbps.
    maxduration INTEGER RECOMMENDED The maximum audio ad duration in seconds.
    maxextended INTEGER OPTIONAL

    The maximum extended ad duration if extension is allowed.

    • -1 - the extension is allowed and there is no time limit imposed
    • 0 or blank - the extension is not allowed
    • > 0 - the value represents the number of seconds of extended play supported beyond the maxduration value
    mimes STRING ARRAY REQUIRED The supported content MIME types (e.g. “audio/mp4”).
    minbitrate INTEGER OPTIONAL The minimum bit rate in Kbps.
    minduration INTEGER RECOMMENDED The minimum audio ad duration in seconds.
    protocols INTEGER ARRAY RECOMMENDED An array of supported audio protocols.
    startdelay INTEGER RECOMMENDED A field indicating the start delay in seconds for pre-roll, mid-roll or post-roll ad placements.

    Native object

    Equativ supports the OpenRTB Dynamic Native Ads API Specification v 1.2 and strongly recommends compliance with this specification. Native requests and creatives are both serialized as strings (See Native bid request sample / Native bid response sample in OpenRTB API integration: samples). 

    To reach maximum demand, compatibility with the main campaign types used by the main native demand DSPs is strongly recommended. For native display campaigns, min. 4 assets should be supported:

    1. main image (img)
    2. title or description (title or data)
    3. icon or CTA (img or data)
    4. sponsored (data)

    For native display app install campaigns, min. 6 assets should be supported:

    1. main image or icon (image or data)
    2. title
    3. description (data)
    4. CTA (data)
    5. price and/or rating (data and/or data)
    6. sponsored (data)

    The following fields (all requiring Native Ads v 1.2) are required for all campaign types in addition to the asset/elements mentioned above:

    • native.privacy (privacy field)
    • plcmttype (placement type)
    • native.eventtrackers requiring support for at least
      • event = 1 (impression) and method = 1 (img) - and
      • event = 1 (impression) and method = 2 (js)

    The field context is recommended. As stated in Native Ads v 1.2, it is strongly recommended to use minimum values for the width/height (wmin/hmin) of image assets (e.g. for main image, asset type 3), as demand campaigns may use the same ratio but higher resolution assets and may not bid on fixed measurements (w/h) that would otherwise be compatible. This and other required/recommended elements above may cumulatively impact the majority of monetization. Native video is not supported at this time.

    Publisher object

    OpenRTB field Data type Necessity Description
    id INTEGER REQUIRED The publisher ID on the exchange; ⚠️ must be the Network ID of the account at Equativ. See "Authentication" in Open RTB API integration: get started for an alternative method to pass the Network ID.

    Format object

    OpenRTB field Data type Necessity Description
    h INTEGER REQUIRED The height in device independent pixels (DIPS).
    w INTEGER REQUIRED The width in device independent pixels (DIPS).

    Content object

    OpenRTB field Data type Necessity Description
    album STRING OPTIONAL The album the content belongs; typically for audio.
    artist STRING OPTIONAL The artist credited with the content.
    cat STRING ARRAY OPTIONAL An array of IAB content categories that describe the content producer.
    cattax INTEGER   OPTIONAL   The taxonomy in use. Default is 1.
    channel OBJECT   OPTIONAL The channel of the content in which the ad will be shown.
    contentrating STRING OPTIONAL The content rating (e.g.: MPAA).
    context INTEGER OPTIONAL The type of content (game, video, text, etc.).
    data OBJECT ARRAY OPTIONAL Additional content data. Each Data object represents a different data source.
    embeddable INTEGER   OPTIONAL

    A field indicating if the content is embeddable (e.g.: an embeddable video player).

    • 1 - content is embeddable
    • 0 - content is not embeddable
    episode INTEGER OPTIONAL The episode number.
    genre STRING OPTIONAL The genre that best describes the content (e.g., rock, pop, etc).
    id STRING OPTIONAL An ID uniquely identifying the content.
    isr STRING OPTIONAL The International Standard Recording Code conforming to ISO3901.
    keywords STRING OPTIONAL A comma-separated list of keywords describing the content.
    kwarray STRING ARRAY   OPTIONAL   A comma separated list of keywords describing the content. Only one of keywords or kwarray may be present.
    langb STRING   OPTIONAL   The content language using IETF BCP 47. Only one of language or langb may be present.
    language STRING OPTIONAL The content language using ISO-639-1-alpha-2.
    len INTEGER   OPTIONAL The length of the content in seconds; appropriate for video or audio.
    livestream INTEGER   OPTIONAL

    A field indicating if the given content is live content.

    • 1 - content is live (e.g.: stream, live blog)
    • 0 - content is not live
    network OBJECT   OPTIONAL   The network of the content in which the ad will be shown.
    producer OBJECT   OPTIONAL   The producer of the content in which the ad will be shown.
    prodq INTEGER OPTIONAL The production quality.
    qagmediarating INTEGER OPTIONAL The media rating per IQG guidelines.
    season STRING OPTIONAL The content season (e.g.: “Season 3”).
    series STRING OPTIONAL A content series. Video examples: “The Office” (television), “Star Wars” (movie), or “Arby ‘N’ The Chief” (made for web). Non-video Example: “Ecocentric” (Time Magazine blog).
    sourcerelationship INTEGER   OPTIONAL

    The relationship to the content source.

    • 1 - relation is direct
    • 0 - relation is indirect
    title STRING OPTIONAL The content title. Video examples: “Search Committee” (television), “A New Hope” (movie), or “Endgame” (made for web). Non-video example: “Why an Antarctic Glacier Is Melting So Quickly” (Time magazine article).
    url STRING OPTIONAL The URL of the content, for buy-side contextualization or review.
    userrating STRING OPTIONAL The user rating of the content (e.g.: number of stars, likes, etc.).

    Data object

    OpenRTB field Data type Necessity Description
    id STRING OPTIONAL An exchange-specific ID for the data provider.
    name STRING OPTIONAL An exchange-specific name for the data provider.
    segment OBJECT ARRAY OPTIONAL An array of Segment objects that contain the actual data values.

    Segment object

    OpenRTB field Data type Necessity Description
    id STRING OPTIONAL The ID of the data segment specific to the data provider.
    name STRING OPTIONAL The name of the data segment specific to the data provider.
    value STRING OPTIONAL The string representation of the data segment value.

    Producer object

    OpenRTB field Data type Necessity Description
    cat STRING ARRAY   OPTIONAL   An array of IAB content categories that describe the content producer.
    cattx INTEGER   OPTIONAL   The taxonomy in use. Default is 1.
    domain STRING   OPTIONAL   The highest level domain of the content producer (e.g. “producer.com”).
    ext OBJECT   OPTIONAL   A placeholder for exchange-specific extensions to OpenRTB.
    id STRING   OPTIONAL   The content producer or originator ID. Useful if content is syndicated and may be posted on a site using embed tags.
    name STRING OPTIONAL   The ID of the bidder seat on whose behalf this bid is made.

    Channel object

    OpenRTB field Data type Description
    domain STRING   The primary domain of the channel (e.g. "https://abc7ny.com" in case of the local channel WABC-TV). It is recommended to include the top private domain (PSL+1) for DSP targeting normalization purposes.
    ext OBJECT   A placeholder for exchange-specific extensions to OpenRTB.
    id STRING   A unique identifier assigned by the publisher. This may not be a unique identifier across all supply sources.
    name STRING The channel the content is on (e.g. a local channel like “WABC-TV").

    Network object

    OpenRTB field Data type Description
    domain STRING   The primary domain of the network (e.g. “abc.com” in case of the network ABC). It is recommended to include the top private domain (PSL+1) for DSP targeting normalization purposes.
    ext OBJECT   A placeholder for exchange-specific extensions to OpenRTB.
    id STRING   A unique identifier assigned by the publisher. This may not be a unique identifier across all supply sources.
    name STRING The network the content is on (e.g. a TV network like “ABC").

    RELATED ARTICLES