|
| Contents |
1.1 Search Requests
1.2 Cache Requests
1.3 Spelling Requests2.1 Search Parameters
2.2 Query Terms
2.3 Automatic Filtering
2.4 Restricts
2.5 Input and Output Encoding
2.6 SafeSearch
2.7 Limitations3.1 Search Response
3.2 Result Element
3.3 Directory Category
| 1. Overview | Back to top
|
This document explains in detail the semantics of the function calls you can make using the Google Web APIs service. In this document, you will learn:
- How Google's query syntax works.
- How to restrict your queries to portions of Google's index, such as a particular language or country.
- How to interpret the search results information sent back by the Google Web APIs service.
You may also find the following files from the Google Web APIs developer kit to be helpful:
- GoogleSearch.wsdl - WSDL description for Google Web APIs SOAP interface.
- soap-samples/ - example SOAP messages and responses.
- javadoc/index.html - javadoc for the example Java libraries.
This is a beta document. If you have comments, find errors, or just have questions, please contact api-support@google.com .
1.1 Search Requests Back to top Search requests submit a query string and a set of parameters to the Google Web APIs service and receive in return a set of search results. Search results are derived from Google's index of over 2 billion Web pages.
The details of the interactions involved with search requests are covered in the Search Request Format and Search Results Format sections of this document.
1.2 Cache Requests Back to top Cache requests submit a URL to the Google Web APIs service and receive in return the contents of the URL when Google's crawlers last visited the page (if available).
Please note that Google is not affiliated with the authors of cached pages nor responsible for their content.
The return type for cached pages is base64 encoded text.
1.3 Spelling Requests Back to top Spelling requests submit a query to the Google Web APIs service and receive in return a suggested spell correction for the query (if available). Spell corrections mimic the same behavior as found on Google's Web site.
Spelling requests are subject to the same query string limitations as any other search request. (The input string is limited to 2048 bytes and 10 individual words.)
The return type for spelling requests is a text string.
| 2. Search Request Format | Back to top
|
2.1 Search Parameters Back to top This table lists all the valid name-value pairs that can be used in a search request and describes how these parameters will modify the search results.
Name Description Provided by Google, this is required for you to access the Google service. Google uses the key for authentication and logging.
q
start
Zero-based index of the first desired result. maxResults Number of results desired per query. The maximum value per query is 10.
Note: If you do a query that doesn't have many matches, the actual number of results you get may be smaller than what you request.filter
Activates or deactivates automatic results filtering, which hides very similar results and results that all come from the same Web host. Filtering tends to improve the end user experience on Google, but for your application you may prefer to turn it off. (See Automatic Filtering section for more details.) restrict
Restricts the search to a subset of the Google Web index, such as a country like "Ukraine" or a topic like "Linux." (See Restricts for more details.) safeSearch A Boolean value which enables filtering of adult content in the search results. See SafeSearch for more details. lr
Language Restrict - Restricts the search to documents within one or more languages. ie
Input Encoding - this parameter has been deprecated and is ignored. All requests to the APIs should be made with UTF-8 encoding. (See Input and Output Encodings section for details.) oe
Output Encoding - this parameter has been deprecated and is ignored. All requests to the APIs should be made with UTF-8 encoding. (See Input and Output Encodings for details.)
2.2 Query Terms - <q> Back to top Default Search
By default, Google only returns pages that include all of the terms in the query string. There is no need to include "AND" between terms. Keep in mind that the order of the terms in the query will impact the search results.
Stop Words
Google ignores common words and characters such as "where" and "how," as well as certain single digits and single letters. Common words that are ignored are known as stop words.
However, you can prevent Google from ignoring stop words by enclosing them in quotes, such as in the phrase "to be or not to be".
Special Characters
By default, all non-alphanumeric characters that are included in a search query are treated as word separators.
The only exceptions are the following: double quote mark ("), plus sign (+), minus sign or hyphen (-), and ampersand (&).
The ampersand character (&) is treated as another character in the query term in which it is included, while the remaining exception characters correspond to search features listed in the section below.
Special Query Terms
Google supports the use of several special query terms that allow the user or search administrator to access additional capabilities of the Google search engine.
Include Query Term Star Wars Episode +I If a common word is essential to getting the results you want, you can include it by putting a "+" sign in front of it.
Exclude Query Term bass -music You can exclude a word from your search by putting a minus sign ("-") immediately in front of the term you want to exclude from the search results. Phrase Search "yellow pages" Search for complete phrases by enclosing them in quotation marks or connecting them with hyphens. Words marked in this way will appear together in all results exactly as entered.
Note: You may need to use a "+" to force inclusion of common words in a phrase.
Boolean OR Search vacation london OR paris Google search supports the Boolean "OR" operator. To retrieve pages that include either word A or word B, use an uppercase OR between terms. Site Restricted Search admission site:www.stanford.edu If you know the specific web site you want to search but aren't sure where the information is located within that site, you can use Google to search only within a specific web site.
Do this by entering your query followed by the string "site:" followed by the host name.
Note: The exclusion operator ("-") can be applied to this query term to remove a web site from consideration in the search.
Note: Only one site: term per query is supported.Date Restricted Search Star Wars daterange:2452122-2452234 If you want to limit your results to documents that were published within a specific date range, then you can use the "daterange: " query term to accomplish this. The "daterange:" query term must be in the following format: daterange:<start_date>-<end date>
where
<start_date> = Julian date indicating the start of the date range
<end_date> = Julian date indicating the end of the date rangeThe Julian date is calculated by the number of days since January 1, 4713 BC. For example, the Julian date for August 1, 2001 is 2452122.
Title Search (term) intitle:Google search If you prepend "intitle:" to a query term, Google search restricts the results to documents containing that word in the title. Note there can be no space between the "intitle:" and the following word. Note: Putting "intitle:" in front of every word in your query is equivalent to putting "allintitle:" at the front of your query.
Title Search (all) allintitle: Google search Starting a query with the term "allintitle:" restricts the results to those with all of the query words in the title. URL Search (term) inurl:Google search If you prepend "inurl:" to a query term, Google search restricts the results to documents containing that word in the result URL. Note there can be no space between the "inurl:" and the following word. Note: "inurl:" works only on words , not URL components. In particular, it ignores punctuation and uses only the first word following the "inurl:" operator. To find multiple words in a result URL, use the "inurl:" operator for each word.
Note: Putting "inurl:" in front of every word in your query is equivalent to putting "allinurl:" at the front of your query.
URL Search (all) allinurl: Google search Starting a query with the term "allinurl:" restricts the results to those with all of the query words in the result URL. Note: "allinurl:" works only on words, not URL components. In particular, it ignores punctuation. Thus, "allinurl: foo/bar" restricts the results to pages with the words "foo" and "bar" in the URL, but does not require that they be separated by a slash within that URL, that they be adjacent, or that they be in that particular word order. There is currently no way to enforce these constraints.
Text Only Search (all) allintext: Google search Starting a query with the term "allintext:" restricts the results to those with all of the query words in only the body text, ignoring link, URL, and title matches. Links Only Search (all) allinlinks: Google search Starting a query with the term "allinlinks:" restricts the results to those with all of the query words in the URL links on the page. File Type Filtering Google filetype:doc OR filetype:pdf The query prefix "filetype:" filters the results returned to include only documents with the extension specified immediately after. Note there can be no space between "filetype:" and the specified extension. Note: Multiple file types can be included in a filtered search by adding more "filetype:" terms to the search query.
File Type Exclusion Google -filetype:doc -filetype:pdf The query prefix "-filetype:" filters the results to exclude documents with the extension specified immediately after. Note there can be no space between "-filetype:" and the specified extension. Note: Multiple file types can be excluded in a filtered search by adding more "-filetype:" terms to the search query.
Web Document Info info:www.google.com The query prefix "info:" returns a single result for the specified URL if it exists in the index. Note: No other query terms can be specified when using this special query term.
Back Links link:www.google.com The query prefix "link:" lists web pages that have links to the specified web page. Note there can be no space between "link:" and the web page URL. Note: No other query terms can be specified when using this special query term.
Related Links related:www.google.com The query prefix "related:" lists web pages that are similar to the specified web page. Note there can be no space between "link:" and the web page URL. Note: No other query terms can be specified when using this special query term.
Cached Results Page cache:www.google.com web The query prefix "cache:" returns the cached HTML version of the specified web document that the Google search crawled. Note there can be no space between "cache:" and the web page URL. If you include other words in the query, Google will highlight those words within the cached document.
2.3 Automatic Filtering - <filter> Back to top The <filter> parameter causes Google to filter out some of the results for a given search. This is done to enhance the user experience on Google.com, but for your application, you may prefer to turn filtering off in order to get the full set of search results.
When enabled, filtering takes the following actions:
- Near-Duplicate Content Filter = If multiple search results contain identical titles and snippets, then only one of the documents is returned.
- Host Crowding = If multiple results come from the same Web host, then only the first two are returned.
2.4 Restricts - <lr> <restrict> Back to top Google provides the ability to search a predefined subset of Google's Web index. This is enabled by using the lr and restrict parameters.
To search for documents within a particular language, use the <lr> parameter, using one of the values in the table below.
<lr> value <lr> value Arabic lang_ar Icelandic lang_is Chinese (S) lang_zh-CN Italian lang_it Chinese (T) lang_zh-TW Japanese lang_ja Czech lang_cs Korean lang_ko Danish lang_da Latvian lang_lv Dutch lang_nl Lithuanian lang_lt English lang_en Norwegian lang_no Estonian lang_et Portuguese lang_pt Finnish lang_fi Polish lang_pl French lang_fr Romanian lang_ro German lang_de Russian lang_ru Greek lang_el Spanish lang_es Hebrew lang_iw Swedish lang_sv Hungarian lang_hu Turkish lang_tr <restrict> - Country and Topic Restricts
Google allows you to search for Web information within one or more countries, using an algorithm that considers the top level domain name of the server and the geographic location of the server IP address.
The automatic country sub-collections currently supported are listed below:
Andorra countryAD Estonia countryEE Kazakhstan countryKZ Qatar countryQA United Arab Emirates countryAE Egypt countryEG Lao People's Democratic Republic countryLA Reunion countryRE Afghanistan countryAF Western Sahara countryEH Lebanon countryLB Romania countryRO Antigua and Barbuda countryAG Eritrea countryER Saint Lucia countryLC Russian Federation countryRU Anguilla countryAI Spain countryES Liechtenstein countryLI Rwanda countryRW Albania countryAL Ethiopia countryET Sri Lanka countryLK Saudi Arabia countrySA Armenia countryAM European Union countryEU Liberia countryLR Solomon Islands countrySB Netherlands Antilles countryAN Finland countryFI Lesotho countryLS Seychelles countrySC Angola countryAO Fiji countryFJ Lithuania countryLT Sudan countrySD Antarctica countryAQ Falkland Islands (Malvinas) countryFK Luxembourg countryLU Sweden countrySE Argentina countryAR Micronesia, Federated States of countryFM Latvia countryLV Singapore countrySG American Samoa countryAS Faroe Islands countryFO Libyan Arab Jamahiriya countryLY St. Helena countrySH Austria countryAT France countryFR Morocco countryMA Slovenia countrySI Australia countryAU France, Metropolitan countryFX Monaco countryMC Svalbard and Jan Mayen Islands countrySJ Aruba countryAW Gabon countryGA Moldova countryMD Slovakia (Slovak Republic) countrySK Azerbaijan countryAZ United Kingdom countryUK Madagascar countryMG Sierra Leone countrySL Bosnia and Herzegowina countryBA Grenada countryGD Marshall Islands countryMH San Marino countrySM Barbados countryBB Georgia countryGE Macedonia, The Former Yugoslav Republic of countryMK Senegal countrySN Bangladesh countryBD French Quiana countryGF Mali countryML Somalia countrySO Belgium countryBE Ghana countryGH Myanmar countryMM Suriname countrySR Burkina Faso countryBF Gibraltar countryGI Mongolia countryMN Sao Tome and Principe countryST Bulgaria countryBG Greenland countryGL Macau countryMO El Salvador countrySV Bahrain countryBH Gambia countryGM Northern Mariana Islands countryMP Syria countrySY Burundi countryBI Guinea countryGN Martinique countryMQ Swaziland countrySZ Benin countryBJ Guadeloupe countryGP Mauritania countryMR Turks and Caicos Islands countryTC Bermuda countryBM Equatorial Guinea countryGQ Montserrat countryMS Chad countryTD Brunei Darussalam countryBN Greece countryGR Malta countryMT French Southern Territories countryTF Bolivia countryBO South Georgia and the South Sandwich Islands countryGS Mauritius countryMU Togo countryTG Brazil countryBR Guatemala countryGT Maldives countryMV Thailand countryTH Bahamas countryBS Guam countryGU Malawi countryMW Tajikistan countryTJ Bhutan countryBT Guinea-Bissau countryGW Mexico countryMX Tokelau countryTK Bouvet Island countryBV Guyana countryGY Malaysia countryMY Turkmenistan countryTM Botswana countryBW Hong Kong countryHK Mozambique countryMZ Tunisia countryTN Belarus countryBY Heard and Mc Donald Islands countryHM Namibia countryNA Tonga countryTO Belize countryBZ Honduras countryHN New Caledonia countryNC East Timor countryTP Canada countryCA Croatia (local name: Hrvatska) countryHR Niger countryNE Turkey countryTR Cocos (Keeling) Islands countryCC Haiti countryHT Norfolk Island countryNF Trinidad and Tobago countryTT Congo, The Democratic Republic of the countryCD Hungary countryHU Nigeria countryNG Tuvalu countryTV Central African Republic countryCF Indonesia countryID Nicaragua countryNI Taiwan countryTW Congo countryCG Ireland countryIE Netherlands countryNL Tanzania countryTZ Switzerland countryCH Israel countryIL Norway countryNO Ukraine countryUA Cote D'ivoire countryCI India countryIN Nepal countryNP Uganda countryUG Cook Islands countryCK British Indian Ocean Territory countryIO Nauru countryNR United States Minor Outlying Islands countryUM Chile countryCL Iraq countryIQ Niue countryNU United States countryUS Cameroon countryCM Iran (Islamic Republic of) countryIR New Zealand countryNZ Uruguay countryUY China countryCN Iceland countryIS Oman countryOM Uzbekistan countryUZ Colombia countryCO Italy countryIT Panama countryPA Holy See (Vatican City State) countryVA Costa Rica countryCR Jamaica countryJM Peru countryPE Saint Vincent and the Grenadines countryVC Cuba countryCU Jordan countryJO French Polynesia countryPF Venezuela countryVE Cape Verde countryCV Japan countryJP Papua New Guinea countryPG Virgin Islands (British) countryVG Christmas Island countryCX Kenya countryKE Philippines countryPH Virgin Islands (U.S.) countryVI Cyprus countryCY Kyrgyzstan countryKG Pakistan countryPK Vietnam countryVN Czech Republic countryCZ Cambodia countryKH Poland countryPL Vanuatu countryVU Germany countryDE Kiribati countryKI St. Pierre and Miquelon countryPM Wallis and Futuna Islands countryWF Djibouti countryDJ Comoros countryKM Pitcairn countryPN Samoa countryWS Denmark countryDK Saint Kitts and Nevis countryKN Puerto Rico countryPR Yemen countryYE Dominica countryDM Korea, Democratic People's Republic of countryKP Palestine countryPS Mayotte countryYT Dominican Republic countryDO Korea, Republic of countryKR Portugal countryPT Yugoslavia countryYU Algeria countryDZ Kuwait countryKW Palau countryPW South Africa countryZA Ecuador countryEC Cayman Islands countryKY Paraguay countryPY Zambia countryZM Zaire countryZR Google also has four topic restricts:
<restrict> value US. Government unclesam Linux linux Macintosh mac FreeBSD bsd Combining the <lr> and <restrict> parameters
Search requests which use the lr and restrict parameters support the Boolean operators identified in the table below (in order of precedence).
Note: If both lr and restrict parameters are used in a search request, the sub-collection strings will be combined together using "AND" logic.
Boolean NOT [ - ] -lang_fr
Removes all results which are defined as part of the sub-collection immediately following the "-" operator. The example restrict value would remove all results in French.
Boolean AND [ . ] linux.countryFR
Returns results which are in the intersection of the results returned by the sub-collection to either side of the "." operator. The example restrict value would return all results which are from both the "linux" subtopic and identified as being located in France.
Boolean OR [ | ] lang_en|lang_fr
Returns results which are in either of the results returned by the sub-collection to either side of the "|" operator. The example restrict value would return all results matching the query that are in either the French or English sub-collections.
Parentheses [ ( ) ] (linux).(-(conutryUK|countryUS))
All terms within the innermost set of parentheses in a sub-collection string will be evaluated before terms outside the parentheses are evaluated. Use parentheses to adjust the order of term evaluation.
The example restrict value would return all results in the "linux" custom sub-collection that are not in either the United States or United Kingdom sub-collections.
Note: Spaces are not valid characters in the restrict parameter.
2.5 Input and Output Encodings - <ie>, <oe> Back to top In order to support searching documents in multiple languages and character encodings the Google Web APIs perform all requests and responses in the UTF-8 encoding. The parameters <ie> and <oe> are required in client requests but their values are ignored. Clients should encode all request data in UTF-8 and should expect results to be in UTF-8.
2.6 SafeSearch - <safeSearch> Back to top Many Google users prefer not to have adult sites included in their search results. Google's SafeSearch feature screens for sites that contain this type of information and eliminates them from search results. While no filter is 100% accurate, Google's filter uses advanced proprietary technology that checks keywords and phrases, URLs, and Open Directory categories.
If you find sites that contain offensive content in your results, even with SafeSearch activated; please send an email with the site's URL to safesearch@google.com and Google will investigate it.
2.7 Limitations Back to top There are some important limitations you should be aware of. Some of these are because Google's infrastructure is currently optimized for end users. However, in the future we hope to vastly increase the limits for Google Web APIs developers.
Component Limit Search request length 2048 bytes Maximum number of words in the query 10 Maximum number of site: terms in the query 1 (per search request) Maximum number of results per query 10 Maximum value of <start> + <maxResults> 1000
| 3. Search Results Format | Back to top |
3.1 Search Response Back to top Each time you issue a search request to the Google service, a response is returned back to you. This section describes the meanings of the values returned to you.
<documentFiltering> - A Boolean value indicating whether filtering was performed on the search results. This will be "true" only if (a) you requested filtering and (b) filtering actually occurred.
<searchComments> - A text string intended for display to an end user. One of the most common messages found here is a note that "stop words" were removed from the search automatically. (This happens for very common words such as "and" and "as.")
<estimatedTotalResultsCount> - The estimated total number of results that exist for the query.
Note: The estimated number may be either higher or lower than the actual number of results that exist.<estimateIsExact> - A Boolean value indicating that the estimate is actually the exact value.
<resultElements> - An array of <resultElement> items. This corresponds to the actual list of search results.
<searchQuery> - This is the value of <q> for the search request.
<startIndex> - Indicates the index (1-based) of the first search result in <resultElements>.
<endIndex> - Indicates the index (1-based) of the last search result in <resultElements>.
<searchTips> - A text string intended for display to the end user. It provides instructive suggestions on how to use Google.
<directoryCategories> - An array of <directoryCategory> items. This corresponds to the ODP directory matches for this search.
<searchTime> - Text, floating-point number indicating the total server time to return the search results, measured in seconds.
3.2 Result Element Back to top <summary> - If the search result has a listing in the ODP directory, the ODP summary appears here as a text string.<URL> - The URL of the search result, returned as text, with an absolute URL path.
<snippet> - A snippet which shows the query in context on the URL where it appears. This is formatted HTML and usually includes <B> tags within it. Note that the query term does not always appear in the snippet. Note: Query terms will be in highlighted in bold in the results, and line breaks will be included for proper text wrapping.
<title> - The title of the search result, returned as HTML.
<cachedSize> - Text (Integer + "k"). Indicates that a cached version of the <URL> is available; size is indicated in kilobytes.
<relatedInformationPresent> - Boolean indicating that the "related:" query term is supported for this URL.
<hostName> - When filtering occurs, a maximum of two results from any given host is returned. When this occurs, the second resultElement that comes from that host contains the host name in this parameter.
<directoryCategory> - See below.
<directoryTitle> - If the URL for this resultElement is contained in the ODP directory, the title that appears in the directory appears here as a text string. Note that the directoryTitle may be different from the URL's <title>.
3.3 Directory Category Back to top <fullViewableName> - Text, containing the ODP directory name for the current ODP category.
<specialEncoding> - Specifies the encoding scheme of the directory information.
© 2002 Google, Inc. All Rights Reserved.