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
(pageToken
is 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'" }