ContextualWeb Custom Search API Quick Start Guide
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:
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”:
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).
In this screen, you can customize many different features of your search engine, including:
- 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:
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:
You can use your public link to let other experiment or use you live custom search engine.
Custom Search comes with AutoComplete baked right in. Simply flick the AutoComplete switch, tap "Apply" and check out the automatic completions:
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".
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:
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:
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.
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.
Scroll down and copy your personal, secret API key. It should look something like this:
Here’s where to find it:
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".
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.
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:
Then, choose which snippet you'd like to see:
And check out the code snippet and response 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.
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.