Caution: You are viewing documentation for the API's REST interface. Most of our official client libraries use gRPC. See the REST Introduction for details.
Google Ads API에는 Google Ads 쿼리 언어를 사용하여 쿼리를 만들 수 있는 통합 속성 검색 및 측정항목 보고 메커니즘이 있습니다.
이를 통해 개별 Google Ads 계정에 관한 대량의 데이터를 반환할 수 있는 복잡한 쿼리를 사용할 수 있습니다.
Search 또는 SearchStream 메서드를 사용하여 쿼리를 만들 수 있습니다.
두 메서드 모두 동일한 쿼리를 지원하고 동일한 결과를 반환합니다. Search 메서드는 10,000개 행의 고정 크기 페이지로 데이터를 반환하므로 페이지로 나누기를 사용하여 결과 집합을 반복할 수 있습니다. 예를 들어 연결이 끊긴 경우 다시 가져올 수 있는 더 작은 응답으로 큰 결과 집합을 분할하는 등 대역폭이 낮거나 신뢰할 수 없는 네트워크 조건에서 유용할 수 있습니다. 반면 SearchStream 메서드는 전체 결과 집합을 단일 응답으로 다시 스트리밍하므로 대량 데이터 검색에 더 효율적일 수 있습니다.
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'"}
결과에 10,000개가 넘는 행이 있는 경우 응답에 nextPageToken이 반환됩니다.
이전 요청의 값이 추가된 pageToken로 동일한 쿼리를 반복하면 결과의 다음 페이지가 가져와집니다.
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"}
단일 스트림 응답으로 모든 결과를 반환하는 SearchStream 메서드를 사용하려면 URL의 서비스 메서드를 searchStream로 변경합니다(pageToken는 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'"}
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["필요한 정보가 없음","missingTheInformationINeed","thumb-down"],["너무 복잡함/단계 수가 너무 많음","tooComplicatedTooManySteps","thumb-down"],["오래됨","outOfDate","thumb-down"],["번역 문제","translationIssue","thumb-down"],["샘플/코드 문제","samplesCodeIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 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."]]
