Mantieni tutto organizzato con le raccolte
Salva e classifica i contenuti in base alle tue preferenze.
Questo documento ti aiuterà ad acquisire familiarità con l'API JSON Custom Search e il suo utilizzo.
Prima di iniziare
Creare un Motore di ricerca programmabile
La chiamata all'utente dell'API invia le richieste a un'istanza esistente del
Motore di ricerca programmabile.
Pertanto, prima di utilizzare l'API, devi crearne una nel Pannello di controllo. Segui il tutorial per scoprire di più sulle varie opzioni di configurazione.
Una volta creato, puoi trovare l'ID motore di ricerca nella sezione Informazioni di base della pagina Panoramica. Questo è il parametro cx utilizzato dall'API.
Identifica la tua applicazione su Google con la chiave API
L'API JSON di Ricerca personalizzata richiede l'utilizzo di una chiave API. Una chiave API è un modo per identificare il tuo client su Google.
Una volta che disponi di una chiave API, l'applicazione può aggiungere il parametro di ricerca key=yourAPIKey a tutti gli URL delle richieste. Puoi incorporare la chiave API negli URL in sicurezza, poiché non è necessaria alcuna codifica.
Panoramica dell'API
Operazioni API
Esiste un solo metodo per richiamare nell'API JSON Custom Search:
Restituisce i risultati di ricerca richiesti da un Motore di ricerca programmabile.
GET
Modello dei dati API
Il risultato di una query di ricerca inviata all'API JSON Custom Search è un oggetto JSON che include tre tipi di dati:
Metadati che descrivono la ricerca richiesta (e, possibilmente, le richieste di ricerca correlata)
Metadati che descrivono il Motore di ricerca programmabile
Risultati di ricerca
Per ulteriori dettagli, consulta la sezione Dati sulle risposte di Utilizzo di REST.
Il modello dei dati si basa sulla specifica OpenSearch 1.1. Oltre alle proprietà OpenSearch standard, l'API JSON Custom Search definisce due proprietà personalizzate e due ruoli query personalizzate:
Proprietà personalizzate
cx: l'identificatore del Motore di ricerca programmabile.
safe: una descrizione del livello di SafeSearch per filtrare i risultati restituiti.
Ruoli query personalizzati
nextPage: un ruolo che indica che la query può essere utilizzata per accedere alla pagina logica dei risultati successiva, se disponibile.
previousPage: un ruolo che indica che la query può essere utilizzata per accedere all'eventuale pagina logica precedente dei risultati.
Prova
Per sperimentare e vedere cosa può fare l'API, senza scrivere alcun codice, visita lo strumento "Prova questa API".
[[["Facile da capire","easyToUnderstand","thumb-up"],["Il problema è stato risolto","solvedMyProblem","thumb-up"],["Altra","otherUp","thumb-up"]],[["Mancano le informazioni di cui ho bisogno","missingTheInformationINeed","thumb-down"],["Troppo complicato/troppi passaggi","tooComplicatedTooManySteps","thumb-down"],["Obsoleti","outOfDate","thumb-down"],["Problema di traduzione","translationIssue","thumb-down"],["Problema relativo a esempi/codice","samplesCodeIssue","thumb-down"],["Altra","otherDown","thumb-down"]],["Ultimo aggiornamento 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)."]]
