This document will help you to get familiar with Custom Search JSON API and its usage.
Before you start
Create Programmable Search Engine
By calling the API user issues requests against an existing instance of
Programmable Search Engine.
Therefore, before using the API, you need to create one in the
Control Panel
. Follow the tutorial
to learn more about different configuration options.
Once it is created, you can find the Search Engine ID in the Overview
page's Basic section. This is the cx parameter used by the API.
Identify your application to Google with API key
Custom Search JSON API requires the use of an API key. An API key is a way to identify your client to Google.
- Programmable Search Engine (free edition) users: Get a Key
After you have an API key, your application can append the query parameter
key=yourAPIKey to all request URLs. The API key is safe for embedding in URLs,
it doesn't need any encoding.
API overview
API operations
There is only one method to invoke in the Custom Search JSON API:
| Operation | Description | REST HTTP mapping |
|---|---|---|
| list | Returns the requested search results from a Programmable Search Engine. | GET |
API data model
The result of a search query to the Custom Search JSON API is a JSON object that includes three types of data:
- Metadata describing the requested search (and, possibly, related search requests)
- Metadata describing the Programmable Search Engine
- Search results
See the Response data section of Using REST for more details.
The 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:
- Custom properties
cx: The identifier of the Programmable Search Engine.safe: A description of the safe search level for filtering the returned results.
- Custom query roles
nextPage: A role that indicates the query can be used to access the next logical page of results, if any.previousPage: A role that indicates the query can be used to access the previous logical page of results, if any.
Try it
To play around and see what the API can do, without writing any code, visit the "Try this API" tool.
For a full description of parameters visit the cse.list reference.
To learn how to use the API via HTTP requests, continue to Using REST.