Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang
Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
Tài liệu này sẽ giúp bạn làm quen với API Tìm kiếm tuỳ chỉnh JSON và cách sử dụng nó.
Trước khi bắt đầu
Tạo Công cụ tìm kiếm có thể lập trình
Khi gọi API, người dùng sẽ đưa ra yêu cầu đối với một thực thể hiện có của Công cụ tìm kiếm có thể lập trình.
Do đó, trước khi sử dụng API, bạn cần tạo một API trong Bảng điều khiển. Làm theo hướng dẫn để tìm hiểu thêm về các tuỳ chọn cấu hình khác nhau.
Sau khi tạo mã này, bạn có thể tìm thấy Mã công cụ tìm kiếm trong phần Tổng quan của trang Cơ bản. Đây là tham số cx mà API sử dụng.
Xác định ứng dụng của bạn cho Google bằng khoá API
API Tìm kiếm tuỳ chỉnh JSON yêu cầu bạn phải sử dụng khoá API. Khoá API là một cách để Google xác định khách hàng của bạn.
Sau khi có khoá API, ứng dụng của bạn có thể thêm tham số truy vấn key=yourAPIKey vào tất cả URL yêu cầu. Khoá API có thể an toàn để nhúng trong URL mà không cần phương thức mã hoá.
Tổng quan về API
Toán tử API
Chỉ có một phương thức để gọi trong API Tìm kiếm tuỳ chỉnh JSON:
Trả về kết quả tìm kiếm được yêu cầu từ một Công cụ tìm kiếm có thể lập trình.
GET
Mô hình dữ liệu API
Kết quả của một cụm từ tìm kiếm đối với API Tìm kiếm tuỳ chỉnh JSON là đối tượng JSON bao gồm ba loại dữ liệu:
Siêu dữ liệu mô tả nội dung tìm kiếm mà bạn yêu cầu (và có thể cả các yêu cầu tìm kiếm có liên quan)
Siêu dữ liệu mô tả Công cụ tìm kiếm có thể lập trình
Kết quả tìm kiếm
Hãy xem mục Dữ liệu phản hồi trong bài viết Sử dụng REST để biết thêm chi tiết.
Mô hình dữ liệu này dựa trên Quy cách của OpenSearch 1.1. Ngoài các thuộc tính OpenSearch chuẩn, API JSON của Tìm kiếm tuỳ chỉnh xác định hai thuộc tính tuỳ chỉnh và hai vai trò của truy vấn tuỳ chỉnh:
Thuộc tính tuỳ chỉnh
cx: Giá trị nhận dạng của Công cụ tìm kiếm có thể lập trình.
safe: Nội dung mô tả mức độ an toàn của tính năng tìm kiếm để lọc kết quả trả về.
Vai trò truy vấn tuỳ chỉnh
nextPage: Vai trò cho biết truy vấn có thể dùng để truy cập vào trang kết quả logic tiếp theo (nếu có).
previousPage: Có vai trò cho biết truy vấn có thể dùng để truy cập vào trang kết quả logic trước đó (nếu có).
Thử ngay
Để khám phá và xem API có thể làm gì mà không cần viết bất kỳ mã nào, hãy truy cập công cụ"Dùng thử API này".
[[["Dễ hiểu","easyToUnderstand","thumb-up"],["Giúp tôi giải quyết được vấn đề","solvedMyProblem","thumb-up"],["Khác","otherUp","thumb-up"]],[["Thiếu thông tin tôi cần","missingTheInformationINeed","thumb-down"],["Quá phức tạp/quá nhiều bước","tooComplicatedTooManySteps","thumb-down"],["Đã lỗi thời","outOfDate","thumb-down"],["Vấn đề về bản dịch","translationIssue","thumb-down"],["Vấn đề về mẫu/mã","samplesCodeIssue","thumb-down"],["Khác","otherDown","thumb-down"]],["Cập nhật lần gần đây nhất: 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)."]]
