Attenzione: stai visualizzando la documentazione per l'interfaccia REST dell'API. La maggior parte delle nostre librerie client ufficiali utilizza gRPC. Per informazioni dettagliate, consulta la Introduzione a REST.
Puoi creare query utilizzando uno dei metodi Search o SearchStream.
Entrambi i metodi supportano le stesse query e restituiscono risultati equivalenti. Il metodo
Search restituisce i dati in pagine di dimensioni fisse di 10.000 righe, consentendoti
di scorrere un insieme di risultati utilizzando la paginazione. Ciò potrebbe essere vantaggioso in condizioni di rete con larghezza di banda ridotta o inaffidabile, ad esempio per segmentare un ampio insieme di risultati in risposte più piccole che possono essere recuperate nuovamente se la connessione viene persa. Il metodo SearchStream, invece, trasmette l'intero insieme di risultati
in un'unica risposta, il che può essere più efficiente per il recupero
dei dati collettivi.
Sia Search sia SearchStream utilizzano lo stesso URL di base:
POST/v21/customers/CUSTOMER_ID/googleAds:searchHTTP/1.1Host:googleads.googleapis.comContent-Type:application/jsonAuthorization:Bearer ACCESS_TOKENdeveloper-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'"}
Se i risultati contengono più di 10.000 righe,nella risposta viene restituito un nextPageToken:
Se ripeti la stessa query con un pageToken aggiunto con i valori della
richiesta precedente, viene recuperata la pagina successiva dei risultati:
POST/v21/customers/CUSTOMER_ID/googleAds:searchHTTP/1.1Host:googleads.googleapis.comContent-Type:application/jsonAuthorization:Bearer ACCESS_TOKENdeveloper-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"}
Per utilizzare il metodo SearchStream, che restituisce tutti i risultati in una singola risposta
in streaming, modifica il metodo del servizio nell'URL in searchStream
(pageToken non è richiesto da SearchStream):
POST/v21/customers/CUSTOMER_ID/googleAds:searchStreamHTTP/1.1Host:googleads.googleapis.comContent-Type:application/jsonAuthorization:Bearer ACCESS_TOKENdeveloper-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'"}
[[["Facile da capire","easyToUnderstand","thumb-up"],["Il problema è stato risolto","solvedMyProblem","thumb-up"],["Altra","otherUp","thumb-up"]],[["Mancano le informazioni di cui ho bisogno","missingTheInformationINeed","thumb-down"],["Troppo complicato/troppi passaggi","tooComplicatedTooManySteps","thumb-down"],["Obsoleti","outOfDate","thumb-down"],["Problema di traduzione","translationIssue","thumb-down"],["Problema relativo a esempi/codice","samplesCodeIssue","thumb-down"],["Altra","otherDown","thumb-down"]],["Ultimo aggiornamento 2025-09-05 UTC."],[[["\u003cp\u003eThe Google Ads API offers a unified mechanism for retrieving attributes and reporting metrics, allowing you to create complex queries using the Google Ads Query Language.\u003c/p\u003e\n"],["\u003cp\u003eYou can retrieve data using either the \u003ccode\u003eSearch\u003c/code\u003e or \u003ccode\u003eSearchStream\u003c/code\u003e methods, with \u003ccode\u003eSearch\u003c/code\u003e returning paginated results and \u003ccode\u003eSearchStream\u003c/code\u003e providing a single streamed response.\u003c/p\u003e\n"],["\u003cp\u003eFor large result sets exceeding 10,000 rows, use the \u003ccode\u003enextPageToken\u003c/code\u003e to retrieve subsequent pages of data when using the \u003ccode\u003eSearch\u003c/code\u003e method.\u003c/p\u003e\n"],["\u003cp\u003eBoth \u003ccode\u003eSearch\u003c/code\u003e and \u003ccode\u003eSearchStream\u003c/code\u003e utilize the same base URL and query structure, differing only in how the results are delivered.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eSearchStream\u003c/code\u003e method wraps results in a JSON array, unlike most other API calls which return a single JSON object.\u003c/p\u003e\n"]]],[],null,["# Search & SearchStream\n\nondemand_video\n[Video: Reporting](/google-ads/api/videos/catalog/working-with-rest-3)\n| **Note:** Refer to the [reporting guide](/google-ads/api/docs/reporting/overview) to learn about various reporting concepts.\n| **Note:** See the [Search](/google-ads/api/rest/examples#search) section of the accompanying examples for more complete examples.\n\nThe Google Ads API has a unified [attribute retrieval and metrics reporting\nmechanism](/google-ads/api/docs/reporting/overview)\nthat lets you create queries using the [Google Ads Query\nLanguage](/google-ads/api/docs/query/overview).\nThis enables complex queries that can return large quantities of data about\nindividual Google Ads accounts.\n\nYou can create queries using either of the `Search` or `SearchStream` methods.\nBoth methods support the same queries and return equivalent results. The\n`Search` method returns data in fixed size pages of 10,000 rows, enabling you\nto iterate over a result set using pagination. This could be advantageous in low\nbandwidth or unreliable network conditions, for example, to segment a large\nresult set into smaller responses that can be re-fetched if a connection is\nlost. The `SearchStream` method, on the other hand, streams the entire result\nset back in a single response, which can be more efficient for bulk data\nretrieval.\n\nBoth `Search` and `SearchStream` use the same base URL: \n\n```html\n https://googleads.googleapis.com/v21/customers/CUSTOMER_ID/googleAds\n``` \n\n```http\nPOST /v21/customers/\u003cvar translate=\"no\"\u003eCUSTOMER_ID\u003c/var\u003e/googleAds:search HTTP/1.1\nHost: googleads.googleapis.com\nContent-Type: application/json\nAuthorization: Bearer \u003cvar translate=\"no\"\u003eACCESS_TOKEN\u003c/var\u003e\ndeveloper-token: DEVELOPER_TOKEN\n\n{\n\"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'\"\n}\n```\n\nIf there are more than 10,000 rows in the results a `nextPageToken` is\nreturned in the response: \n\n```javascript\n{\n \"results\": [\n // ...\n // ...\n // ...\n ],\n \"nextPageToken\": \"CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B\",\n \"fieldMask\": \"adGroupCriterion.keyword.text,adGroupCriterion.status\"\n}\n```\n\nRepeating the same query with a `pageToken` added with the values from the\nprevious request fetches the next page of results: \n\n```http\nPOST /v21/customers/\u003cvar translate=\"no\"\u003eCUSTOMER_ID\u003c/var\u003e/googleAds:search HTTP/1.1\nHost: googleads.googleapis.com\nContent-Type: application/json\nAuthorization: Bearer \u003cvar translate=\"no\"\u003eACCESS_TOKEN\u003c/var\u003e\ndeveloper-token: DEVELOPER_TOKEN\n\n{\n\"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'\",\n\"pageToken\": \"CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B\"\n}\n```\n\nTo use the `SearchStream` method, which returns all results in a single streamed\nresponse, change the service method in the URL to `searchStream`\n(`pageToken` is not required by `SearchStream`): \n\n```http\nPOST /v21/customers/\u003cvar translate=\"no\"\u003eCUSTOMER_ID\u003c/var\u003e/googleAds:searchStream HTTP/1.1\nHost: googleads.googleapis.com\nContent-Type: application/json\nAuthorization: Bearer \u003cvar translate=\"no\"\u003eACCESS_TOKEN\u003c/var\u003e\ndeveloper-token: DEVELOPER_TOKEN\n\n{\n \"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'\"\n}\n```\n| **Note:** The results of a `SearchStream` API call are wrapped in a JSON array, whereas most other API calls return a single JSON object as the response message. See the [JSON mappings](/google-ads/api/rest/design/json-mappings) section for more info."]]
