Report streaming using GoogleAdsService

  • To retrieve Google Ads API entities and reporting data, you can use either GoogleAdsService.SearchStream or GoogleAdsService.Search.

  • While both methods are suitable for production and fetching objects and reports, SearchStream provides a stream of GoogleAdsRow objects in a single continuous response, whereas Search returns pages of GoogleAdsRow objects over multiple responses.

  • SearchStream sends a single request and initiates a persistent connection, allowing data packets to download immediately and potentially offering improved performance for bigger reports compared to the paged requests of Search.

  • For multiple page reports, SearchStream is typically faster than Search as it avoids multiple round trips.

  • Daily limits for both methods are based on access levels, and a single query or report is counted as one operation regardless of whether it is paged or streamed.

To retrieve Google Ads API entities and reporting data, use one of these methods:

Here are the high-level distinctions for the two methods:

GoogleAdsService.SearchStream GoogleAdsService.Search
Suitable for production code Yes Yes
Service GoogleAdsService GoogleAdsService
Scenario Fetching objects and reports Fetching objects and reports
Response Stream of GoogleAdsRow objects Pages of GoogleAdsRow objects
Response's fields Only those specified in the query Only those specified in the query
Daily limits Daily limits based on access levels Daily limits based on access levels

While Search can send multiple paginated requests to download the entire report, SearchStream sends a single request and initiates a persistent connection with the Google Ads API regardless of report size.

For SearchStream, data packets start to download immediately with the entire result cached in a data buffer. Your code can start reading the buffered data without having to wait for the entire stream to finish.

By eliminating the round-trip network time required to request each individual page of a Search response, depending on your app, SearchStream can offer improved performance over paging, especially for bigger reports.

Example

This example looks at a report that consists of 100,000 rows. The following table breaks down the accounting differences between the two methods.

SearchStream Search
Page size Not Applicable 10,000 rows per page
Number of API requests 1 request 10 requests
Number of API responses 1 continuous stream 10 responses

Performance factors

For most use cases, we recommend SearchStream over Search for the following reasons:

  • For single page reports (under 10,000 rows): No significant performance differences between the two methods.

  • For multiple page reports: SearchStream is typically faster since multiple round trips are avoided, and reading or writing from disk cache is less of a factor.

Rate limits

Daily limits for both methods adhere to the standard limits and access levels of your developer token. A single query or report is counted as one operation regardless of the result being paged or streamed.

Previous
Labels
Next
Paging