Measurements API

The Measurements service provides methods for creating and managing measurement requests across data providers.

Resource

Measurement

A measurement from a set of DataProviders requested by a MeasurementConsumer. Resource name pattern: measurementConsumers/{measurement_consumer}/measurements/{measurement}

name

string

required

Resource name identifier.

measurement_consumer_certificate

string

required

Resource name of the Certificate belonging to the parent MeasurementConsumer.

measurement_spec

SignedMessage

required

Serialized MeasurementSpec for requisitions, which can be verified using measurement_consumer_certificate.The version of the MeasurementSpec message type must correspond to the API version that this resource was created in.

data_providers

DataProviderEntry[]

required

Map of DataProvider name to parameters for that DataProvider.

protocol_config

ProtocolConfig

The ProtocolConfig selected for this measurement according to the measurement_spec. Output only.

state

State

State of this Measurement. Output only.Possible values:

STATE_UNSPECIFIED - Default value used if the state is omitted
AWAITING_REQUISITION_FULFILLMENT - Waiting for all linked Requisitions to be fulfilled
COMPUTING - Computation is running
SUCCEEDED - Completed successfully (terminal state)
FAILED - Completed with failure (terminal state)
CANCELLED - Cancelled by Measurement Consumer (terminal state)

results

ResultOutput[]

Results of this Measurement. Only set if state is SUCCEEDED. Output only.

measurement_reference_id

string

ID referencing the Measurement in an external system, provided by the MeasurementConsumer.

failure

Failure

Information about the failure of this Measurement. Set when the state is set to FAILED. Output only.

create_time

Timestamp

When the Measurement was created. Output only.

update_time

Timestamp

When the Measurement was last updated. Output only.

DataProviderEntry

Entry for data_providers map.

key

string

required

Key of the map entry, which is a DataProvider resource name.

value

Value

required

Value of the map entry.

Show Value fields

data_provider_certificate

string

required

Resource name of the Certificate belonging to data_provider.

data_provider_public_key

Any

required

Pre-shared packed EncryptionPublicKey. The version of the EncryptionPublicKey message type must correspond to the API version that this resource was created in.

encrypted_requisition_spec

EncryptedMessage

required

Encrypted SignedMessage containing the serialized RequisitionSpec for this entry, which can be verified using measurement_consumer_certificate. The encryption uses data_provider_public_key as the recipient public key.

nonce_hash

bytes

required

SHA256 hash of the nonce from encrypted_requisition_spec, where the nonce value has big-endian byte ordering.

Result

The result of a Measurement.

reach

Reach

The reach result.

Show Reach fields

value

int64

Number of unique users (VIDs) for which there are impression events. This must be non-negative, meaning any negative value arising due to noise must be clamped to 0.

noise_mechanism

NoiseMechanism

The mechanism used to generate noise during computation.

methodology

oneof

The computation methodology. Required. One of: custom_direct_methodology, deterministic_count_distinct, liquid_legions_count_distinct, liquid_legions_v2, reach_only_liquid_legions_v2, honest_majority_share_shuffle.

frequency

Frequency

The frequency result.

Show Frequency fields

relative_frequency_distribution

map<int64, double>

Map of frequency to reach ratio. Values must be non-negative, meaning any negative value arising due to noise must be clamped to 0.

noise_mechanism

NoiseMechanism

The mechanism used to generate noise during computation.

methodology

oneof

The computation methodology. Required. One of: custom_direct_methodology, deterministic_distribution, liquid_legions_distribution, liquid_legions_v2, honest_majority_share_shuffle.

impression

Impression

The impression result.

Show Impression fields

value

int64

Number of impression events. This must be non-negative, meaning any negative value arising due to noise must be clamped to 0.

noise_mechanism

NoiseMechanism

The mechanism used to generate noise during computation.

methodology

oneof

The computation methodology done by data provider. Required. One of: custom_direct_methodology, deterministic_count.

watch_duration

WatchDuration

The watch duration result.

Show WatchDuration fields

value

Duration

Total duration. This must be non-negative, meaning any negative value arising due to noise must be clamped to 0.

noise_mechanism

NoiseMechanism

The mechanism used to generate noise during computation.

methodology

oneof

The computation methodology done by data provider. Required. One of: custom_direct_methodology, deterministic_sum.

population

Population

The population result.

Show Population fields

value

int64

The population value. This must be non-negative.

methodology

oneof

The computation methodology done by data provider. Required. One of: deterministic_count.

Failure

Information about a failure.

reason

Reason

required

Reason for this Failure.Possible values:

REASON_UNSPECIFIED - Default value used if the reason is omitted
CERTIFICATE_REVOKED - An associated certificate was revoked
REQUISITION_REFUSED - Requisition state was set to REFUSED
COMPUTATION_PARTICIPANT_FAILED - ComputationParticipant state was set to FAILED

message

string

Human-readable message. This should not contain any sensitive information.

Methods

GetMeasurement

Returns the Measurement with the specified resource key. Request

name

string

required

Resource name of the Measurement.Format: measurementConsumers/{measurement_consumer}/measurements/{measurement}

Response Returns a Measurement resource. Example

message GetMeasurementRequest {
  string name = 1 [(google.api.field_behavior) = REQUIRED];
}

CreateMeasurement

Creates (registers) a Measurement. Request

parent

string

required

Resource name of the parent MeasurementConsumer.Format: measurementConsumers/{measurement_consumer}

measurement

Measurement

required

The Measurement to create. The name field will be ignored, and the system will assign an ID.

request_id

string

Unique identifier for this request. If specified, the request will be idempotent. See https://google.aip.dev/155.

Response Returns the created Measurement resource. Example

