Custom Google search

9 min. read

Caution! This article is 5 years old. It may be obsolete or show old techniques. It may also still be relevant, and you may find it useful! So it has been marked as deprecated, just in case.

For a long time I had a disfunctional search in my site. It is a static site, so you have to use third party services if you want search capabilities. I was using Google Custom Search, but they changed the way you use it a long time ago, and as the saying goes, The shoemaker's children always go barefoot. I'm a developer, I have a site, site is abandoned, lol.

You can find the new docs for Google's Custom Search API here. Basically, you have a free version (with ads) that will allow you a maximum of 100 searches per day, or the paid version. Honestly, I'm not that popular and you can always search on Google anyway... but it's nice to have a search in place.

So I decided to document what I did here in case I need to change things in the future.

First: create a new search engine

The documentation is out of date and mentions menus that don't exist. So do this:

  • Go to your Control panel:
  • Click New search engine
  • Add your pages. In my case:
  • Now it appears in the menu of the left.

You can now use the API in your site through a GET request, through a JavaScript snippet to paste in your site that will generate their characteristic search form, or through a page that they generate for you that is styled with the awful Google-backend-developer-who-doesnt-know-shit-about-design style.

Configure your search engine

  • Click on Setup and then click on Seach Engine ID and copy that code. You'll need it to talk to the API.
  • Next to the ID is Public URL. This will give you a link to a page with a Google search form that returns results for your site only. However, the first four links or so returned here will be ads. The Look and feel item in the left menu allows you to configure this page. You can also do it programmatically passing options to your code snippet (see next point). My public url is here, in case you like to have your eyes cry blood.
  • Next to the URL is Get code, this will give you a script to paste in your site, use this if you want google to generate the search form for you. You can configure it from the Control Panel or programmatically through JavaScript. It will look like this:

  (function() {
    var cx = 'YOUR-SEARCH-ENGINE-ID';
    var gcse = document.createElement('script');
    gcse.type = 'text/javascript';
    gcse.async = true;
    gcse.src = '' + cx;
    var s = document.getElementsByTagName('script')[0];
    s.parentNode.insertBefore(gcse, s);
  • Click on Image search and turn it on, so that the search includes images.
  • If the Control Panel does not give you the level of customization that you need, you can click on the advanced tab and download the context (your search setup) and anotations (your sites to search) as XML files. Edit them to add your advanced configuration and then upload them again.

Get an API key

You can go to the docs or get it from your Control pane. You can also get it from your Google developer console.

The API key is safe for embedding in URLs, it doesn't need any encoding.

Making requests

The API only has a GET method, and the URL to make requests to it is:

It has a lot of parameters that you can pass to it. Three of them are required with each search request:

  • API key: Use the key query parameter to identify your application.
  • Custom search engine ID: Use cx to specify the custom search engine you want to use to perform this search. The search engine must be created with the Control Panel. Also, this ID contains a ':', so you will need to encode this ID before using it to make a request or you will get an "invalid parameter" error.
  • Search query: Use the q query parameter to specify your search expression.

You can find a list of all parameters that you can pass to this URL and what they mean in the API reference page. This page has a sidebar on the right where you can try the API with a demo API, so that you don't exceed your daily requests limit of 100. You will get the results in JSON format, which you can compare with the sample in that same page.

If you still wanted to use your own API key, you could use it directly on a browser, or use this page, which will also spit the JSON in place.

Kind of GraphQL

The API allows you to choose only those parameters that you want in the resulting JSON, so that you don't have to deal with a lot of data at once, using the fields query parameter. The fields syntax is very well explained in their performance page so I won't go into detail here, but this is an example:,items(title,characteristics/length)

This will get only the kind and items keys from their database, and only the title and characteristics keys from items. And from all the fields in characteristics, you will only get the length.

That's it, enjoy!