Google's Custom Search allows you to create custom search engines based on Google's solid foundation of searching capabilities. A Google Custom Search Engine is an easy way to provide a search capability for your websites or blogs. Once created, the custom search engine can be consumed by adding a search box on any of the web pages or by linking to the home page of the custom search engine. At times, however, we may need some advanced way to consume our search engine. Say, for example, we want to programmatically perform search operations against our custom search engine or want to retrieve the search results in a Windows application. Fortunately Google has come up with JSON/ATOM Custom Search API, which can be used to accomplish just that. As the name suggests, the custom search API returns search results in JSON or ATOM format, depending upon your choice, and can be invoked using the Representational State Transfer (REST) programming model.
Though the JSON/ATOM Custom Search API is simple to use and primarily rely on GET requests, wrapping this API in a custom control would make it even easier to use. That way, without having to learn the JSON/ATOM Custom Search API, anyone can just drag and drop the custom control, set a few properties, and consume the custom search engine. In this article and the next in a two-part series, we are going to do just that.
Before You Begin
Note that as of this writing the JSON/ATOM Custom Search API is in Google Labs and, as such, is subject to change. Also note that to use this API you need to have the following things:
- a Google Custom Search Engine. You can create one by visiting www.google.com/cse and following the step-by-step instructions found there. We won't cover those basics in this article.
- an API key. Calling JSON/ATOM Custom Search API requires an API key. You can obtain one using Google API Console.
- Every custom search engine is assigned a unique ID. You will need this ID while making REST calls.
Understanding Google's JSON/ATOM Custom Search API
As a control author we should be aware of how Google's JSON/ATOM Custom Search API works. From our code (client side or server side), we will be sending a GET request to the following URL:
You can find the complete list of query string parameters in Google's online documentation for the JSON/Atom Custom Search API. We will be using the query string parameters listed in Figure 1 in our custom control.
|Query string parameter||Description|
|key||The API key as obtained from Google API console|
|cx||The ID of the custom search engine that you wish to use.|
|alt||Data format for search results. Possible values are json (default) and atom.|
|lr||Language restriction for the search results. By default no restriction is placed.|
|safe||Search safety level. Possible values are high, moderate and off (default). See online documentation for more details.|
|filter||Governs turning on or off the duplicate content filter. Possible values are 0 (off) and 1 (on). Default is 1.|
|q||The search criteria.|
A typical client-side call to invoke the above REST service will look like this:
Once the results are retrieved, the client-side callback function (MyHandler in above example) will be called, and the results in JSON/ATOM format are passed to it as a parameter. The complete details of the result format for JSON and ATOM can be found in the online documentation. For our example we need the pieces of data, as listed in Figure 2.
|JSON object property||ATOM tag name||Description|
||The title of the search result item in plain text.|
||The title of the search result item in HTML.|
|link||The full URL to which the search result item is pointing.|
|displayLink||A short version of search result’s full URL|
||A short snippet from the search result item in plain text.|
||A short snippet from the search result item in HTML.|
Now that we know the basics of using the Google JSON/ATOM custom search API, let's focus on wrapping the API in an ASP.NET custom server control.
The Custom Control
We will create an ASP.NET custom server control (Google REST API Control) complete with designer support and a smart tag that allows us to consume the JSON/ATOM Custom Search API. The control will be invisible at runtime. Figures 3 and 4, respectively show the look and feel of the control at design time along with its smart tag.
The Google REST API custom control will have the properties and methods as listed in Figure 5.
|Property / Method||Description|
|Url||Indicates the Google URL for making REST calls. Though this URL is fixed we still make it as a property to accommodate any changes at later time.|
|ApiKey||An API Key required to use Google REST API.|
|CustomSearchEngineId||A unique ID of the custom search engine that you wish to use for searching.|
|SearchCriteria||Any search criteria string that you normally enter in search box.|
|LanguageFilter||By default search returns matching content without any language restriction. You can restrict the results to a particular language using this property.|
|SafeSearchOption||Governs safety level of the results. Possible values are Off, High and Medium.|
|FilterDuplicateResults||By default duplicate content is filtered but you can change the default using this property.|
|SearchResultFormat||The format in which search results are returned. Possible formats are JSON and ATOM.|
|GetSearchResults()||This method returns search results as a string. The string can contain JSON or ATOM data depending on the format specified using the SearchResultFormat property.|
|GetSearchResultsAsSyndicationItems()||Returns search results as ATOM feed items.|
Returns a client side ";
Notice the lines at callouts A and B. The URL is almost identical to the previous methods we developed, but we have also added "callback" query string parameter. Since the