Search & SearchStream

Video: Reporting

The Google Ads API has a unified attribute retrieval and metrics reporting mechanism that lets you create queries using the Google Ads Query Language. This enables complex queries that can return large quantities of data about individual Google Ads accounts.

You can create queries using either of the Search or SearchStream methods. Both methods support the same queries and return equivalent results. The Search method returns data in fixed size pages of 10,000 rows, enabling you to iterate over a result set using pagination. This could be advantageous in low bandwidth or unreliable network conditions, for example, to segment a large result set into smaller responses that can be re-fetched if a connection is lost. The SearchStream method, on the other hand, streams the entire result set back in a single response, which can be more efficient for bulk data retrieval.

Both Search and SearchStream use the same base URL:

    https://googleads.googleapis.com/v18/customers/CUSTOMER_ID/googleAds
POST /v18/customers/CUSTOMER_ID/googleAds:search HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
"query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'"
}

If there are more than 10,000 rows in the results a nextPageToken is returned in the response:

{
  "results": [
    // ...
    // ...
    // ...
  ],
  "nextPageToken": "CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B",
  "fieldMask": "adGroupCriterion.keyword.text,adGroupCriterion.status"
}

Repeating the same query with a pageToken added with the values from the previous request fetches the next page of results:

POST /v18/customers/CUSTOMER_ID/googleAds:search HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
"query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'",
"pageToken": "CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B"
}

To use the SearchStream method, which returns all results in a single streamed response, change the service method in the URL to searchStream (pageSize and pageToken are not required by SearchStream):

POST /v18/customers/CUSTOMER_ID/googleAds:searchStream HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
    "query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'"
}