message CreateMeasurementRequest {
  string parent = 3 [(google.api.field_behavior) = REQUIRED];
  Measurement measurement = 1 [(google.api.field_behavior) = REQUIRED];
  string request_id = 2;
}

ListMeasurements

Lists Measurements for the parent MeasurementConsumer. Request

parent

string

required

Resource name of the parent MeasurementConsumer.Format: measurementConsumers/{measurement_consumer}

page_size

int32

The maximum number of Measurements to return. The service may return fewer than this value.If unspecified, at most 50 Measurements will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.

page_token

string

A page token, received from a previous ListMeasurementsRequest call. Provide this to retrieve the subsequent page.When paginating, all other parameters provided to ListMeasurementsRequest must match the call that provided the page token.

filter

Filter

Filter criteria. Repeated fields are treated as logical ORs, and multiple fields specified as logical ANDs.

Show Filter fields

Response

measurements

Measurement[]

List of Measurements that has all of the tags in the ListMeasurementsRequest.

next_page_token

string

A token, which can be sent as page_token to retrieve the next page. If this field is omitted, there are no subsequent pages.

Example

message ListMeasurementsRequest {
  string parent = 1 [(google.api.field_behavior) = REQUIRED];
  int32 page_size = 2;
  string page_token = 3;
  Filter filter = 4;
}

message ListMeasurementsResponse {
  repeated Measurement measurements = 1;
  string next_page_token = 2;
}

CancelMeasurement

Transitions a Measurement to the CANCELLED state. This is a terminal state for the Measurement. This is a state transition method (see https://aip.dev/216). Request

name

string

required

Resource name of the Measurement to mark as CANCELLED.Format: measurementConsumers/{measurement_consumer}/measurements/{measurement}

Response Returns the updated Measurement resource with state set to CANCELLED. Example

message CancelMeasurementRequest {
  string name = 1 [(google.api.field_behavior) = REQUIRED];
}

BatchCreateMeasurements

Batch creates Measurements. Results in an error if any of the specified Measurements fail to be created. Request

parent

string

required

Resource name of the parent MeasurementConsumer.Format: measurementConsumers/{measurement_consumer}

requests

CreateMeasurementRequest[]

required

The requests specifying the Measurements to create. Either all requests must have the same parent and the parent must match the top-level parent, or all requests must leave the parent unset.A maximum of 50 Measurements can be created in a single batch.

Response

measurements

Measurement[]

The Measurement resources.

Example

message BatchCreateMeasurementsRequest {
  string parent = 1 [(google.api.field_behavior) = REQUIRED];
  repeated CreateMeasurementRequest requests = 2 [(google.api.field_behavior) = REQUIRED];
}

message BatchCreateMeasurementsResponse {
  repeated Measurement measurements = 1;
}

BatchGetMeasurements

Batch gets Measurements. Results in a NOT_FOUND error if any of the specified Measurements do not exist. Request

parent

string

required

Resource name of the parent MeasurementConsumer.Format: measurementConsumers/{measurement_consumer}

names

string[]

required

List of resource names. A maximum of 50 Measurements can be retrieved in a single batch.

Response

measurements

Measurement[]

The Measurement resources.

Example

message BatchGetMeasurementsRequest {
  string parent = 1 [(google.api.field_behavior) = REQUIRED];
  repeated string names = 2 [(google.api.field_behavior) = REQUIRED];
}

message BatchGetMeasurementsResponse {
  repeated Measurement measurements = 1;
}

State Transitions

Measurements follow a specific state transition workflow:

  [Created]
      |
      v
AWAITING_REQUISITION_FULFILLMENT
      |
      +---> CANCELLED (terminal)
      |
      v
  COMPUTING
      |
      +---> FAILED (terminal)
      +---> CANCELLED (terminal)
      |
      v
  SUCCEEDED (terminal)

State Descriptions

AWAITING_REQUISITION_FULFILLMENT: The measurement is waiting for all linked requisitions to be fulfilled by data providers.
COMPUTING: All requisitions have been fulfilled and the computation is running.
SUCCEEDED: The measurement completed successfully and results are available.
FAILED: The measurement failed due to an error (e.g., certificate revoked, requisition refused, computation participant failed).
CANCELLED: The measurement was cancelled by the measurement consumer.

Workflow

Create Measurement: A MeasurementConsumer creates a measurement specifying the data providers and measurement specifications.
Requisition Creation: The system automatically creates requisitions for each data provider.
Await Fulfillment: The measurement enters AWAITING_REQUISITION_FULFILLMENT state while waiting for data providers.
Data Collection: Data providers fulfill requisitions by providing the requested data.
Computation: Once all requisitions are fulfilled, the measurement transitions to COMPUTING state.
Result: The measurement transitions to either SUCCEEDED with results or FAILED with failure information.

Overview

Identity & Access

Measurement Resources

Event Management

Model Management

Panel Matching

Populations

Resource

Measurement

DataProviderEntry

Result

Failure

Methods

GetMeasurement

CreateMeasurement

ListMeasurements

CancelMeasurement

BatchCreateMeasurements

BatchGetMeasurements

State Transitions

State Descriptions

Workflow

Build docs developers (and LLMs) love

Overview

Identity & Access

Measurement Resources

Event Management

Model Management

Panel Matching

Populations

​Resource

​Measurement

​DataProviderEntry

​Result

​Failure

​Methods

​GetMeasurement

​CreateMeasurement

​ListMeasurements

​CancelMeasurement

​BatchCreateMeasurements

​BatchGetMeasurements

​State Transitions

​State Descriptions

​Workflow

Build docs developers (and LLMs) love

Resource

Measurement

DataProviderEntry

Result

Failure

Methods

GetMeasurement

CreateMeasurement

ListMeasurements

CancelMeasurement

BatchCreateMeasurements

BatchGetMeasurements

State Transitions

State Descriptions

Workflow