Using REST to Invoke the API

This document describes how to use the JSON/Atom Custom Search API.

Making a request

REST, or Representational State Transfer, in the JSON/Atom Custom Search API is somewhat different from traditional REST. Instead of providing access to resources, the API provides access to a service. As a result, the API provides a single URI that acts as the service endpoint.

You can retrieve results for a particular search by sending an HTTP GET request to its URI. You pass in the details of the search request as query parameters. The format for the JSON/Atom Custom Search API URI is:

https://www.googleapis.com/customsearch/v1?parameters

Three query parameters are required with each search request:

API key - Use the key query parameter to identify your application.
Custom search engine ID - Use either cx or cref to specify the custom search engine you want to use to perform this search.
- Use cx for a search engine created with the Control Panel
- Use cref for a linked custom search engine (does not apply for Google Site Search).
- If both are specified, cx is used.
Search query - Use the q query parameter to specify your search expression.

All other query parameters are optional.

Here is an example of a request which searches a test Custom Search Engine for lectures:

GET https://www.googleapis.com/customsearch/v1?key=INSERT_YOUR_API_KEY&cx=017576662512468239146:omuauf_lfve&q=lectures

Query parameters

There are two types of parameters that you can pass in your request:

API-specific parameters - define properties of your search, like the search expression, number of results, language etc.
Standard query parameters - define technical aspects of your request, like the API key or data format for the response (JSON or Atom).

All parameter values need to be URL encoded.

API-specific query parameters

Request parameters that apply specifically to the JSON/Atom Custom Search API and define your search request are summarized in the reference.

Standard query parameters

All parameters are optional except where noted.

Parameter	Meaning	Notes
`alt`	Data format for the response.	Valid values: `json`, `atom` Default value: `json`
`callback`	Callback function.	Name of the JavaScript callback function that handles the response. Used in JavaScript JSON-P requests.
`fields`	Selector specifying a subset of fields to include in the response.	For more information, see the partial response section in the Performance Tips document. Use for better performance.
`key`	API key. (REQUIRED)	Your API key identifies your project and provides you with API access, quota, and reports. Obtain your project's API key from the Google API Console.
`prettyPrint`	Returns response with indentations and line breaks.	Returns the response in a human-readable format if `true`. Default value: `true`. When this is `false`, it can reduce the response payload size, which might lead to better performance in some environments.
`quotaUser`	Alternative to `userIp`.	Lets you enforce per-user quotas from a server-side application even in cases when the user's IP address is unknown. This can occur, for example, with applications that run cron jobs on App Engine on a user's behalf. You can choose any arbitrary string that uniquely identifies a user, but it is limited to 40 characters. Overrides `userIp` if both are provided. Learn more about Capping API usage.
`userIp`	IP address of the end user for whom the API call is being made.	Lets you enforce per-user quotas when calling the API from a server-side application. Learn more about Capping API usage.

Response data

If the request succeeds, the server responds with a 200 OK HTTP status code and the response data in JSON or Atom format. You can look up the response data structure in the reference.

The response data is a JSON or Atom object that includes three types of properties:

Metadata describing the requested search (and, possibly, related search requests)
Metadata describing the custom search engine
Search results

For a detailed description of each property, see the reference.

Search request metadata

The search metadata includes:

url property, which has information about the OpenSearch template used for the results returned in this request.
queries property, which is an array of objects describing the characteristics of possible searches. The name of each object in the array is either the name of an OpenSearch query role or one of the two custom roles defined by this API: previousPage and nextPage. Possible query role objects include:
- request: Metadata describing the query for the current set of results.
  - This role is always present in the response.
  - It is always an array with just one element.
- nextPage: Metadata describing the query to use for the next page of results.
  - This role is not present if the current results are the last page. Note: This API returns up to the first 100 results only.
  - When present, it is always a array with just one element.
- previousPage: Metadata describing the query to use for the previous page of results.
  - Not present if the current results are the first page.
  - When present, it is always a array with just one element.

Search engine metadata

The context property has metadata describing the search engine that performed the search query. It includes the name of the search engine, and any facet objects it provides for refining a search.

Search results

The items array contains the actual search results. The search results include the URL, title and text snippets that describe the result. In addition, they can contain rich snippet information, if applicable.

If the search results include a promotions property, it contains a set of promotions.

REST from JavaScript

You can invoke the JSON/Atom Custom Search API using REST from JavaScript, using the callback query parameter and a callback function. This allows you to write rich applications that display Custom Search data without writing any server side code.

The following example uses this approach to display the first page of search results for the query cars:

<html>
  <head>
    <title>JSON/Atom Custom Search API Example</title>
  </head>
  <body>
    <div id="content"></div>
    <script>
      function hndlr(response) {
      for (var i = 0; i < response.items.length; i++) {
        var item = response.items[i];
        // in production code, item.htmlTitle should have the HTML entities escaped.
        document.getElementById("content").innerHTML += "<br>" + item.htmlTitle;
      }
    }
    </script>
    <script src="https://www.googleapis.com/customsearch/v1?key=<span class="apiparam">YOUR-KEY</span>&amp;cx=017576662512468239146:omuauf_lfve&amp;q=cars&amp;callback=hndlr">
    </script>
  </body>
</html>