Protos & Reference Data

View or download files that support the RTB Protocol.


Important: When you download a proto file, you must rename it, replacing -proto.txt with .proto.

File Description Version Last Updated
publisher-settings.proto A set of publisher settings specific to a real-time bidder network. v.7 Jan 08, 2020
realtime-bidding.proto This is the message Google uses to request bids. A BidRequest includes the ad slot from a single impression. v.179 Jul 24, 2020
openrtb.proto Google supports the OpenRTB protocol, using either JSON or Protobuf encoding. This proto is necessary if you use OpenRTB/Protobuf. It also includes documentation of supported fields and their mapping to Google's native protocol. 2.5.0 May 27, 2020
openrtb-adx.proto Google's OpenRTB protocol includes some extensions, provided in a separate proto. v.50 Jul 23, 2020
snippet-status-report.proto This is the message Google uses to communicate creative status reports. v.31 Feb 20, 2020
cookie-bulk-upload.proto Use this message to bulk upload user targeting data. v.16 Jul 09, 2020

Reference data

Dictionaries (Click to download .txt file)

Ad product categories Used in the excluded_product_category field of BidRequest. This field describes categories of products and services that are not allowed by a publisher, for example, if the publisher doesn't want to host ads related to online banking.
Ad restricted categories Used in the allowed_restricted_category field of BidRequest and the restricted_category field of BidResponse. The allowed_restricted_category field describes categories that are normally restricted, but explicitly declared by a publisher as allowed, for example, ads containing alcohol-related content.
Ad sensitive categories Used in the excluded_sensitive_category field of BidRequest and the category field of BidResponse. The excluded_sensitive_category field describes sensitive categories that are not allowed by the publisher, for example, if the publisher does not want to host ads related to politics.
Advertisers Used in the advertiser_id field of SnippetStatusItem. This field specifies the advertiser represented by the creative associated with the snippet. This list reflects advertisers across the exchange and does not reflect the advertisers represented by any one buyer.
Agencies Used in the agency_id field of BidResponse. This field is used to declare the agency associated with the ad being returned.
Brands List of brands, used in the Client Access API.
Buyer declarable creative attributes Used for the attribute field in BidResponse. This field describes buyer-declarable attributes on creatives which must not appear in excluded_attribute in BidRequest.
Callout status codes Status codes returned by the performancereport method call.
Content labels Used in the detected_content_labels field of the BidRequest.
Cookie matcher status codes Used in the cookieMatcherStatusRate field of RTB Protocol performance reports. Available codes are described in the Cookie matching guide.
Creative status codes

Used in

Hosted match status codes Used in the hostedMatchStatusRate field of RTB Protocol performance reports.
Pretargetable creative attributes Used in the supportedCreativeAttribute field in the PretargetingConfig resource exposed in the Buyer REST API. This field describes creative attributes expected to be present in all creatives corresponding to a single pretargeting configuration.
Publisher-excludable creative attributes Used in the excluded_attribute field of BidRequest. This field describes the types of creatives that are not allowed by the publisher. For example, they might specify restrictions on whether cookie usage is allowed, or whether media and/or text ads are allowed.
Publisher verticals Used in the detected_vertical field of BidRequest. This field specifies the verticals (similar to keywords) of the page on which the ad will be shown. Google generates this field by crawling the page and determining which verticals are used.
Seller network IDs Used in the seller_network_id field of BidRequest. This field specifies the seller network to which the publisher belongs.
Vendors Used in the allowed_vendor_type field of BidRequest. This field lists which Rich Media vendors, such as Campaign Monitor and VoiceFive, are allowed for the creative being served, as specified by the publisher.

Includes vendors from the sunsetted gdn-vendors.txt dictionary file.

Reference tables (Click to download CSVs)

Providers Maps ads personalization provider IDs to a human readable name, a privacy policy URL, and a list of domains which can be attributed to the provider. Currently, providers are used in the BidRequest.AdSlot.consented_providers_settings field for AdX protocol and BidRequest.User.UserExt.consented_providers_settings for OpenRTB protocol. In these fields, the listed providers have user consent as passed by publishers for users in the countries within the European Economic Area.
Geo tables The table used to decode the geo_criteria_id field of BidRequest. Refer to Geotargeting for more information.
Android mobile apps List of targetable Android mobile apps with their app IDs, category IDs, and human-readable app names.
Mobile carriers List of mobile carriers.
Mobile devices List of mobile devices.
Mobile operating systems List of mobile operating systems.

Publisher settings

Request the publisher-settings.pb.gz file from your account representative.