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'" }