Part VI

Appendixes

TEAM LinG - Live, Informative, Non-cost and Genuine !

In this part...

Appendix A explains what is in the Google APIs software development kit (SDK).

Appendix B shows you how to use the Google APIs with Visual Basic .NET and Visual Studio. I show you a sample Visual Basic application in this appendix that searches for similar sites and displays links to these sites. You can use this application to understand what you need to do to create your own Visual Basic applications.

Appendix C tells you what you need to know to use the Google APIs with the Java class library included with the SDK. I show you a sample Java application in this appendix that returns the snippet of text associated with

the first result of a search. You can use this application to understand what you need to do to create your own Java applications.

TEAM LinG - Live, Informative, Non-cost and Genuine !

Appendix A

Using the SDK

The Google APIs SDK (software development kit) provides information about the Google APIs and samples that use the APIs. If you are inter-

ested in building research applications with the Google APIs, you’ll want to download and unzip the SDK.

This appendix tells what you find in the SDK.

Downloading and Unzipping the SDK

To download the SDK, just follow these simple steps:

1.Open the URL in your browser.

The Download the Google APIs Developer’s Kit page appears.

2.Click to put a check mark in the box to indicate your agreement with the Google Web APIs license terms.

The license terms are also sometimes called the Google APIs Terms of Service, or TOS.

3.Click the Download Now button.

4.When the File Download window opens, click the Save button.

5.Choose a location on your computer to save the Zip archive containing the SDK.

After you download the Zip archive file to your computer, unzip — or expand — the archive file. Specify where on your computer you’d like to place the files contained in the archive file.

TEAM LinG - Live, Informative, Non-cost and Genuine !

328 Part VI: Appendixes

The easiest way to unzip a file on Windows is to use the WinZip utility. You can download WinZip from www.winzip.com. A free evaluation version of WinZip is available.

You don’t need a Google developer key to download, unzip, and inspect the SDK. But you do need a key to use any of the sample applications that the SDK includes. For more information, see Chapter 14.

Understanding the SDK Contents

When you download, unzip, and save the contents of the SDK to your computer, the files are organized in a structure with a folder named googleapi at the highest level. The contents of the SDK are shown in Table A-1.

Table A-1	Contents of the SDK
Folder	Filename	What It Is
googleapi	APIs_Reference.html	API reference document
		(also available on the Web)
googleapi	googleapi.jar	Executable Jar (Java) file
		that you can use to run the
		Java APIs demo
googleapi	GoogleAPIDemo	Java source code file
googleapi	GoogleSearch.wsdl	The Google APIs Web serv-
		ice WSDL file (see Chapter
		15 for more information)
googleapi	License.txt	Google APIs TOS
googleapi	Readme.txt	Brief description of how to
		use the examples and a
		manifest of the contents
		of the SDK
googleapi\dotnet	CSharp Example.exe	Compiled C# sample appli-
		cation; requires .NET
		Framework

TEAM LinG - Live, Informative, Non-cost and Genuine !

			Appendix A: Using the SDK 329
	Folder	Filename	What It Is
	googleapi\dotnet	VB Example.exe	Compiled Visual Basic
			sample application; requires
			.NET Framework
	googleapi\	Various files	Source code and .NET
	dotnet\CSharp		project files for sample C#
			application (see Chapter 16
			for more information)
	googleapi\	Various files	Source code and .NET
	dotnet\		project files for sample
	VisualBasic		Visual Basic application
			(see Appendix B for more
			information and building
			Google APIs applications
			in Visual Basic .NET)
	googleapi\javadoc	Various files	HTML documentation for the
			Java classes used to create
			the sample Java application
	googleapi\	Various files	Text of licenses from the
	licenses		Apache Organization and
			Sun Microsystems covering
			some of the Java code used
			in the googleapi.jar file
	googleapi\	Various files	Sample SOAP messages
	soap-samples		and responses in XML for
			invoking the GoogleSearch
			WSDL file

