9.7. Understanding the Google API Response
While the Google API grants you programmatic access to
Google's Web index, it doesn't
provide all the functionality available through the Google.com web
site's search interface.
9.7.1. Can Do
The Google API, in addition to simple keyword queries, supports the
following ["Special Syntaxes" in
9.7.2. Can't Do
The Google API does not support these special syntaxes:
While queries of this sort provide no individual results, aggregate
result data is sometimes returned and can prove rather useful.
googly.php [Hack #96], for
instance, displays the number of results
9.7.3. The 10-Result Limit
While searches through the standard Google.com home page can be tuned
["Setting Preferences" in Chapter 1] to return 10, 20, 30, 50, or 100 results
per page, the Google Web API limits the number to 10 per query. This
doesn't mean, mind you, that the rest are not
available to you, but it takes a wee bit of creative programming
entailing looping through results, 10 at a time [Hack #95] .
9.7.4. What's in the Results
The Google API provides both aggregate and per-result data in its
188.8.131.52 Aggregate data
The aggregate data, information on the query itself and on the kinds
and number of results that query turned up, consists of:
A Boolean (true/false) value
specifying whether or not results were filtered for very similar
results or those that come from the same web host.
Any commentary (e.g., a note about stop words being removed) Google
might throw in that would usually be displayed just beneath the
search box on a typical Google results page.
An estimate of how many results might be found for your search in the
Google index. This number may vary from invocation to invocation,
moment to moment—thus the
Google may sometimes be sure of its
estimatedTotalResultsCount, in which case
estimateIsExact will be set to
The individual results themselves, returned as an array.
Your Google query, right back at you.
The index of the first result in the current array of results.
Assuming your query asked for a start of
0, the first result will have a
startIndex of 1. If you asked
for a start of 25,
startIndex would be 26. Yes, I
know it's confusing that start is
zero-based, while startIndex is one-based, but
that's the way the cookie crumbles,
The index of the last result in the current array of results. This is
always whatever you set as start +
maxResults in your query, unless the total is
greater than the number of
estimatedTotalResultsCount, in which case it is
May provide suggestions on better using Google, suitable for
displaying to the end user.
A list of directory categories, if any, associated with the query
The time spent by the Google server (in seconds) on your search.
184.108.40.206 Individual search result data
The "guts" of a search
result—the URLs, page titles, and snippets—are returned
in a <resultElements> list. Each result
consists of the following elements:
The Google Directory summary, if available.
The search result's URL, consistently starts with
A brief excerpt of the page with query terms highlighted in bold
(HTML <b> </b> tags).
The page title in HTML.
The size in kilobytes (K) of the Google-cached version of the page,
If set to 1, means a related:
search on the current result's URL will turn up
something of use.
When you set filter to TRue in
your query, only two results from the same hostname are included in
your set of results. In the second of these results,
hostName is set to the host from which the result
The title under which this result appears in the Google Directory
a.k.a. the Open Directory Project) if it is in the directory at all.
The Google Directory category, if any, in which
you'll find this result.
<directoryCategory> consists of
<fullViewableName>, the name given to the
category itself, and <specialEncoding>, any
special encoding assigned to the directory category at hand.
You no doubt notice the conspicuous absence of PageRank. Google does
not make PageRank available through anything but the official Google
Toolbar [Hack #60] .
You can get a general idea of a page's popularity by
looking over the popularity bars in the Google