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: https://cse.google.com/manage/all
- Click New search engine
- Add your pages. In my case:
- Now it appears in the menu of the left.
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.
- 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.
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
keyquery parameter to identify your application.
- Custom search engine ID: Use
cxto 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
qquery 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:
This will get only the
items keys from their database, and only the
characteristics keys from
items. And from all the fields in
characteristics, you will only get the
That's it, enjoy!