The most important parts of the SDK are the sample applications, which you can use as the starting place for your own applications.

The documentation portions of the SDK are sketchy (at best) — which may be why you’ll find this book helpful if you’d like to build research applications based upon the Google Web APIs.

TEAM LinG - Live, Informative, Non-cost and Genuine !

330 Part VI: Appendixes

Table A-2 shows where to go in this book for more information about using the contents of the SDK (including the code samples).

Table A-2 Information in This Book about Using the SDK

You’d Like to Know More About . . .	Where to Go . . .
The specifics of the Google APIs	Chapter 13
Downloading a developer key	Chapter 14
Working with WSDL files	Chapter 15
Using the C# sample application	Chapter 16
Building C# Google APIs applications	Chapters 17 and 18
Using the Visual Basic sample, building VB	Appendix B
Google API applications
Using the Java sample, building Java Google	Appendix C
API applications

TEAM LinG - Live, Informative, Non-cost and Genuine !

Appendix B

Building a Research Application

with Visual Basic .NET

You can easily create Windows and ASP.NET Web applications that use the Google APIs with Visual Basic .NET in Visual Studio. These steps are

involved:

1.Add a Web reference to the Google WSDL file (see Chapter 15 for information about WSDL files).

This action creates and adds a proxy class, which is used to call the Google APIs, to your project.

2.Change the name of the proxy class to Google.

This step is not required, but changing the name of the class helps to keep your program simple and clear.

3.In code, create an instance of the Google class.

4.Use one or more of the Web methods (Google APIs) associated with the Google class.

5.Do something with the return values from the Web methods (such as displaying a page of results).

In this appendix I cover each of these points in detail.

Creating an application that uses the Google APIs in Visual Basic is exactly like creating one in C#, except that the syntax of the language used is a little different (after all, Visual Basic is a different language than C#). You can follow the general directions for creating applications with the Google APIs using C# in Chapter 16, and these mechanics work similarly with Visual Basic, although of course the language is different.

Adding a Web Reference

To add a Web reference to the Google APIs Web service to your Visual Basic project, follow these steps:

TEAM LinG - Live, Informative, Non-cost and Genuine !

332 Part VI: Appendixes

1.Choose Add Web Reference from the Project menu.

The Add Web Reference window opens.

2.In the URL text box, enter the Web address for the Google WSDL file, http://api.google.com/GoogleSearch.wsdl.

3.Click the Go button.

When the Google WSDL file is found on the Web, the Google Web service and its Web methods display, as shown in Figure B-1.

4.Click Add Reference.

The Web reference is added to your project.

The three Web methods shown in Figure B-1, such as doGoogleSearch, are the three Google APIs that collectively make up the Google Web service. See Chapter 13 for more information about each of the three APIs.

Figure B-1:

Adding a Web reference to the Google APIs.

Changing the Name of the Proxy Class

I recommend changing the default name given the Web service proxy class that is created when you add the reference to the Google Web service.

The default name for the proxy class is api.google.com, which is the location of the GoogleSearch WSDL file on the Web.

TEAM LinG - Live, Informative, Non-cost and Genuine !

Appendix B: Building a Research Application with Visual Basic .NET 333

The reasons for changing this name are so that you can do the following:

Write clearer code using a less complex name.

Conform to the name used in Google’s sample applications that are in the SDK (see Appendix A for more information about the contents of the SDK).

In the SDK sample applications, Google names the class Google. Simple and clear, right? So why not follow suit?

To change the default name for the Web reference:

1.Open Solution Explorer by choosing View Solution Explorer.

Solution Explorer opens.

2.Expand Web References by clicking the plus icon (+) to the left of the Web Reference folder.

Keep expanding the folder until you see a listing for the Google Web service.

3.Right-click the Google Web service folder.

Choose Properties from the context menu to open the Properties window.

