Google Custom Search JSON API explained

Google custom search JSON API explained

Rate this article

Share this article

Google custom search JSON API is a RESTFUL API that lets you develop applications to get and show search results (web search, images) from Google custom search programmatically. With this API, you can use RESTFUL requests to get either web search or image search results in JSON format.

Google Custom Search JSON API explained

The existing documentation on creating a Google custom search using the API method is confusing and we will try to simplify the entire process here. If you are not a big fan of Google custom search, you could try out Expertrec’s custom search engine which doesn’t require coding expertise to implement it on your website.

In this article, we will see how we can create a custom search engine using the Google custom search API. We will also see what are the limitations of Google’s custom search API and how we can overcome them.

Create a zero-code custom search engine

You can try how to turn off Ads in Google search to remove ads in GCS.

If your Google site search is not working you can refer Google custom search support to find a solution. 

Google search script for sites is an easy and effective way to add search capabilities to your site. You can learn more about Google custom search JS examples

Google Custom Search JSON API

The Google Custom Search JSON API lets you develop websites and apps that can retrieve and display search results from Google custom search programmatically. With this API, you can use RESTful requests to get either web search or image search results in JSON format. With these results, you can build your own search frontend interface with the backend linked to Google custom search.

Things to do before you begin

Create a custom search engine

  1. Go to
  2. Enter your website URL.
  3. Click on create Google custom search.
  4. If you wish to create a custom search engine on multiple URLs, have a list of URLs ready with you in a Google doc or excel sheet that you can readily copy paste.

Get your Search engine ID

The Google custom search engine id (also known as the CX id) is a key that uniquely identifies your Google custom search engine.

Before using the Custom Search JSON API you will first need to create and configure your Google custom search engine. If you have not already created a Google custom search engine, you can start by visiting the Google custom search engine control panel.

After you have created a Google custom search engine, visit the instruction towards the end of this blog to learn how to locate your Search engine ID.

google custom search CX ID


Get your custom search API key

Custom Search JSON API requires the use of an API key. The API key uniquely identifies your API usage and make sure you don’t reveal your API key on any external forums as it might attract misuse. You can get your API key from here.

google custom search JSON API key

Google search script for sites is an easy and effective way to add search capabilities to your site. You can learn more about Google custom search JS examples

A static website with a dynamic search function? Yes, Hugo provides an alternative to embeddable scripts from Google or other search engines for static websites. Check out hugo themes with search

Sometimes you might want to see more than ten results on the Google SERP (Search Engine Results Page). Increasing the result count per page is pretty simple. You can read google custom search pagination to know how

JSON API pricing

Custom Search JSON API provides 100 search queries per day for free. If you need more, you may sign up for billing in the API Console. Additional requests cost $5 per 1000 queries, up to 10k queries per day. If your site has 10,000 search queries in a day, it will cost 50$ per day. This is a major disadvantage of the Google custom search API, especially if you have significant traffic. If you fall under this category, you can sign up for expertrec custom search engine that is priced on the number of pages on your website with unlimited search queries. Hence it’s a very cost-effective alternative to Google Custom Search Engine

If you need more than 10k queries per day and your Programmable Search Engine searches 10 sites or fewer, you may be interested in the Custom Search Site Restricted JSON API, which does not have a daily query limit. (the only catch with this is that you can search only Upton 10 websites). 

Here is our detailed analysis of google custom search pricing

Create your custom search engine now

JSON API Monitoring

Monitoring your API usage is a very useful feature that you should consider (for example when your search goes down, you can get an email alert).

Basic monitoring for the Custom Search JSON API is available through Cloud Platform Console’s API Dashboard. For more advanced monitoring Google Cloud’s Operations suite (formerly Stack driver) is available.

With Google Cloud Operations you can create custom dashboardsset up alerts, and access metrics data programmatically.

To access Custom Search JSON API usage data in Google Cloud Operations, select “Resource type: Consumed API” and filter on “service = ‘'” in the Query Builder.

See Monitoring Your API Usage for a discussion of the different monitoring and alerting capabilities provided by the API Dashboard and the Google Cloud Operations suite.

JSON api monitoring

Google custom search JSON API parameters

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.

All parameter values need to be URL encoded.

API-specific query parameters

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

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 Custom Search JSON API URL is:

