I’m working on a project that uses a search engine to show images on a particular topic … but I need my search to be localised since I’m in the UK and so “football” doesn’t mean what a generic search engine thinks it means. Getting this working was MUCH harder than I expected, so here’s a quick post on what I did so that I can remember for next time – and if this helps you as well, then great :)

Google Custom Search Engine

It’s possible to set up and configure a custom search engine in Google, so you can configure some settings and the search will always use those settings. To begin, go to http://www.google.com/cse. Here you can create a search engine, give it a name and description, and then set some options. You can choose whether to search for images, or not, or images only. You can include or exclude certain sites, or search everywhere and just prefer certain sites.

The main feature I was making use of here was that you can set the googlehost parameter, which means you get the results you would have got if you’d used that regional google search page. Since http://www.google.co.uk/ knows exactly what “football” is, that’s what I needed!

If you just want to add a smart google search box to your page, then it looks as if you should be able to just grab the code snippets at this point and you will be all set … but I wanted to do this programmatically.

I saw lots of references to the “Custom Search API” being required, but I guess this is deprecated as all the links to it simply 404. Following links from the custom search engine also didn’t help much, but it turns out you can reach this functionality via the REST/JSON API.

Preparing the Request

The hard work here is all in the preamble, once you make the API call, it gets much easier so bear with me! To get this working you will need:

• One custom search engine, as described above
• The id and creator values from your custom search engine. Go your search engine configuration screen and visit Setup > Advanced > CSE Context and choose “view in browser”, then grab these two values
• An API Key from the Google Cloud Console. Create a project, then go to “APIs & Auth” and enable the “Custom Search” entry in the list. Under “Registered Apps” create a new app and then get look inside the “Server Key” entry to get the API key

Calling Google’s Custom Search API

At this point, I found I had enough information to follow the documentation. We’re creating a URL that will return us the request, mine looks something like this:

https://www.googleapis.com/customsearch/v1?googlehost=google.co.uk&safe=medium&searchType=image&key={apikey}&cx={cseId}&q={search}

There are a few placeholders in there, let’s look at those in turn:

• {apikey} is the API key you got from the google cloud console
• {cseId} is the identifier for your custom search engine, in the format “creator:id”
• {search} whatever you wanted to look for! This could be user input.

You can also append &start={startindex} where {startindex} is a page number if you need more results than just the first set. There are plenty more options but this is everything I needed.

As I say the documentation is pretty good, and the result format is very clear and easy to understand … so once you get this far, I hope you have everything you need to build whatever awesome thing you were aiming for! If you had different experiences or want to add anything, please leave a comment, google’s products do update pretty rapidly so updates and additions are very likely to be helpful to future readers of this post (and of course, to me, if that “next time” ever comes along!)