Custom Search JSON API: 소개
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
이 문서는 Custom Search JSON API 및 사용법을 익히는 데 도움이 됩니다.
시작하기 전에
프로그래밍 검색 엔진 만들기
사용자는 API를 호출하여 프로그래밍 검색 엔진의 기존 인스턴스에 요청을 보냅니다.
따라서 API를 사용하기 전에 제어판에서 API를 만들어야 합니다. 다양한 구성 옵션에 대한 자세한 내용은 튜토리얼을 참조하세요.
검색엔진 ID를 만든 후 개요 페이지의 기본 섹션에서
확인할 수 있습니다. API에서 사용하는 cx 매개변수입니다.
API 키로 Google에 애플리케이션 식별
Custom Search JSON API를 사용하려면 API 키를 사용해야 합니다. API 키는 Google에서 클라이언트를 식별하는 방법입니다.
API 키가 있으면 애플리케이션에서 쿼리 매개변수 key=yourAPIKey을 모든 요청 URL에 추가할 수 있습니다. API 키는 URL에 삽입해도 안전하며 인코딩이 필요하지 않습니다.
API 개요
API 작업
Custom Search JSON API에서는 하나의 메서드만 호출할 수 있습니다.
| 작업 |
설명 |
REST HTTP 매핑 |
| list |
프로그래밍 검색 엔진에서 요청된 검색 결과를 반환합니다. |
GET |
API 데이터 모델
Custom Search JSON API에 대한 검색어의 결과는 다음 세 가지 유형의 데이터가 포함된 JSON 객체입니다.
- 요청된 검색 (및 관련 검색 요청도 해당)을 설명하는 메타데이터
- 프로그래밍 검색 엔진을 설명하는 메타데이터입니다.
- 검색 결과
자세한 내용은 REST 사용의 응답 데이터 섹션을 참조하세요.
데이터 모델은 OpenSearch 1.1 사양을 기반으로 합니다. Custom Search JSON API는 표준 OpenSearch 속성 외에도 두 개의 맞춤 속성과 두 개의 맞춤 쿼리 역할을 정의합니다.
- 맞춤 속성
cx: 프로그래밍 검색 엔진의 식별자입니다.safe: 반환된 결과를 필터링하기 위한 세이프서치 수준의 설명입니다.
- 맞춤 쿼리 역할
nextPage: 결과의 다음 논리 페이지(있는 경우)에 액세스하는 데 쿼리를 사용할 수 있음을 나타내는 역할입니다.previousPage: 결과의 이전 논리 페이지(있는 경우)에 액세스하는 데 쿼리를 사용할 수 있음을 나타내는 역할입니다.
사용해 보기
코드를 작성하지 않고 API를 둘러보면서 기능을 살펴보려면 'API 사용해 보기' 도구를 방문하세요.
매개변수에 대한 자세한 설명은 cse.list 참조를 확인하세요.
HTTP 요청을 통해 API를 사용하는 방법을 알아보려면 REST 사용으로 이동하세요.
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2025-08-31(UTC)
[null,null,["최종 업데이트: 2025-08-31(UTC)"],[[["\u003cp\u003eThis guide introduces the Custom Search JSON API and provides instructions for its use.\u003c/p\u003e\n"],["\u003cp\u003eBefore using the API, you need to create a Programmable Search Engine and obtain an API key.\u003c/p\u003e\n"],["\u003cp\u003eThe API allows you to retrieve search results from your Programmable Search Engine using a single \u003ccode\u003elist\u003c/code\u003e operation.\u003c/p\u003e\n"],["\u003cp\u003eThe API returns results in JSON format containing search metadata, engine details, and the search results themselves.\u003c/p\u003e\n"],["\u003cp\u003eYou can experiment with the API using the provided "Try this API" tool or learn more through detailed documentation and examples.\u003c/p\u003e\n"]]],[],null,["# Custom Search JSON API: Introduction\n\nThis document will help you to get familiar with Custom Search JSON API and its usage.\n\nBefore you start\n----------------\n\n### Create Programmable Search Engine\n\nBy calling the API user issues requests against an existing instance of\nProgrammable Search Engine.\nTherefore, before using the API, you need to create one in the\n[Control Panel](https://programmablesearchengine.google.com/controlpanel/create)\n. Follow the [tutorial](/custom-search/docs/tutorial/creatingcse)\nto learn more about different configuration options.\nOnce it is created, you can find the **Search Engine ID** in the **Overview**\npage's **Basic** section. This is the `cx` parameter used by the API.\n\n### Identify your application to Google with API key\n\nCustom Search JSON API requires the use of an API key. An API key is a way to identify your client to Google.\n\n- [Programmable Search Engine](https://cse.google.com/) (free edition) users: Get a Key\n\nAfter you have an API key, your application can append the query parameter\n`key=yourAPIKey` to all request URLs. The API key is safe for embedding in URLs,\nit doesn't need any encoding.\n\nAPI overview\n------------\n\n### API operations\n\nThere is only one method to invoke in the Custom Search JSON API:\n\n| Operation | Description | REST HTTP mapping |\n|------------------------------------------------------|-------------------------------------------------------------------------|-------------------|\n| [list](/custom-search/v1/reference/rest/v1/cse/list) | Returns the requested search results from a Programmable Search Engine. | `GET` |\n\n### API data model\n\nThe result of a search query to the Custom Search JSON API is a JSON object that includes three types of data:\n\n- Metadata describing the requested search (and, possibly, related search requests)\n- Metadata describing the Programmable Search Engine\n- Search results\n\nSee the Response data section of [Using REST](/custom-search/v1/using_rest#response_data) for more details.\n\nThe data model is based on the OpenSearch 1.1 Specification. In addition to the standard OpenSearch properties, the Custom Search JSON API defines two custom properties and two custom query roles:\n\n- Custom properties\n - `cx`: The identifier of the Programmable Search Engine.\n - `safe`: A description of the safe search level for filtering the returned results.\n- Custom query roles\n - `nextPage`: A role that indicates the query can be used to access the next logical page of results, if any.\n - `previousPage`: A role that indicates the query can be used to access the previous logical page of results, if any.\n\nTry it\n------\n\nTo play around and see what the API can do, without writing any code, visit the\n[\"Try this API\" tool](/custom-search/v1/reference/rest/v1/cse/list?apix=true).\n\nFor a full description of parameters visit the\n[cse.list reference](/custom-search/v1/reference/rest/v1/cse/list).\n\nTo learn how to use the API via HTTP requests, continue to\n[Using REST](/custom-search/v1/using_rest)."]]