The usual API call is

Three query [parameters] are required with each search request:

  • API key – Use the key query parameter to identify your application.
  • Programmable Search Engine ID – Use cx to specify the Programmable Search Engine you want to use to perform this search. The search engine must be created with the Control Panel Note: The Search Engine ID (cx) can be of different format (e.g. 8ac1ab64606d234f1)
  • Search query – Use the q query parameter to specify your search expression.

All other query parameters are optional.

Here parameters could be –

  1. q– query string
  2. cx– Custom search engine ID.
  3. file Type– BMP, gif, jpg, ping, PDF, etc
  4. num-number of search results to display
  5. searchType- search type.
  6. sort-Sort by functionality to use.

For a complete list of all query parameters for google custom search JSON API, go to this link.

Google custom search JSON API

Example :'

The response of this API will be in JSON format for you to consume to build your search application.
"kind": "customsearch#search",
"url": {
"type": "application/json",
       "template": "{searchTerms}&num={count?}&start={startIndex?}&lr={language?}&safe={safe?}&cx={cx?}&sort={sort?}&filter={filter?}&gl={gl?}&cr={cr?}&googlehost={googleHost?}&c2coff={disableCnTwTranslation?}&hq={hq?}&hl={hl?}&siteSearch={siteSearch?}&siteSearchFilter={siteSearchFilter?}&exactTerms={exactTerms?}&excludeTerms={excludeTerms?}&linkSite={linkSite?}&orTerms={orTerms?}&relatedSite={relatedSite?}&dateRestrict={dateRestrict?}&lowRange={lowRange?}&highRange={highRange?}&searchType={searchType}&fileType={fileType?}&rights={rights?}&imgSize={imgSize?}&imgType={imgType?}&imgColorType={imgColorType?}&imgDominantColor={imgDominantColor?}&alt=json"
         "queries": {
            "request": [
              "title": "Google Custom Search - rocket propulsion",
              "searchTerms": "rocket propulsion",
              "count": 10,
              "startIndex": 1,
              "inputEncoding": "utf8",
              "outputEncoding": "utf8",
              "safe": "off",
              "cx": "59c893957269aa6d7"
          "searchInformation": {
               "searchTime": 0.175466,
                "formattedSearchTime": "0.18",
                "totalResults": "0",
                "formattedTotalResults": "0"

If you are doing a search for something you should be looking for personal search engines, that can help you easily, and also helps you create amazing results when searching for the name of the product you are looking for, the keywords to find for that product etc. You can go for the Google search API alternative

Looking for how to add multiple websites in google custom search include sites in bulk?

Create your custom search engine now

More Detailed information

Getting your Google custom search API Key

  1. Go to
  2. Click on get a key.Google custom search JSON API simplified
  3. Click to create a new project.Google custom search JSON API simplified
  4. This will generate your new API key.Google custom search JSON API simplified
  5. You can restrict the usage of this API key in your Google API console

Google custom search JSON API simplified

Getting your CX / Search engine ID

Go to your custom search / site search control panel-> edit search engine->Basics->Details->Search engine ID.

This is your search engine ID.

Google custom search JSON API

Testing your Google custom search JSON API-

You can test your Google custom search API using the Google API explorer 

google custom search api

Limitations of Google custom search API

  1. You can only retrieve a maximum of 10 search results at a time.
  2. Query limit of 100 per day.
  3. Costly- At $5 per 1000 queries, the cost of google custom search goes really high when your site has significant traffic

Overcoming the limitations of the JSON API

To overcome the limitations of the Google custom search API, we have built a custom search engine at expertrec that is priced not based on the number of queries but the number of pages. If your website has 2000 pages, you can create a custom search engine with ExpertRec at just $9 per month.

API Format

The API will be of this format-{org_id}/?q={keyword}&page={pagination}&size={number_of_search_results}

Expertrec site search API parameters

  1. org_id- Your unique ID that identifies your website/ websites.
  2. q- Keyword.
  3. page- pagination
  4. size- number of search results to be displayed.

The results will be in JSON format-

{ "len":1, "query":"a", "facet_interval":{ }, "facets":{ "type":{ "webpage":160 } }, "fq":{ }, "nf":{ }, "numeric":{ }, "res":{ "count":160, "st":0, "time":3 }, "results":[ { "date":"2018-05-09T12:35:47.110Z", "host":"", "id":"", "image":[ "" ], "popularity_score":1.0, "score":1.25, "snippet":{ "content":[ "How to <span class=highlight>create</span> <span class=highlight>a</span> wordpress custom <span class=highlight>search</span> - 2018 Expertrec   Support <span class=highlight>magento</span> <span class=highlight>search</span> engine Google site <span class=highlight>search</span> <span class=highlight>replacement</span> Expertec Toggle <span class=highlight>Navigation</span> How to <span class=highlight>create</span> <span class=highlight>a</span> wordpress custom <span class=highlight>search</span> Published by <span class=highlight>muthali</span> <span class=highlight>ganesh</span> on <span class=highlight>April</span> 8, 2018 <span class=highlight>Creating</span> wordpress custom <span class=highlight>search</span> using expertrec is <span class=highlight>as</span> <span class=highlight>easy</span> <span class=highlight>and</span> <span class=highlight>can</span> be <span class=highlight>taken</span> live in 5 minutes. " ], "metatag.description":[ ], "title":[ "How to <span class=highlight>create</span> <span class=highlight>a</span> wordpress custom <span class=highlight>search</span> - 2018 Expertrec" ] }, "title":"How to create a wordpress custom search - 2018 Expertrec", "type":"webpage", "url":"" } ], "sfacets":{ "type":[ { "count":160, "name":"webpage" } ] } }

You can also try searching multiple websites at once

Google discontinued their Google site search product in April 2017 and replaced it with Google’s custom search engine, a search engine that came along with ads and offered it for free. If you are looking for an ad-free experience you can check Google Site search alternatives


Create your custom search engine now


How Do I Use Google Custom Search API?

Google’s custom search JSON API can develop applications or websites to retrieve your results. This API can do both image and web searches. This can also search topics that the programmer particularly inserts. 

The steps to create a custom search API –

  • Create a Search Engine

First, you must create a search engine and configure your search engine. If you don’t have a search engine, then you can create one using Google’s programmable search engine control panel.  After that, you have to find its ID. For that, you have to go to “setup,” then go to “basics,” and after clicking “search engine,” if you now have it. 

  • API Key

To properly function as a custom search, you need to have the API. The key used helps identify the client. After acquiring this, you can add your API key parameter key=yourAPIKey with request URLs. This key is safe and doesn’t need coding to add to your URLs. 

How Do I Create A Search API? 

To create a search API, we need to do three things. Search API Server, Search API Index, and Search Page. 

  • Search API Server

Firstly we need to create the server because it can tell us where the index will be stored. We can use the Search API Database Search module or Apache Solr Search API Solr module to do this task. 

  • Search API Index

Secondly, we will create a Search API index to define the fields that need to be stored. 

  • Search Page

Lastly, we are going to create a search page. You can use both “Views” and “Search API pages modules to do this and get results immediately.

Is There a Working Sample of The Google Custom Search Rest API? 

Google custom search JSON API is itself a RESTFUL API. You can develop applications to get it to show search results such as web searches, images, etc. Google’s rest or “Representational State Transfer” is unique from other forms of rest as it provides access to services rather than giving access to resources. You can send requests to URI using HTTP GET. 

Examples of Google APIs are Cloud Machine Learning Engine, Google Maps, Google Cloud, Google Cloud Video Intelligence API, etc. 

What Are Google free APIs? 

Depending on the usage limit, almost every search API of Google is free. 

  • Cloud Machine Learning Engine

This API can map out a lot of outputs using input fields. It can determine probabilities of failure with the help of its turbine data. 

  • Google Maps

Many Google APIs can give you the same benefits as Google maps. It can include street view and navigation etc. Dividing by platform or function, several APIs could range from simple to complex. 

  • Google Cloud Video Intelligence API

This API can store your videos and give you Metadata, cropping advice, and a lot of auto-generated information. 

  • Hangouts Chat API

Google never had anything too remarkable in the world of social networking. This service can let people have conversations among themselves, like every chatting application, but it also can have customer service bots.


Create your custom search engine now

Are you showing the right products, to the right shoppers, at the right time? Contact us to know more.
You may also like