4.In the Properties window, change the Folder Name property from api.google.com to Google.

See Figure B-2.

In order to see the Google Web service in the Web References folder, you may need to click the Show All Files button, which is the second button from the left in the Solution Explorer toolbar shown in Figure B-2.

Figure B-2:

Use Solution Explorer and the Properties window to change the Web

reference’s

name.

TEAM LinG - Live, Informative, Non-cost and Genuine !

334 Part VI: Appendixes

Creating an Instance of the Class

It’s easy to create an instance of the proxy class that represents the Google

Web service in code, like this:

Dim s As New Google.GoogleSearchService

To see this declaration and instantiation in context, have a look at Listing B-1.

Using the Web Methods (The APIs)

You need to use your Google developer key each time you call a Google Web method (the Google Web methods are the same thing as the Google APIs).

Downloading a Google developer key is pretty simple stuff. See Chapter 14 for more information about getting a Google developer key of your very own!

Before you start calling the Web methods in code, declare a string variable and assign your developer key to it:

Dim devKey As String = “xxxxxxxxxxxxxxxxxxxxxxxxxxxx”

In your programs, you’ll need to replace the blanks with your own developer key.

There are three Google Web methods:

doGoogleSearch, used to search Google

doGetCachedPage, used to retrieve a page from the Google cache (and/or information about the page)

doSpellingSuggestions, which returns a Google spelling suggestion

Searching Google

As an example, suppose you want to create an application that searches for

Web pages that are similar to a given page.

The user enters a URL into a TextBox named txtURL. The related keyword is then put in front of the text entered by the user and used for the search, like this:

TEAM LinG - Live, Informative, Non-cost and Genuine !

Appendix B: Building a Research Application with Visual Basic .NET 335

Dim searchStr As String = “related:” & txtURL.Text

The related: operator is used in a Google search to find Web pages that are similar to a given Web page. See Chapter 5 for more information about how this and other search operators work in Google.

You can now declare a variable, r, to hold the search result, and use the instance of the Google proxy class to call the doGoogleSearch Web method:

Dim r As Google.GoogleSearchResult = _ s.doGoogleSearch(devKey, searchStr, 0, 10, _ False, “”, False, “”, “”, “”)

This code passes the doGoogleSearch Web method your developer key, the search string, the starting result number to return (0), and the number of results to return (10) as arguments. For information about the other arguments passed to the doGoogleSearch Web method, see Chapter 13.

In Visual Basic, the end of a line serves to mark the end of a statement.

A special character sequence, space underscore ( _) is used to indicate that a statement continues to the next line. When you put these two characters at the very end of the line (with nothing after them), the Visual Basic compiler treats the next line as a continuation of the current line.

Retrieving a page from the cache

You can let the user specify the page to retrieve from the Google cache in a TextBox named txtCachePage. To get the bytes that make up the page

selected by the user, call the doGetCachedPage API with your developer key and the URL entered by the user:

Dim bytes() As System.Byte = _

s.doGetCachedPage (devKey, txtCachePage.Text)

Getting a spelling suggestion

You can get a spelling suggestion from Google by using the doSpelling Suggestion API to pass it some text (along with your developer key, of course):

Dim suggestion As String = s.doSpellingSuggestion _

(devKey, txtSpell.Text)

TEAM LinG - Live, Informative, Non-cost and Genuine !

336 Part VI: Appendixes

Displaying Results

How you display the results of a call to one of the Google Web methods depends on what information you need to display (and, of course, which Web method you’re using). Here are some examples.

Showing search results

Earlier in this appendix, I show an example in which you can let a user search for similar sites by using the related: operator; you might want to display the results in a LinkLabel control. Adding the title of each resulting similar Web page to the LinkLabel control makes sense because you can associate the title with the actual URL of the Web page. When the user clicks the title, the similar Web page opens in the user’s Web browser.

