Calls to the Search Ads 360 Reporting API are typically made through your client library. See Client libraries explained for more information. However, knowledge about the structure of the underlying request details can be useful when testing and debugging.
Search Ads 360 Reporting API is a gRPC API with REST bindings. This means that you can make calls to the API in two alternative ways:
- Preferred method
- Use a client library:
- Create the body of the request as a protocol buffer.
- Send the request to the server using HTTP/2.
- Deserialize the response to a protocol buffer.
- Interpret the results.
- Optional alternative method
- Use REST:
- Create the body of request as a JSON object.
- Send the request to the server using HTTP 1.1.
- Deserialize the response as a JSON object.
- Interpret the results.
See Google Cloud APIs for more information.
The following sections apply to both gRPC and REST protocols.
Resource names
Most objects in the API are identified by their resource name strings. These strings also serve as URLs when using the REST interface.
See Reference > REST for more information about supported resources and their path representation. The same format is used for other services.
Composite IDs
If the ID of an object is not globally unique, a composite ID for that object is constructed by prepending its parent ID and a tilde (~).
For example, because an ad group ad ID is not globally unique, the parent object (ad group) ID is prepended to it resulting in a unique composite ID.
Example: AdGroupId of 123 + ~ + AdGroupAdId of 45678
= composite ad group ad ID of 123~45678.
Request headers
The HTTP headers (or gRPC metadata) in the following sections should be included in the body of the request.
Authorization
You need to include an OAuth2 access token in the form:
Authorization: Bearer [OAUTH_2.0_ACCESS_TOKEN]
The token should identify either a manager account acting on behalf of a client or an advertiser directly managing their own sub-manager or client account. See About Search Ads 360 manager accounts and Authentication to learn more.
Login customer ID header
The login-customer-id header is required when using a manager account to
access a sub-manager or client account. It is not required when accessing a
sub-manager or client account directly. Although not strictly necessary, we
recommend always specifying the login-customer-id for authenticated users who
have access to more than one account. This avoids ambiguity and prevents
unintentionally setting the context to the incorrect account.
The request should include the customer ID of the authorized user, without
hyphens (-), for example:
https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/campaignBudgets
Setting the login-customer-id is equivalent to choosing an account in the
Search Ads 360 UI after signing in or clicking on your profile image at the top
right.
Response headers
The following headers (or gRPC trailing-metadata) are returned with the response body. We recommend that you log these values for debugging purposes.
Request ID
The request-id header is a string that uniquely identifies the request.