Custom Search JSON API의 REST 또는 Representational State Transfer는 일반적인 RESTful API와 다소 다릅니다. API는 리소스에 대한 액세스 권한을 제공하는 대신 서비스에 대한 액세스 권한을 제공합니다. 따라서 API는 서비스 엔드포인트 역할을 하는 단일 URI를 제공합니다.
URI에 HTTP GET 요청을 전송하여 특정 검색의 결과를 검색할 수 있습니다. 검색 요청의 세부정보를 쿼리 매개변수로 전달합니다. Custom Search JSON API URI의 형식은 다음과 같습니다.
url 속성: 이 요청에서 반환된 결과에 사용된 OpenSearch 템플릿에 관한 정보가 포함되어 있습니다.
queries 속성: 가능한 검색의 특성을 설명하는 객체 배열입니다. 배열의 각 객체 이름은 OpenSearch 쿼리 역할의 이름이거나 이 API에 의해 정의된 두 가지 맞춤 역할(previousPage 및 nextPage) 중 하나입니다. 가능한 쿼리 역할 객체는 다음과 같습니다.
request: 현재 결과 집합의 쿼리를 설명하는 메타데이터입니다.
이 역할은 응답에 항상 표시됩니다.
항상 요소가 하나만 있는 배열입니다.
nextPage: 결과의 다음 페이지에 사용할 쿼리를 설명하는 메타데이터입니다.
현재 결과가 마지막 페이지인 경우 이 역할은 표시되지 않습니다.
참고: 이 API는 최대 100개의 결과만 반환합니다.
이 속성이 있는 경우 항상 요소가 하나만 있는 배열입니다.
previousPage: 이전 결과 페이지에 사용할 쿼리를 설명하는 메타데이터입니다.
현재 결과가 첫 번째 페이지인 경우 표시되지 않습니다.
이 속성이 있는 경우 항상 요소가 하나만 있는 배열입니다.
검색엔진 메타데이터
context 속성에는 검색 쿼리를 실행한 검색엔진을 설명하는 메타데이터가 있습니다. 여기에는 검색엔진의 이름과 검색을 세분화하기 위해 제공하는 모든 측면 객체가 포함됩니다.
검색 결과
items 배열에는 실제 검색 결과가 포함됩니다. 검색 결과에는 결과를 설명하는 URL, 제목, 텍스트 스니펫이 포함됩니다. 또한 해당하는 경우 리치 스니펫 정보를 포함할 수 있습니다.
callback 쿼리 매개변수와 콜백 함수를 사용하여 JavaScript에서 REST를 사용하여 Custom Search JSON API를 호출할 수 있습니다. 이를 통해 서버 측 코드를 작성하지 않고도 프로그래밍 검색 엔진 데이터를 표시하는 풍부한 애플리케이션을 작성할 수 있습니다.
다음 예에서는 이 접근 방식을 사용하여 lecture 검색어의 검색 결과 첫 페이지를 표시합니다.
<html>
<head>
<title>CustomSearchJSONAPIExample</title>
</head>
<body>
<divid="content"></div>
<pid="demo"></p>
<script>
functionhndlr(response){if(response.items==null){document.getElementById("demo").innerHTML+=`<h3> No Results Found </h3>`;}else{for(vari=1;i < response.items.length;i++){varitem=response.items[i];// Make sure HTML in item.htmlTitle is escaped.document.getElementById("content").append(document.createElement("br"),document.createTextNode(item.htmlTitle));}}}</script>
<scriptsrc="https://www.googleapis.com/customsearch/v1?key=YOUR-KEY&cx=017576662512468239146:omuauf_lfve&q=lecture&callback=hndlr">
</script>
</body>
</html>
[[["이해하기 쉬움","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-08-31(UTC)"],[[["\u003cp\u003eThe Custom Search JSON API provides a RESTful service for retrieving search results from a Programmable Search Engine using HTTP GET requests.\u003c/p\u003e\n"],["\u003cp\u003eRequests require an API key, Programmable Search Engine ID (cx), and a search query (q) passed as URL parameters.\u003c/p\u003e\n"],["\u003cp\u003eResponse data includes search metadata, search engine information, and an array of search results with URLs, titles, and snippets.\u003c/p\u003e\n"],["\u003cp\u003eDevelopers can integrate the API with JavaScript using the \u003ccode\u003ecallback\u003c/code\u003e parameter for client-side rendering of search results.\u003c/p\u003e\n"],["\u003cp\u003eThe API returns up to the first 100 search results, and the length of the search request should be within 2048 characters.\u003c/p\u003e\n"]]],[],null,["# Use REST to Invoke the API\n\nThis document describes how to use the Custom Search JSON API.\n\nMake a request\n--------------\n\nREST, or [Representational State\nTransfer](http://en.wikipedia.org/wiki/Representational_State_Transfer), in the\nCustom Search JSON API is somewhat different from the usual RESTful APIs. Instead of\nproviding access to resources, the API provides access to a service. As a\nresult, the API provides a single URI that acts as the service endpoint.\n\nYou can retrieve results for a particular search by sending an HTTP `GET`\nrequest to its URI. You pass in the details of the search request as query\nparameters. The format for the Custom Search JSON API URI is: \n\n https://www.googleapis.com/customsearch/v1?[parameters]\n\nThree query `[parameters]` are required with each search request:\n\n- **API key** - Use the `key` query parameter to [identify your\n application](/custom-search/json-api/v1/introduction#identify_your_application_to_google_with_api_key).\n\n - **Programmable Search Engine ID** - Use `cx` to specify the Programmable Search Engine you want to use to perform this search. The search engine must be created with the [Control Panel](https://cse.google.com/all) Note: The Search Engine ID (cx) can be of different format (e.g. 8ac1ab64606d234f1)\n- **Search query** - Use the `q` query parameter to specify your search\n expression.\n\nAll other [query parameters](/custom-search/v1/reference/rest/v1/cse/list) are\noptional.\n\nHere is an example of a request which searches a test Programmable Search Engine\nfor *lectures*: \n\n```\nGET https://www.googleapis.com/customsearch/v1?key=INSERT_YOUR_API_KEY&cx=017576662512468239146:omuauf_lfve&q=lectures\n```\n| **Note:** The limit on the length of the search request should be within 2048 characters.\n\nQuery parameters\n----------------\n\nThere are two types of parameters that you can pass in your request:\n\n- API-specific parameters - define properties of your search, like the search expression, number of results, language etc.\n- Standard query parameters - define technical aspects of your request, like the API key.\n\nAll parameter values need to be URL encoded.\n\n### API-specific query parameters\n\nRequest parameters that apply specifically to the Custom Search JSON API and define your\nsearch request are summarized in the\n[reference](/custom-search/v1/reference/rest/v1/cse/list#request).\n\n### Standard query parameters\n\nQuery parameters that apply to all Custom Search JSON API operations are documented at\n[System Parameters](https://cloud.google.com/apis/docs/system-parameters).\n\nResponse data\n-------------\n\nIf the request succeeds, the server responds with a `200 OK` HTTP status code\nand the response data in JSON format. You can look up the response data\nstructure in the\n[reference](/custom-search/v1/reference/rest/v1/cse/list#response).\n\nThe response data is a JSON object that includes three types of properties:\n\n- Metadata describing the requested search (and, possibly, related search requests)\n- Metadata describing the Programmable Search Engine\n- Search results\n\nFor a detailed description of each property, see the\n[reference](/custom-search/v1/reference/rest/v1/cse/list#response).\n\n### Search request metadata\n\nThe search metadata includes:\n\n- `url` property, which has information about the [OpenSearch template](https://github.com/dewitt/opensearch/blob/master/opensearch-1-1-draft-6.md#the-url-element) used for the results returned in this request.\n- `queries` property, which is an array of objects describing the characteristics of possible searches. The name of each object in the array is either the name of an [OpenSearch\n query role](https://github.com/dewitt/opensearch/blob/master/opensearch-1-1-draft-6.md#local-role-values) or one of the two custom roles defined by this API: `previousPage` and `nextPage`. Possible query role objects include:\n - `request`: Metadata describing the query for the current set of results.\n - This role is always present in the response.\n - It is always an array with just one element.\n - `nextPage`: Metadata describing the query to use for the next page of results.\n - This role is not present if the current results are the last page. **Note:**This API returns up to the first 100 results only.\n - When present, it is always a array with just one element.\n - `previousPage`: Metadata describing the query to use for the previous page of results.\n - Not present if the current results are the first page.\n - When present, it is always a array with just one element.\n\n### Search engine metadata\n\nThe `context` property has metadata describing the search engine that performed\nthe search query. It includes the name of the search engine, and any [facet\nobjects](/custom-search/docs/refinements#create) it provides for refining a\nsearch.\n\n### Search results\n\nThe `items` array contains the actual search results. The search results include\nthe URL, title and text snippets that describe the result. In addition, they can\ncontain [rich snippet](/custom-search/docs/snippets) information, if\napplicable.\n\nIf the search results include a `promotions` property, it contains a set of\n[promotions](/custom-search/docs/promotions#sl).\n\nREST from JavaScript\n--------------------\n\nYou can invoke the Custom Search JSON API using REST from JavaScript, using the\n`callback` query parameter and a callback function. This lets you write rich\napplications that display Programmable Search Engine data without writing any\nserver side code.\n\nThe following example uses this approach to display the first page of search\nresults for the query **lecture**: \n\n \u003chtml\u003e\n \u003chead\u003e\n \u003ctitle\u003eCustom Search JSON API Example\u003c/title\u003e\n \u003c/head\u003e\n \u003cbody\u003e\n \u003cdiv id=\"content\"\u003e\u003c/div\u003e\n \u003cp id=\"demo\"\u003e\u003c/p\u003e\n \u003cscript\u003e\n function hndlr(response) {\n if (response.items == null) {\n document.getElementById(\"demo\").innerHTML +=`\u003ch3\u003e No Results Found \u003c/h3\u003e`;\n } else {\n for (var i = 1; i \u003c response.items.length; i++) {\n var item = response.items[i];\n // Make sure HTML in item.htmlTitle is escaped.\n document.getElementById(\"content\").append(\n document.createElement(\"br\"),\n document.createTextNode(item.htmlTitle)\n );\n }\n }\n }\n \u003c/script\u003e\n \u003cscript src=\"https://www.googleapis.com/customsearch/v1?key=YOUR-KEY&cx=017576662512468239146:omuauf_lfve&q=lecture&callback=hndlr\"\u003e\n \u003c/script\u003e\n \u003c/body\u003e\n \u003c/html\u003e\n\n| **Note:** Replace cx with your Search Engine ID. Make sure your Search Engine return results for the query."]]
