> For the complete documentation index, see [llms.txt](https://support.gamoshi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.gamoshi.com/gamoshi-wiki/general-information/gamoshi-open-rtb-specification.md). # Gamoshi Open RTB Specification This document outlines the information and guidelines advertisers and publishers need to implement an OpenRTB integration with Gamoshi. ## 1. Introduction Gamoshi provides cloud-based programmatic advertising infrastructure and technology, offering advertisers and publishers advanced, robust technology wrapped in easy-to-use services that support a diversity of business scenarios and media types. This document describes how to integrate with the Gamoshi platform via the OpenRTB protocol. ### 1.1 What Is Real-Time Bidding? Real-Time Bidding is an auction-based model in which ad impressions are bought and sold, with transactions taking place in the blink of an eye. Once an advertiser's bid wins the auction, their digital ad is shown instantly on the publisher's website or property. RTB auctions focus on impression-based bidding, whereas static auctions tend to group impressions and allow advertisers to bid only on packages. ### 1.2 How Does Real-Time Bidding Work? When a user visits a website/app, a corresponding bid request is sent to the platform the supply source is connected with via an RTB endpoint. This bid request contains various types of information, such as demographic data, location information, and browser history. The platform then passes the bid requests to its list of connected advertisers/buyers, who bid in real time for the ad impression as it's presented to the website/app user. The advertiser that bids the highest amount wins the impression and has its ad served to the site/app user. This process repeats for every ad unit of the website/app property page, and takes place within 100 milliseconds, including receiving the bid request and serving the ad. ### 1.3 Gamoshi Supported Scenarios Banners, Videos, and Native, across mobile (in-app), desktop, and mobile web. ### 1.4 Gamoshi OpenRTB Supported Versions 2.3 – 2.6 ### 1.5 Gamoshi Servers Location * **Google GCS:** Berkeley County, South Carolina. * **Amazon:** US East (Ohio), Asia Pacific (Singapore), Europe (Frankfurt). The Gamoshi RTB platform follows the standards set by OpenRTB version 2.5/2.6. OpenRTB ad requests are communicated via the endpoint below. ### 1.6 Gamoshi Publisher Endpoint URL `https://rtb.gamoshi.io/r//bidr` {% hint style="info" %} This document lays out ad requests, response structures, object specifications, and request parameters specific to Gamoshi. We recommend also referring to the guidelines in the OpenRTB API Specification v2.5 documentation. {% endhint %} ## 2. Bid Request ### 2.1 Bid Request Specification The details below specify the request parameters that Gamoshi supports, following the IAB OpenRTB API Specification v2.5. #### Object: Bid Request | **Attribute** | **Type** | **Description** | | ------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | string; required | Unique ID of the bid request, provided by the exchange. | | imp | object array; required | Array of Imp objects representing the impressions offered. At least 1 Imp object is required. | | site | object; recommended | Details via a Site object about the publisher's website. Only applicable and recommended for websites. | | app | object; recommended | Details via an App object about the publisher's app (i.e., non-browser applications). Only applicable and recommended for apps. | | device | object; recommended | Details via a Device object about the user's device to which the impression will be delivered. | | user | object; recommended | Details about the human user of the device via a User object, the advertising audience. | | test | integer; default 0 | Indicator of test mode, in which auctions are not billable. 0 = live mode, 1 = test mode. | | at | integer; default 2 | Auction type. 1 = First Price, 2 = Second Price Plus. Exchange-specific auction types can be defined using values greater than 500. | | tmax | integer | Maximum time in milliseconds the exchange allows for bids to be received, including internet latency, to avoid a timeout. This value supersedes any a priori guidance from the exchange. | | wseat | string array | Whitelist of buyer seats (e.g., advertisers, agencies) allowed to bid on this impression. Seat IDs must be coordinated between bidders and the exchange in advance. At most, only one of wseat and bseat should be used per request. Omission of both implies no seat restrictions. | | bseat | string array | Block list of buyer seats (e.g., advertisers, agencies) restricted from bidding on this impression. | | allimps | integer; default 0 | Flag indicating whether the exchange can verify that the impressions offered represent all impressions available in context (e.g., all on the web page, all video spots such as pre-, mid-, and post-roll), to support road-blocking. 0 = no or unknown, 1 = yes. | | cur | string array | Array of allowed currencies for bids on this bid request, using ISO-4217 alpha codes. Recommended only if the exchange accepts multiple currencies. | | wlang | string array | Whitelist of languages for creatives, using ISO-639-1-alpha-2. Omission implies no specific restrictions, but buyers should consider the language attribute in the Device and/or Content objects if available. | | bcat | string array | Blocked advertiser categories, using the IAB content categories (List 5.1). | | badv | string array | Block list of advertisers by their domains (e.g., "ford.com"). | | bapp | string array | Block list of applications by their platform-specific, exchange-independent application identifiers. On Android, bundle or package names (e.g., com.foo.mygame); on iOS, numeric IDs. | | source | object | A Source object providing data about the inventory source and which entity makes the final decision. | | regs | object | A Regs object specifying any industry, legal, or governmental regulations in force for this request. | | ext | object | Placeholder for exchange-specific extensions to OpenRTB. | #### Object: Source | **Attribute** | **Type** | **Description** | | ------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------- | | fd | Integer; recommended | Entity responsible for the final impression sale decision. 0 = exchange, 1 = upstream source. | | tid | string; recommended | Transaction ID that must be common across all participants in this bid request (e.g., across multiple exchanges). | | pchain | string; recommended | Payment ID chain string, containing embedded syntax described in the TAG Payment ID Protocol v1.0. | | ext | object | Placeholder for exchange-specific extensions to OpenRTB. | #### Object: Regs | **Attribute** | **Type** | **Description** | | ------------- | -------- | ------------------------------------------------------------------------------------------------------------ | | coppa | integer | Flag indicating if this request is subject to COPPA regulations established by the USA FTC. 0 = no, 1 = yes. | | ext | object | Placeholder for exchange-specific extensions to OpenRTB. | #### Object: Imp | **Attribute** | **Type** | **Description** | | ----------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | string; required | A unique identifier for this impression within the context of the bid request (typically starts at 1 and increments). | | metric | object array | An array of Metric objects. | | banner | object | A Banner object; required if this impression is offered as a banner ad opportunity. | | video | object | A Video object; required if this impression is offered as a video ad opportunity. | | audio | object | Currently not supported. | | native | object | A Native object; required if this impression is offered as a native ad opportunity. | | pmp | object | A Pmp object containing any private marketplace deals in effect for this impression. | | displaymanager | string | Name of the ad mediation partner, SDK technology, or player responsible for rendering the ad (typically video or mobile). Used by some ad servers to customize ad code by partner. Recommended for video and/or apps. | | displaymanagerver | string | Version of the ad mediation partner, SDK technology, or player responsible for rendering the ad. Recommended for video and/or apps. | | instl | integer; default 0 | 1 = the ad is interstitial or full screen, 0 = not interstitial. | | tagid | string | Identifier for the specific ad placement or ad tag used to initiate the auction. Useful for debugging or optimization by the buyer. | | bidfloor | float; default 0 | Minimum bid for this impression, expressed in CPM. | | bidfloorcur | string; default "USD" | Currency, specified using ISO-4217 alpha codes. May differ from the bid currency returned by the bidder, if allowed by the exchange. | | clickbrowser | integer | Indicates the type of browser that opens when the creative is clicked in an app: 0 = embedded, 1 = native. (Safari View Controller on iOS 9.x is considered native for this attribute.) | | secure | integer | Flag indicating whether the impression requires secure HTTPS URL creative assets and markup. 0 = non-secure, 1 = secure. If omitted, the secure state is unknown, but non-secure HTTP support can be assumed. | | iframebuster | string array | Array of exchange-specific names of supported iframe busters. | | exp | integer | Advisory as to the number of seconds that may elapse between the auction and the actual impression. | | ext | object | Placeholder for exchange-specific extensions to OpenRTB. | #### Object: Metric | **Attribute** | **Type** | **Description** | | ------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | type | string; required | Type of metric being presented, using exchange-curated string names, which should be published to bidders a priori. | | value | float; required | Number representing the value of the metric. Probabilities must be in the range 0.0–1.0. | | vendor | string; recommended | Source of the value, using exchange-curated string names. If the exchange itself is the source rather than a third party, "EXCHANGE" is recommended. | | ext | object | Placeholder for exchange-specific extensions to OpenRTB. | #### Object: Banner | **Attribute** | **Type** | **Description** | | ------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | format | object array; recommended | Array of Format objects representing the permitted banner sizes. If none are specified, use of the h and w attributes is highly recommended. | | w | integer | Exact width in device-independent pixels (DIPS); recommended if no format objects are specified. | | h | integer | Exact height in device-independent pixels (DIPS); recommended if no format objects are specified. | | btype | integer array | Blocked banner ad types (List 5.2). | | battr | integer array | Blocked creative attributes (List 5.3). | | pos | integer | Ad position on screen (List 5.4). | | mimes | string array | Content MIME types supported. Popular types may include "application/x-shockwave-flash", "image/jpg", and "image/gif". | | topframe | integer | Indicates whether the banner is in the top frame rather than in an iframe. 0 = no, 1 = yes. | | expdir | integer array | Directions in which the banner may expand (List 5.5). | | api | integer array | List of supported API frameworks for this impression (List 5.6). If an API is not explicitly listed, it's assumed not to be supported. | | id | string | Unique identifier for this banner object. Recommended when Banner objects are used with a Video object to represent an array of companion ads. Values usually start at 1 and increase with each object; unique within an impression. | | vcm | integer | Relevant only for Banner objects used with a Video object in an array of companion ads. Indicates the companion banner rendering mode relative to the associated video. 0 = concurrent, 1 = end-card. | | ext | object | Placeholder for exchange-specific extensions to OpenRTB. | #### Object: Video | **Attribute** | **Type** | **Description** | | -------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | mimes | string array; required | Content MIME types supported (e.g., "video/x-ms-wmv", "video/mp4"). | | minduration | integer; recommended | Minimum video ad duration in seconds. | | maxduration | integer; recommended | Maximum video ad duration in seconds. | | protocols | integer; recommended | Array of supported video protocols (List 5.8). At least one protocol must be specified in either the protocol or protocols attribute. | | w | integer; recommended | Width of the video player in DIPS. | | h | integer; recommended | Height of the video player in DIPS. | | startdelay | integer; recommended | Start delay in seconds for pre-roll, mid-roll, or post-roll placements (List 5.12 for additional generic values). | | placement | integer | Placement type for the impression (List 5.9). | | linearity | integer | Indicates if the impression must be linear, nonlinear, etc. If none specified, assume all are allowed (List 5.7). | | skip | integer | Indicates whether the player will allow the video to be skipped. 0 = no, 1 = yes. If a bidder sends skippable markup, the Bid object should include the attr array, with element 16 set to skippable video (List 5.3). | | skipmin | integer; default 0 | Videos of total duration greater than this number of seconds can be skippable; applies only if the ad is skippable. | | skipafter | integer; default 0 | Number of seconds a video must play before skipping is enabled; applies only if the ad is skippable. | | sequence | integer | If multiple ad impressions are included in the same bid request, the sequence number enables coordinated delivery of multiple creatives. | | battr | integer array | Blocked creative attributes (List 5.3). | | maxextended | integer | Maximum extended ad duration if extension is allowed. Blank/0 = not allowed; -1 = allowed with no time limit; >0 = seconds of extended play beyond maxduration. | | minbitrate | integer | Minimum bit rate in Kbps. | | maxbitrate | integer | Maximum bit rate in Kbps. | | boxingallowed | integer; default 1 | Indicates whether letter-boxing of 4:3 content into a 16:9 window is allowed. 0 = no, 1 = yes. | | playbackmethod | integer array | Playback methods that may be in use. If none specified, any method may be used (List 5.10). Only one method is typically used in practice — it's strongly advised to use only the first element of this array, in preparation for a possible future change to an integer. | | playbackend | integer | The event that causes playback to end (List 5.11). | | delivery | integer array | Supported delivery methods (e.g., streaming, progressive). If none specified, assume all are supported (List 5.15). | | pos | integer | Ad position on screen (List 5.4). | | companionad | object array | Array of Banner objects, if companion ads are available. | | api | integer array | List of supported API frameworks for this impression (List 5.6). If an API is not explicitly listed, it's assumed not to be supported. | | companiontype | integer array | Supported VAST companion ad types (List 5.14). Recommended if companion Banner objects are included via the companionad array. If a banner will be rendered as an end-card, this can be specified using the vcm attribute on that banner. | | ext | object | Placeholder for exchange-specific extensions to OpenRTB. | #### Object: Audio Currently not supported. #### Object: Native | **Attribute** | **Type** | **Description** | | ------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | request | string; required | Request payload complying with the Native Ad Specification. | | ver | string; recommended | Version of the Dynamic Native Ads API to which the request complies; highly recommended for efficient parsing. | | api | integer array | List of supported API frameworks for this impression (List 5.6). If an API is not explicitly listed, it's assumed not to be supported. | | battr | integer array | Blocked creative attributes (List 5.3). | | ext | object | Placeholder for exchange-specific extensions to OpenRTB. | #### Object: Format | **Attribute** | **Type** | **Description** | | ------------- | -------- | ------------------------------------------------------------------------------------------- | | w | integer | Width in DIPS. | | h | integer | Height in DIPS. | | wratio | integer | Relative width when expressing size as a ratio. | | hratio | integer | Relative height when expressing size as a ratio. | | wmin | integer | Minimum width in DIPS at which the ad will be displayed, when size is expressed as a ratio. | | ext | object | Placeholder for exchange-specific extensions to OpenRTB. | #### Object: Pmp | **Attribute** | **Type** | **Description** | | ---------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | private\_auction | integer; default 0 | Indicator of auction eligibility to seats named in the Direct Deals object. 0 = all bids accepted, 1 = bids restricted to the specified deals and their terms. | | deals | object array | Array of Deal objects conveying the specific deals applicable to this impression. | | ext | object | Placeholder for exchange-specific extensions to OpenRTB. | #### Object: Deal | **Attribute** | **Type** | **Description** | | ------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | string; required | A unique identifier for the direct deal. | | bidfloor | float; default 0 | Minimum bid for this impression, expressed in CPM. | | bidfloorcur | string; default "USD" | Currency, specified using ISO-4217 alpha codes. May differ from the bid currency returned by the bidder, if allowed by the exchange. | | at | integer | Optional override of the bid request's overall auction type. 1 = First Price, 2 = Second Price Plus, 3 = the value passed in bidfloor is the agreed-upon deal price. Additional auction types can be defined by the exchange. | | wseat | string array | Whitelist of buyer seats (e.g., advertisers, agencies) allowed to bid on this deal. Omission implies no seat restrictions. | | wadomain | string array | Array of advertiser domains (e.g., advertiser.com) allowed to bid on this deal. Omission implies no advertiser restrictions. | | ext | object | Placeholder for exchange-specific extensions to OpenRTB. | #### Object: Site | **Attribute** | **Type** | **Description** | | ------------- | ------------------- | ------------------------------------------------------------------------------------------------------ | | id | string; recommended | Exchange-specific site ID. | | name | string | Site name (may be aliased at the publisher's request). | | domain | string | Domain of the site (e.g., "mysite.foo.com"). | | cat | string array | Array of IAB content categories of the site (List 5.1). | | sectioncat | string array | Array of IAB content categories describing the current section of the site (List 5.1). | | pagecat | string array | Array of IAB content categories describing the current page or view of the site (List 5.1). | | page | string | URL of the page where the impression will be shown. | | ref | string | Referrer URL that caused navigation to the current page. | | search | string | Search string that caused navigation to the current page. | | mobile | integer | Indicates whether the site has been programmed to optimize layout for mobile devices. 0 = no, 1 = yes. | | privacypolicy | integer | Indicates whether the site has a privacy policy. 0 = no, 1 = yes. | | publisher | object | Details about the Publisher of the site. | | content | object | Details about the Content within the site. | | keywords | string | Comma-separated list of keywords about the site. | | ext | object | Placeholder for exchange-specific extensions to OpenRTB. | #### Object: App | **Attribute** | **Type** | **Description** | | ------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | string; recommended | Exchange-specific app ID. | | name | string | App name (may be aliased at the publisher's request). | | bundle | string | A platform-specific application identifier, unique to the app and independent of the exchange. On Android, a bundle or package name (e.g., com.foo.mygame); on iOS, typically a numeric ID. | | domain | string | Domain of the app (e.g., "mygame.foo.com"). | | storeurl | string | App store URL for an installed app; for IQG 2.1 compliance. | | cat | string array | Array of IAB content categories of the app (List 5.1). | | sectioncat | string array | Array of IAB content categories describing the current section of the app (List 5.1). | | pagecat | string array | Array of IAB content categories describing the current page or view of the app (List 5.1). | | ver | string | Application version. | | privacypolicy | integer | Indicates whether the app has a privacy policy. 0 = no, 1 = yes. | | paid | integer | 0 = app is free, 1 = paid version. | | publisher | object | Details about the Publisher of the app. | | content | object | Details about the Content within the app. | | keywords | string | Comma-separated list of keywords about the app. | | ext | object | Placeholder for exchange-specific extensions to OpenRTB. | #### Object: Publisher | **Attribute** | **Type** | **Description** | | ------------- | ------------ | -------------------------------------------------------------------- | | id | string | Exchange-specific publisher ID. | | name | string | Publisher name (may be aliased at the publisher's request). | | cat | string array | Array of IAB content categories describing the publisher (List 5.1). | | domain | string | Highest-level domain of the publisher (e.g., "publisher.com"). | | ext | object | Placeholder for exchange-specific extensions to OpenRTB. | #### Object: Content | **Attribute** | **Type** | **Description** | | ------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | id | string | ID uniquely identifying the content. | | episode | integer | Episode number. | | title | string | Content title. Video examples: "Search Committee" (television), "A New Hope" (movie), "Endgame" (made for web). Non-video example: "Why an Antarctic Glacier Is Melting So Quickly" (Time magazine article). | | series | string | Content series. Video examples: "The Office" (television), "Star Wars" (movie), "Arby 'N' The Chief" (made for web). Non-video example: "Ecocentric" (Time magazine blog). | | season | string | Content season (e.g., "Season 3"). | | artist | string | Artist credited with the content. | | genre | string | Genre that best describes the content (e.g., rock, pop). | | album | string | Album to which the content belongs; typically for audio. | | isrc | string | International Standard Recording Code, conforming to ISO-3901. | | producer | object | Details about the content Producer. | | url | string | URL of the content, for buy-side contextualization or review. | | cat | string array | Array of IAB content categories describing the content producer (List 5.1). | | prodq | integer | Production quality (List 5.13). | | context | integer | Type of content (game, video, text, etc.) (List 5.18). | | contentrating | string | Content rating (e.g., MPAA). | | userrating | string | User rating of the content (e.g., number of stars, likes). | | qagmediarating | integer | Media rating per IQG guidelines (List 5.19). | | keywords | string | Comma-separated list of keywords describing the content. | | livestream | integer | 0 = not live, 1 = content is live (e.g., stream, live blog). | | sourcerelationship | integer | 0 = not live, 1 = content is live (e.g., stream, live blog). | | len | integer | Length of content in seconds; appropriate for video or audio. | | language | string | Content language, using ISO-639-1-alpha-2. | | embeddable | integer | Indicates whether the content is embeddable (e.g., an embeddable video player). 0 = no, 1 = yes. | | data | object array | Additional content data. Each Data object represents a different data source. | | ext | object | Placeholder for exchange-specific extensions to OpenRTB. | #### Object: Producer | **Attribute** | **Type** | **Description** | | ------------- | ------------ | ---------------------------------------------------------------------------------------------------------------- | | id | string | Content producer or originator ID. Useful if content is syndicated and may be posted on a site using embed tags. | | name | string | Content producer or originator name (e.g., "Warner Bros"). | | cat | string array | Array of IAB content categories describing the content producer (List 5.1). | | domain | string | Highest-level domain of the content producer (e.g., "producer.com"). | | ext | object | Placeholder for exchange-specific extensions to OpenRTB. | #### Object: Device | **Attribute** | **Type** | **Description** | | -------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | ua | string; recommended | Browser user agent string. | | geo | object; recommended | Location of the device, assumed to be the user's current location, defined by a Geo object. | | dnt | integer; recommended | Standard "Do Not Track" flag, as set in the browser header. 0 = tracking unrestricted, 1 = do not track. | | lmt | integer; recommended | "Limit Ad Tracking" signal, commercially endorsed (e.g., iOS, Android). 0 = tracking unrestricted, 1 = tracking must be limited per commercial guidelines. | | ip | string; recommended | IPv4 address closest to the device. | | ipv6 | string | IP address closest to the device, as IPv6. | | devicetype | integer | The general type of device (List 5.21). | | make | string | Device make (e.g., "Apple"). | | model | string | Device model (e.g., "iPhone"). | | os | string | Device operating system (e.g., "iOS"). | | osv | string | Device operating system version (e.g., "3.1.2"). | | hwv | string | Hardware version of the device (e.g., "5S" for iPhone 5S). | | h | integer | Physical height of the screen in pixels. | | w | integer | Physical width of the screen in pixels. | | ppi | integer | Screen size as pixels per linear inch. | | pxratio | float | Ratio of physical pixels to device-independent pixels. | | js | integer | Support for JavaScript. 0 = no, 1 = yes. | | geofetch | integer | Indicates whether the geolocation API will be available to JavaScript code running in the banner. 0 = no, 1 = yes. | | flashver | string | Version of Flash supported by the browser. | | language | string | Browser language, using ISO-639-1-alpha-2. | | carrier | string | Carrier or ISP (e.g., "VERIZON"), using exchange-curated string names published to bidders a priori. | | mccmnc | string | Mobile carrier as the concatenated MCC-MNC code (e.g., "310-005" identifies Verizon Wireless CDMA in the USA). The dash between MCC and MNC is required to remove parsing ambiguity. | | connectiontype | integer | Network connection type (List 5.22). | | ifa | string | ID sanctioned for advertiser use in the clear (i.e., not hashed). | | didsha1 | string | Hardware device ID (e.g., IMEI); hashed via SHA1. | | didmd5 | string | Hardware device ID (e.g., IMEI); hashed via MD5. | | macsha1 | string | MAC address of the device; hashed via SHA1. | | macmd5 | string | MAC address of the device; hashed via MD5. | | ext | object | Placeholder for exchange-specific extensions to OpenRTB. | #### Object: Geo | **Attribute** | **Type** | **Description** | | ------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | lat | float | Latitude, from -90.0 to +90.0, where negative is south. | | lon | float | Longitude, from -180.0 to +180.0, where negative is west. | | type | integer | Source of location data; recommended when passing lat/lon (List 5.20). | | accuracy | integer | Estimated location accuracy in meters; recommended when lat/lon are derived from a device's location services (type = 1). This is the accuracy as reported by the device — consult OS-specific documentation for exact interpretation. | | lastfix | integer | Number of seconds since this geolocation fix was established. Devices may cache location data across multiple fetches; ideally this value reflects the time the actual fix was taken. | | ipservice | integer | Service or provider used to determine geolocation from IP address, if applicable (type = 2) (List 5.23). | | country | string | Country code, using ISO-3166-1-alpha-3. | | region | string | Region code using ISO-3166-2; 2-letter state code if USA. | | regionfips104 | string | Region of a country using FIPS 10-4 notation. Supported by OpenRTB, though withdrawn by NIST in 2008. | | metro | string | Google metro code; similar to, but not exactly, Nielsen DMAs. | | city | string | City, using the United Nations Code for Trade & Transport Locations. | | zip | string | Zip or postal code. | | utcoffset | integer | Local time as the number of +/- minutes from UTC. | | ext | object | Placeholder for exchange-specific extensions to OpenRTB. | #### Object: User | **Attribute** | **Type** | **Description** | | ------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | string; recommended | Exchange-specific ID for the user. At least one of id or buyeruid is recommended. | | buyeruid | string; recommended | Buyer-specific ID for the user, as mapped by the exchange for the buyer. At least one of buyeruid or id is recommended. | | yob | integer | Year of birth, as a 4-digit integer. | | gender | string | Gender, where "M" = male, "F" = female, "O" = known to be other (omitted = unknown). | | keywords | string | Comma-separated list of keywords, interests, or intent. | | customdata | string | Optional feature for passing bidder data that was set in the exchange's cookie. The string must be in base85 cookie-safe characters, in any format. Proper JSON encoding must be used to include "escaped" quotation marks. | | geo | object | Location of the user's home base, defined by a Geo object. Not necessarily their current location. | | data | object array | Additional user data. Each Data object represents a different data source. | | ext | object | Placeholder for exchange-specific extensions to OpenRTB. | #### Object: Data | **Attribute** | **Type** | **Description** | | ------------- | ------------ | -------------------------------------------------------------- | | id | string | Exchange-specific ID for the data provider. | | name | string | Exchange-specific name for the data provider. | | segment | object array | An array of Segment objects containing the actual data values. | | ext | object | Placeholder for exchange-specific extensions to OpenRTB. | #### Object: Segment | **Attribute** | **Type** | **Description** | | ------------- | -------- | -------------------------------------------------------- | | id | string | ID of the data segment, specific to the data provider. | | name | string | Name of the data segment, specific to the data provider. | | value | string | String representation of the data segment value. | | ext | object | Placeholder for exchange-specific extensions to OpenRTB. | ### Banner Bid Request Example ```json { "id": "1a7e8897-7054-42cb-beae-14a6dd0fc140", "site": { "domain": "demo.gamotest.com", "page": "http://demo.gamotest.com/publishers/demo/index.html", "ref": "" }, "device": { "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.142 Safari/537.36", "ip": "3.0.0.0" }, "imp": [ { "id": "395060be-12ab-4456-adaf-ab641c4ebadc", "instl": 0, "tagid": "banner-unit", "bidfloor": 0, "bidfloorcur": "USD", "secure": 0, "banner": { "w": 300, "h": 250, "pos": 0, "topframe": 0 } } ], "ext": {} } ``` ### Video Bid Request Example ```json { "app": { "bundle": "com.gamoshi.test", "id": "d422842355a24f3c9df40c139ca214a4", "name": "SDK Test" }, "at": 2, "badv": [], "bcat": [], "device": { "carrier": "", "connectiontype": 1, "devicetype": 4, "dnt": 0, "geo": { "city": "Mountain View", "country": "USA", "metro": "", "type": 2, "zip": "94043" }, "h": 1920, "hwv": "klteatt", "ifa": "c50377de-f8a4-4f89-81c6-ad0c00691bc0", "ip": "66.249.76.28", "js": 1, "language": "en", "lmt": 0, "make": "samsung", "model": "SAMSUNG-SM-G900A", "os": "Android", "osv": "5.0.0", "ua": "Dalvik/2.1.0 (Linux; U; Android 5.0; SAMSUNG-SM-G900A Build/LRX21T)", "w": 1080 }, "id": "18f21e5332a17b95ffb922317137d2302a5c28a2", "imp": [ { "displaymanager": "generic", "displaymanagerver": "6.2.4", "id": "1", "instl": 1, "secure": 0, "tagid": "86371d35d96aff1f:", "video": { "battr": [], "companiontype": [1, 2], "h": 480, "linearity": 1, "maxduration": 60, "mimes": ["video/mp4"], "minduration": 5, "protocols": [2, 3], "w": 320 } } ] } ``` ## 3. Bid Response ### 3.1 Bid Response Specification RTB responses contain bids that reference specific impressions within a bid request. Bids are, in essence, an offer to buy. The bid response consists of the top-level bid response object and optional objects depicting the specific bids. An empty HTTP response constitutes a no-bid, and is the most bandwidth-friendly form of this signal — though returning a response with a "no-bid reason" is encouraged. A malformed response, or one that contains no actual bids, will also be interpreted as a no-bid. #### Object: BidResponse | **Attribute** | **Type** | **Description** | | ------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | string; required | ID of the bid request to which this is a response. | | seatbid | object array | Array of SeatBid objects; 1+ required if a bid is to be made. | | bidid | string | Bidder-generated response ID to assist with logging/tracking. | | cur | string; default "USD" | Bid currency, using ISO-4217 alpha codes. | | customdata | string | Optional feature allowing a bidder to set data in the exchange's cookie. The string must be in base85 cookie-safe characters, in any format. Proper JSON encoding must be used to include "escaped" quotation marks. | | nbr | integer | Reason for not bidding (List 5.24). | | ext | object | Placeholder for bidder-specific extensions to OpenRTB. | #### Object: SeatBid | **Attribute** | **Type** | **Description** | | ------------- | ---------------------- | -------------------------------------------------------------------------------------------------------- | | bid | object array; required | Array of 1+ Bid objects, each related to an impression. Multiple bids can relate to the same impression. | | seat | string | ID of the buyer seat (e.g., advertiser, agency) on whose behalf this bid is made. | | group | integer; default 0 | 0 = impressions can be won individually, 1 = impressions must be won or lost as a group. | | ext | object | Placeholder for bidder-specific extensions to OpenRTB. | #### Object: Bid | **Attribute** | **Type** | **Description** | | -------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | string; required | Bidder-generated bid ID to assist with logging/tracking. | | impid | string; required | ID of the Imp object in the related bid request. | | price | float; required | Bid price, expressed as CPM, although the actual transaction is for a unit impression only. Integer math is highly recommended when handling currencies (e.g., BigDecimal in Java). | | nurl | string | Win notice URL called by the exchange if the bid wins (not necessarily indicative of a delivered, viewed, or billable ad); optional means of serving ad markup. Substitution macros may be included in both the URL and returned markup. | | burl | string | Billing notice URL called by the exchange when a winning bid becomes billable, per exchange-specific business policy (e.g., typically delivered, viewed). Substitution macros may be included. | | lurl | string | Loss notice URL called by the exchange when a bid is known to have been lost. Substitution macros may be included. Exchange-specific policy may preclude support for loss notices or disclosure of winning clearing prices, resulting in ${AUCTION\_PRICE} macros being replaced with a zero-length string. | | adm | string | Optional means of conveying ad markup in case the bid wins; supersedes the win notice if markup is included in both. Substitution macros may be included. | | adid | string | ID of a preloaded ad to be served if the bid wins. | | adomain | string array | Advertiser domain for block-list checking (e.g., "ford.com"). Can be an array, for rotating creatives. Exchanges can mandate that only one domain is allowed. | | bundle | string | A platform-specific application identifier, unique to the app and independent of the exchange. On Android, a bundle or package name (e.g., com.foo.mygame); on iOS, a numeric ID. | | iurl | string | URL, without cache-busting, to an image representative of the campaign's content, for ad quality/safety checking. | | cid | string | Campaign ID to assist with ad quality checking — the collection of creatives for which iurl should be representative. | | crid | string | Creative ID to assist with ad quality checking. | | tactic | string array | Tactic ID, enabling buyers to label bids for reporting to the exchange the tactic through which their bid was submitted. Usage and meaning should be communicated between buyer and exchange a priori. | | cat | string array | IAB content categories of the creative (List 5.1). | | attr | integer array | Set of attributes describing the creative (List 5.3). | | api | integer | API required by the markup, if applicable (List 5.6). | | protocol | integer | Video response protocol of the markup, if applicable (List 5.8). | | qagmediarating | integer | Creative media rating, per IQG guidelines (List 5.19). | | language | string | Language of the creative, using ISO-639-1-alpha-2. The non-standard code "xx" may be used if the creative has no linguistic content (e.g., a banner with just a company logo). | | dealid | string | Reference to the deal.id from the bid request, if this bid pertains to a private marketplace direct deal. | | w | integer | Width of the creative in DIPS. | | h | integer | Height of the creative in DIPS. | | wratio | integer | Relative width of the creative, when expressing size as a ratio. Required for Flex Ads. | | hratio | integer | Relative height of the creative, when expressing size as a ratio. Required for Flex Ads. | | exp | integer | Advisory as to the number of seconds the bidder is willing to wait between the auction and the actual impression. | | ext | object | Placeholder for bidder-specific extensions to OpenRTB. | ### Banner Bid Response Example ```json { "id": "imp_5dff3170e4b01f3d1c599c9f", "bidid": "imp_5dff3170e4b01f3d1c599c9f", "cur": "USD", "seatbid": [ { "seat": "16482", "group": 0, "bid": [ { "id": "gb_1", "impid": "1", "price": 0.99, "adid": "2867", "nurl": "http://rtb.gamoshi.io/pix/6511/win_notice/imp_5dff3170e4b01f3d1c599c9f/im.gif?r=imp_5dff3170e4b01f3d1c599c9f&i=1&a=2867&b=gb_1&p=${AUCTION_PRICE}&est=1577005424757", "adomain": [], "bundle": "test bundle", "adm": "\"\"", "cid": "16482", "crid": "2867", "cat": [], "attr": [], "h": 600, "w": 300, "ext": { "bidfloor": 0.0101, "imptrackers": [ "http://rtb.gamoshi.io/pix/6511/imp/imp_5dff3170e4b01f3d1c599c9f/im.gif?r=imp_5dff3170e4b01f3d1c599c9f&i=1&a=2867&b=gb_1&est=1577005424757" ] } } ] } ] } ``` ### Video Bid Response Example ```json { "id": "d24543f7-c2ef-4386-9382-b724702d3b9a", "bidid": "imp_607ec5fae4b01407c1c6180d", "cur": "USD", "seatbid": [ { "seat": "3668", "group": 0, "bid": [ { "id": "gb_1", "impid": "5c547eea-37c2-4101-bd91-9426ecf48127", "price": 5.0, "adid": "1274", "nurl": "http://aws.gamx.io/pix/1275/win_notice/imp_607ec5fae4b01407c1c6180d/im.gif?r=imp_607ec5fae4b01407c1c6180d&i=5c547eea-37c2-4101-bd91-9426ecf48127&a=1274&b=gb_1&p=${AUCTION_PRICE}&est=1618920954952", "adm": "", "cid": "3668", "crid": "1274", "h": 250, "w": 300 } ] } ] } ``` *** ## Related articles * [Gamoshi bid request & bid response examples](/gamoshi-wiki/general-information/gamoshi-bid-request-and-bid-response-examples.md) * [Inventory Integration Types RTB integration](/gamoshi-wiki/core-entities/inventory/inventory-integration-types-rtb-integration.md) * [Inventory Incoming Request Workflow Overview](/gamoshi-wiki/general-information/inventory-incoming-request-workflow-overview.md)