Google sends a
[SegmentRequest](https://developers.google.com/authorized-buyers/curation/realtime-curation/reference#segreq)
based on ad requests matching your targeted inventory to your Real-time
Curation integration. The `SegmentRequest` object provides either contextual
signals or audience signals that you can use to identify which of your segments
apply to the given inventory in the
[SegmentResponse](https://developers.google.com/authorized-buyers/curation/realtime-curation/reference#segresp).
Real-time Curation supports `SegmentRequest` and `SegmentResponse` objects
sent in JSON format.

This guide is a reference for the Real-time Curation protocol that can help you
build your integration.

## SegmentRequest

| Attribute | Type | Description |
|---|---|---|
| `imp` | [Imp](https://developers.google.com/authorized-buyers/curation/realtime-curation/reference#segreq_imp) array | **Only supported for contextual curation partners.** Represents the impression opportunities being offered. |
| `site` | [Site](https://developers.google.com/authorized-buyers/curation/realtime-curation/reference#segreq_site) | **Only supported for contextual curation partners.** A descriptor of the website. The `site` field is populated if the ad supported content is a website rather than a non-browser application. |
| `app` | [App](https://developers.google.com/authorized-buyers/curation/realtime-curation/reference#segreq_app) | **Only supported for contextual curation partners.** A descriptor of the app. The `app` field is populated if the ad supported content is a non-browser application rather than a website. |
| `pub` | [Publisher](https://developers.google.com/authorized-buyers/curation/realtime-curation/reference#segreq_pub) | **Only supported for contextual curation partners.** A descriptor of the publisher. |
| `user` | [User](https://developers.google.com/authorized-buyers/curation/realtime-curation/reference#segreq_user) | A descriptor of the user browsing publisher content that initiated the segment request. |
| `device` | [Device](https://developers.google.com/authorized-buyers/curation/realtime-curation/reference#segreq_device) | **Only supported for contextual curation partners.** A descriptor of the user's device. |
| `segment_request_id` | string | A unique identifier used to identify the segment request independently from all other segment requests. |

### Imp

| Attribute | Type | Description |
|---|---|---|
| `id` | string | **Only supported for contextual curation partners.** A unique identifier for this impression within the context of the segment request. The value starts at 1 and increments up to n for n impressions. |
| `banner` | [Banner](https://developers.google.com/authorized-buyers/curation/realtime-curation/reference#segreq_imp_banner) | **Only supported for contextual curation partners.** This field is populated if the impression is offered as a banner ad opportunity. |
| `video` | [Video](https://developers.google.com/authorized-buyers/curation/realtime-curation/reference#segreq_imp_video) | **Only supported for contextual curation partners.** This field is populated if the impression is offered as a video ad opportunity. |
| `ext` | [ImpExt](https://developers.google.com/authorized-buyers/curation/realtime-curation/reference#segreq_imp_ext) | This is populated with extensions for the `Imp` object. |

#### Banner

| Attribute | Type | Description |
|---|---|---|
| `w` | int | **Only supported for contextual curation partners.** Width in device independent pixels (DIPS). |
| `h` | int | **Only supported for contextual curation partners.** Height in device independent pixels (DIPS). |
| `pos` | int | **Only supported for contextual curation partners.** Ad position on screen. To learn more about possible placement positions, see [List: Placement Positions](https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/main/AdCOM%20v1.0%20FINAL.md#list--placement-positions-) in AdCOM 1.0. |

#### Video

| Attribute | Type | Description |
|---|---|---|
| `w` | int | **Only supported for contextual curation partners.** Width of the video player in device independent pixels (DIPS). |
| `h` | int | **Only supported for contextual curation partners.** Height of the video player in device independent pixels (DIPS). |
| `pos` | int | **Only supported for contextual curation partners.** Ad position on screen. To learn more about possible placement positions, see [List: Placement Positions](https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/main/AdCOM%20v1.0%20FINAL.md#list--placement-positions-) in AdCOM 1.0. |

#### ImpExt

| Attribute | Type | Description |
|---|---|---|
| `gpid` | string | **Only supported for contextual curation partners.** Describes the Global placement ID. A distinct, persistent ID, specified by the publisher, which is consistent across supply paths for each ad unit on a page. See [this article](https://github.com/InteractiveAdvertisingBureau/openrtb/blob/main/extensions/community_extensions/gpid.md). |

### Site

| Attribute | Type | Description |
|---|---|---|
| `page` | string | **Only supported for contextual curation partners.** URL of the page showing the impression. |
| `mobile` | int | **Only supported for contextual curation partners.** Indicates if the site has been programmed to optimize layout when viewed on mobile devices, where 0 = no, 1 = yes. |

### App

| Attribute | Type | Description |
|---|---|---|
| `bundle` | string | **Only supported for contextual curation partners.** A platform-specific application identifier intended to be unique to the app. On Android, the `bundle` field is a bundle or package name. On iOS, it is a numeric ID. |

### Publisher

| Attribute | Type | Description |
|---|---|---|
| `id` | string | **Only supported for contextual curation partners.** A publisher ID defined by the publisher code suffix of the web property code. For example, a publisher having a web property code of `ca-pub-123` would have its ID set to `pub-123`. |

### User

| Attribute | Type | Description |
|---|---|---|
| `id` | string | The Google User ID. |
| `buyeruid` | string | Hosted match data uploaded with the Cookie Matching Service. By default, this is specified in web-safe base64 encoding without padding. You can optionally configure this field to be populated without encoding by contacting your account manager. |
| `consent` | string | A web-safe based64-encoded IAB Transparency and Consent Framework (TCF) v2 consent string fetched from the publisher's [IAB Consent Management Platform](https://iabeurope.eu/tcf-for-cmps/) (CMP). The `consent` field is populated if the publisher has integrated with a CMP for TCF v2 and that CMP indicates that GDPR applies to the ad request and provides a valid consent string. See the IAB Global Vendor List at [vendor-list.consensu.org/v2/vendor-list.json](https://vendor-list.consensu.org/v2/vendor-list.json) for details about the vendors listed in the consent string. |
| `eids` | [EID](https://developers.google.com/authorized-buyers/curation/realtime-curation/reference#segreq_user_eid) array | **Only supported for audience curation partners.** Extended ID instances. In Curation, the `eids` field is data that the publisher makes available, such as secure signals. |

#### EID

| Attribute | Type | Description |
|---|---|---|
| `source` | string | **Only supported for audience curation partners.** Source or technology provider responsible for the set of included data. Expressed as a top-level domain. |
| `uids` | [UID](https://developers.google.com/authorized-buyers/curation/realtime-curation/reference#segreq_user_eid_uid) array | **Only supported for audience curation partners.** Array of UID objects from the given source. |

#### UID

| Attribute | Type | Description |
|---|---|---|
| `id` | string | **Only supported for audience curation partners.** The identifier. In curation, the `id` field is a secure signal. To learn more about secure signals, see Ad Manager's [Share secure signals with bidders and curation partners](https://support.google.com/admanager/answer/10488752#bidders). |

### Device

| Attribute | Type | Description |
|---|---|---|
| `geo` | [Geo](https://developers.google.com/authorized-buyers/curation/realtime-curation/reference#segreq_device_geo) | **Only supported for contextual curation partners.** Location of the user's device. |
| `devicetype` | int | **Only supported for contextual curation partners.** The general type of device. To learn more about possible device types, see [List: Device Types](https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/main/AdCOM%20v1.0%20FINAL.md#list--device-types-) in AdCOM 1.0. |
| `os` | string | **Only supported for contextual curation partners.** Device operating system (e.g., "iOS"). |
| `make` | string | **Only supported for contextual curation partners.** Device make (e.g., "Apple"). |
| `ifa` | string | Unencrypted device advertising ID (not hashed). In Google's Real-time Curation protocol, this is typically a 36-character UUID, where Android IDs are in lowercase and IDFAs are in uppercase. For Samsung devices, these are 32-character alphanumeric values. |

#### Geo

| Attribute | Type | Description |
|---|---|---|
| `country` | string | **Only supported for contextual curation partners.** Country using the ISO-3166-1 Alpha-3 standard. |
| `region` | string | **Only supported for contextual curation partners.** Region code using the ISO-3166-2 standard; 2-letter state code if USA. |
| `metro` | string | **Only supported for contextual curation partners.** Google metro code found in [geo-table.csv](https://storage.googleapis.com/adx-rtb-dictionaries/geo-table.csv) file. |
| `city` | string | **Only supported for contextual curation partners.** City using United Nations Code for Trade \& Transport Locations. |

## SegmentResponse

| Attribute | Type | Description |
|---|---|---|
| `segment` | [Segment](https://developers.google.com/authorized-buyers/curation/realtime-curation/reference#segresp_segment) array | A descriptor for a segment. |

### Segment

| Attribute | Type | Description |
|---|---|---|
| `segment_id` | string | The ID for the segment. The ID should match the `curatorDataSegmentId` found in the name of the segment in Marketplace API's [`curators.dataSegments`](https://developers.google.com/authorized-buyers/apis/marketplace/reference/rest/v1beta/curators.dataSegments) resource. |