JSON/Atom Custom Search API: Introduction

This document will help you to get familiar with JSON/Atom Custom Search API and its usage.

Before you start

Create Custom Search Engine

By calling the API user issues requests against an existing instance of Custom Search Engine or Google Site Search. 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 engine's ID in the Setup > Basics > Details section of the Control Panel. This is the cx parameter used by the API.

Identify your application to Google with API key

JSON/Atom Custom Search API requires the use of an API key. An API key is a way to identify your client to Google.

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 JSON/Atom Custom Search API:

Operation Description REST HTTP mapping
list Returns the requested search results from a Custom Search Engine. GET

API data model

The result of a search query to the Custom Search Engine API is a JSON or Atom object that includes three types of data:

  • Metadata describing the requested search (and, possibly, related search requests)
  • Metadata describing the custom 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 JSON/Atom Custom Search API defines three custom properties and two custom query roles:

  • Custom properties
    • cx: The identifier of the custom 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 APIs Explorer.

To learn how to use the API via HTTP requests, continue to Using REST.

Send feedback about...

Custom Search