جستجوی سفارشی JSON API: مقدمه
با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
این سند به شما کمک می کند تا با جستجوی سفارشی JSON API و کاربرد آن آشنا شوید.
قبل از اینکه تو شروع کنی
ایجاد موتور جستجوی قابل برنامه ریزی
با فراخوانی API کاربر درخواست هایی را علیه یک نمونه موجود از موتور جستجوی قابل برنامه ریزی صادر می کند. بنابراین، قبل از استفاده از API، باید یکی را در کنترل پنل ایجاد کنید. برای کسب اطلاعات بیشتر در مورد گزینه های مختلف پیکربندی، آموزش را دنبال کنید. پس از ایجاد، می‌توانید شناسه موتور جستجو را در بخش اصلی صفحه نمای کلی پیدا کنید. این پارامتر cx است که توسط API استفاده می شود.
برنامه خود را در Google با کلید API شناسایی کنید
جستجوی سفارشی JSON API به استفاده از کلید API نیاز دارد. کلید API راهی برای شناسایی مشتری شما در گوگل است.
پس از داشتن یک کلید API، برنامه شما می تواند پارامتر query key=yourAPIKey به همه URL های درخواستی اضافه کند. کلید API برای جاسازی در URL ها ایمن است و نیازی به رمزگذاری ندارد.
نمای کلی API
عملیات API
فقط یک روش برای فراخوانی در جستجوی سفارشی JSON API وجود دارد:
| عمل | شرح | REST نقشه برداری HTTP |
|---|
| فهرست | نتایج جستجوی درخواستی را از یک موتور جستجوی قابل برنامه ریزی برمی گرداند. | GET |
مدل داده های API
نتیجه جستجوی جستجوی سفارشی JSON API یک شی JSON است که شامل سه نوع داده است:
- فراداده ای که جستجوی درخواستی را توصیف می کند (و احتمالاً درخواست های جستجوی مرتبط)
- ابرداده که موتور جستجوی قابل برنامه ریزی را توصیف می کند
- نتایج جستجو
برای جزئیات بیشتر به بخش پاسخ داده استفاده از REST مراجعه کنید.
مدل داده بر اساس مشخصات OpenSearch 1.1 است. علاوه بر ویژگی های OpenSearch استاندارد، Custom Search JSON API دو ویژگی سفارشی و دو نقش درخواست سفارشی را تعریف می کند:
- خواص سفارشی
-
cx : شناسه موتور جستجوی قابل برنامه ریزی. -
safe : شرحی از سطح جستجوی ایمن برای فیلتر کردن نتایج برگشتی.
- نقش های پرس و جو سفارشی
-
nextPage : نقشی که پرس و جو را نشان می دهد می تواند برای دسترسی به صفحه منطقی بعدی نتایج، در صورت وجود، استفاده شود. -
previousPage : نقشی که نشان دهنده پرس و جو است، می تواند برای دسترسی به صفحه منطقی قبلی نتایج، در صورت وجود، استفاده شود.
آن را امتحان کنید
برای بازی کردن و دیدن آنچه که API می تواند انجام دهد، بدون نوشتن هیچ کدی، از ابزار "Try this API" بازدید کنید.
برای توضیح کامل پارامترها به مرجع cse.list مراجعه کنید.
برای یادگیری نحوه استفاده از API از طریق درخواست‌های HTTP، به استفاده از REST ادامه دهید.
جز در مواردی که غیر از این ذکر شده باشد،محتوای این صفحه تحت مجوز Creative Commons Attribution 4.0 License است. نمونه کدها نیز دارای مجوز Apache 2.0 License است. برای اطلاع از جزئیات، به خطمشیهای سایت Google Developers مراجعه کنید. جاوا علامت تجاری ثبتشده Oracle و/یا شرکتهای وابسته به آن است.
تاریخ آخرین بهروزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی.
[null,null,["تاریخ آخرین بهروزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی."],[[["\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)."]]
