×

ContextualWeb Custom Search API Quick Start Guide

Getting Started

In this tutorial, you’ll learn how to set up a Custom Search Engine and how to use it. This is a quick, 10 minute process, so grab a cup of coffee and let’s get to it.

1. Create your Custom Search Engine

To create your custom search engine, head on over to cse.contextualweb.io and log in with your Facebook or Google account.

You’ll see this screen:

New Search Engine

Under the “Domains to search” field, fill in the domains which you’d like the engine to crawl and search. In this example, I’ll be creating an engine to search the BBC and the Guardian websites, so I’ll fill in bbc.com and theguardian.com, and I’ll call the engine UK Search Engine. Here’s how it looks before I click “create”:

Creating a new engine

In this example, I’m only searching two domains, but you can add as many domains and subdomains as you’d like. If you’re still unsure, don’t worry: you can edit this list later.

Once you’ve entered a list of domains and the search engine name, click “create”.

 

2. Customize Your Search Engine

Click “Edit Search Engine” and choose the search engine you created from the drop-down menu (the reason we have the drop down menu is you can have many custom search engines operational at the same time).

Editing the engine

In this screen, you can customize many different features of your search engine, including:

  • Description
  • Add News Search
  • Add Image Search
  • Safe Search
  • Add or Remove Domains
  • Toggle Thumbnails
  • Toggle Autocomplete

Custom News Search

In this example, we're building a custom search engine focused on news, so we can flick the news search switch and apply:

Turning News Search on

Under the headline "Public URL", you’ll also see a URL for your search engine, which you can use to try it out. You can share this URL with others to let them try your engine. Here’s my search engine’s URL, for example:

https://cse.contextualweb.io/cse?searchEngineHash=7645176731227862567

You can use your public link to let other experiment or use you live custom search engine.

Public Search Engine URL

Autocomplete

Custom Search comes with AutoComplete baked right in. Simply flick the AutoComplete switch, tap "Apply" and check out the automatic completions:

Autocomplete

Adding or Removing domains

One more thing you can do on this screen is add or remove domains. Simply tap the "Websites" tab, enter the domain you'd like to add and tap "Save". Or, if you'd like to remove a domain, tick the box next to the domain you'd like to remove and tap "Delete".

Adding domains

It's also possible to upload a domain file from your computer: simply click the dropdown menu, choose "File" and navigate to the file you'd like to upload.

Look & Feel

You can always customize your search engine’s look and feel by clicking the “Look and Feel” link on the left:

Look and feel

You can use the Look and Feel dashboard to change every visual aspect of your engine. For example, after clicking the "customize" tab, you can change your engine's font and colors to match your brand:

Custom Search Example

 

Thumbnails

Another toggle that might be helpful is under the thumbnails tab. This toggle determines whether the news search engine returns thumbnails for the articles it digs up as part of its response. If you want to only display articles with thumbnails, simply flip this switch and tap "Save". Keep in mind that the engine will display thumbnails even with the switch turned off, but it will also display results where we weren't able to retrieve a thumbnail.

Image Thumbnails

Feel free to experiment - any change you make can be easily reverted. 

 

Step 3: Sign up for a RapidAPI account.

RapidAPI is the API marketplace we use to distribute the custom search engine API. It lets us manage subscriptions and billing easily. Over one million developers use Rapid API to get their APIs, and the breadth of the marketplace is astounding, so getting an account is useful anyway!

Simply head on over to https://rapidapi.com/signup to get your account. You can use Facebook, Github or Google to sign up.

Step 4: Get your API key.

Once you’ve registered and logged in to RapidAPI, visit our Custom Search API page.

 https://rapidapi.com/contextualwebsearch/api/custom-search

Scroll down and copy your personal, secret API key. It should look something like this:

4EFkAKPf2zmvh3BXV8O0UCRgymsqUJ6xT

Here’s where to find it:

RapidAPI key

Step 5: Add your API key

Once you've got your key from RapidAPI, Click the generate API key menu option on the left.

Then, paste the API key you copied into the API field and click "update".

Adding your API key

You should see a little message saying “API Key Updated”. If you see that, it means you’re good to go. 👍

 

Step 6: Use your engine programmatically

Back in the Setup screen, you’ll see a link to set up programmatic access to your engine.

Click the button that says “Get started”.

This screen provides an example of what an API call to your engine might look like.

Every API call requires a query, the search engine ID (which you can find in the Setup screen), the API key you’ve copied from Rapid API and the page number (which is used for pagination - Most searches return more than one page of results).

Once you’ve filled the form in, tap "Call", and you’ll see an example of the GET request and the Headers you should use for your API request.

Calling your custom news search API

You can use the GET Requests and Headers as a template in your actual application. You can also see the actual Response 200 you'd get for this API call.

In the left hand menu under "JSON API", you will also see sections for "News Search API" and "Image Search API".  These can both be used similarly to the Web Search API - simply enter your search query, choose the engine and API key you'd like to use from the dropdown, and tap "Call" to see the relevant results.

To get actual code snippets to embed in your application, simply head back over to Rapid API, and choose your programming language from the dropdown menu:

Choose your programming language

Then, choose which snippet you'd like to see:

Code snippets

And check out the code snippet and response example:

Code example

If you need more help with Rapid API, feel free to head on over to their tutorial.

If you need a primer on how APIs work, check out this awesome guide by Smashing Magazine.

 

Wrap up

That’s it - you’re done! You can now embed your custom search engine in your site or application and start providing exceptional search results for your users. If you need any help getting started, please don’t hesitate to reach out - we’d love to hear from you.