Figure B-3 shows the results of a search for similar pages to www.google.com. If the user clicks one of the titles shown in this figure, the corresponding Web page opens.

Figure B-3:

The addresses of the first ten similar sites are displayed.

To implement this functionality, you need to use the return results of the Google search, stored in the variable r.

You can use the resultElements array associated with r to assign each similar page title as part of the LinkLabel text and associate the URLs belonging to the similar pages with the title text:

TEAM LinG - Live, Informative, Non-cost and Genuine !

Appendix B: Building a Research Application with Visual Basic .NET 337

Dim j As Integer = r.resultElements.Length - 1 Dim i As Integer

For i = 0 To j

If (Not (r.resultElements(i) Is Nothing)) Then

Dim labelLen As Integer = LinkLabel1.Text.Length LinkLabel1.Text += r.resultElements(i).title & _

vbCrLf

Dim titleLen As Integer = _ r.resultElements(i).title.Length

LinkLabel1.Links.Add(labelLen, titleLen, _ r.resultElements(i).URL)

End If Next

The code that actually opens the URLs corresponding to the similar page title goes in the LinkClicked event of the LinkLabel control.

Listing B-1 shows the code for searching Google for similar sites, displaying the site titles, and opening the target URL when a similar site is selected by title.

Listing B-1: Displaying and Providing Links for Similar Results

Dim devKey As String = “xxxxxxxxxxxxxxxxxxxxxxxxxxxx”

Private Sub btnSearch_Click(ByVal sender As System.Object, _ ByVal e As System.EventArgs) Handles btnSearch.Click

‘ Create a Google Web service object Dim s As New Google.GoogleSearchService Try

Me.Cursor = Cursors.WaitCursor

Dim searchStr As String = “related:” & txtURL.Text Dim r As Google.GoogleSearchResult = _

s.doGoogleSearch(devKey, searchStr, 0, 10, _ False, “”, False, “”, “”, “”)

Dim j As Integer = r.resultElements.Length - 1 Dim i As Integer

For i = 0 To j

If (Not (r.resultElements(i) Is Nothing)) Then

Dim labelLen As Integer = LinkLabel1.Text.Length LinkLabel1.Text += r.resultElements(i).title & _

vbCrLf

Dim titleLen As Integer = _ r.resultElements(i).title.Length

LinkLabel1.Links.Add(labelLen, titleLen, _ r.resultElements(i).URL)

End If Next

Catch ex As System.Web.Services.Protocols.SoapException MessageBox.Show(ex.Message, “SOAP Exception”)

(continued)

TEAM LinG - Live, Informative, Non-cost and Genuine !

338 Part VI: Appendixes

Listing B-1 (continued)

Catch excep As Exception

MessageBox.Show(excep.Message, “Program Exception”)

Finally

Me.Cursor = Cursors.Default

End Try

End Sub

Private Sub LinkLabel1_LinkClicked(ByVal sender _

As Object, ByVal e As _

System.Windows.Forms.LinkLabelLinkClickedEventArgs) _

Handles LinkLabel1.LinkClicked

Dim target As String = CType(e.Link.LinkData, String)

Diagnostics.Process.Start(target)

End Sub

Visit www.braintique.com/research/ to download the sample project. The source code enables you to search for similar sites and display the top-ten results as clickable links.

Showing the size of a page in the cache

If you use the doGetCachedPage API, the page that is retrieved from the cache is stored as an array of bytes. The length of this array is the size of the page in bytes. If the array is named bytes, you could display this information like this:

lblCacheResults.Text = CStr(bytes.Length)

Showing a spelling suggestion

The return value for a call to the doSpellingSuggestion API is a string.

If the string is named suggestion, its value could be displayed like this:

If suggestion Is Nothing Then lblSpellResults.Text = “<no suggestion>”

Else

lblSpellResults.Text = suggestion End If

TEAM LinG - Live, Informative, Non-cost and Genuine !