XML API reference

This page refers to the XML version of the Custom Search JSON API, which is available only to Google Site Search customers.

1. Overview
2. Programmable Search Engine Request Format
   1. Request Overview
   2. Query Terms
   3. Request Parameters
      1. Sample WebSearch Queries
      2. WebSearch Query Parameter Definitions
      3. Advanced Search
      4. Advanced Search Query Parameters
      5. Special Query Terms
      6. Sample Image Queries
      7. Image Search Query Parameters
      8. Request Limits
   4. Internationalizing Queries and Results Presentation
      1. Character Encoding
      2. Interface Languages
      3. Simplified and Traditional Chinese Search
   5. Filtering Results
      1. Automatic Filtering of Search Results
      2. Language and Country Filtering
      3. Filtering Adult Content with SafeSearch
3. XML Results
   1. Google XML Results DTD
   2. About the XML Response
   3. XML Results for Regular, Image, and Advanced Search Queries
      1. Regular/Advanced Search: Sample Query and XML Result
      2. Regular/Advanced Search: XML Tags
      3. XML Results for Image Search Queries
      4. Image Search: Sample Query and XML Result
      5. Image Search: XML Tags

Overview

The Google WebSearch service enables Google Site Search customers to display Google search results on their own web sites. The WebSearch service uses a simple HTTP-based protocol to serve search results. Search administrators have complete control over the way they request search results and the way they present those results to the end user. This document describes the technical details of the Google search request and results formats.

To retrieve Google WebSearch results, your application sends Google a simple HTTP request. Google then returns search results in XML format. XML-formatted results give you the ability to customize the way search results are displayed.

WebSearch Request Format

• Request Overview
• Query Terms
• Request Parameters
• Sample WebSearch Queries
• WebSearch Query Parameter Definitions
• Sample Image Queries
• Image Search Query Parameter Definitions
• Advanced Search
  
• Advanced Search Query Parameters
• Special Query Terms
• Request Limits

Request Overview

The Google search request is a standard HTTP GET command. It includes a collection of parameters relevant to your queries. These parameters are included in the request URL as name=value pairs separated by ampersand (&) characters. Parameters include data like the search query and a unique engine ID (cx) that identifies the engine that is making the HTTP request. The WebSearch or Image Search service returns XML results in response to your HTTP requests.

Query Terms

Most search requests include one or more query terms. A query term appears as the value of a parameter in the search request.

Query terms can specify several types of information to filter and organize the search results that Google returns. Queries can specify:

• Words or phrases to include or exclude
  • All of the words in a search query (default)
  • An exact phrase in the search query
  • Any word or phrase in a search query
• Where in a document to look for the search terms
  • Anywhere in the document (default)
  • Only in the body of the document
  • Only in the document title
  • Only in the document URL
  • Only in links in the document
• Restrictions on the documents themselves
  • Including or excluding documents of particular file types (such as PDF files or Word documents)
• Special URL queries that return information about a given URL, rather than doing a search
  • Queries that return general information about a URL, such as its Open Directory category, snippet or language
  • Queries that return the set of web pages that link to a URL
  • Queries that return a set of web pages similar to a given URL

Default Search

Search query parameter values must be URL-escaped. Note that you would substitute the plus sign ("+") for any whitespace sequences in the search query. This is discussed further in the URL Escaping section of this document.

The search query term is submitted to the WebSearch service using the q parameter. A sample search query term is:

q=horses+cows+pigs

By default, the Google WebSearch service only returns documents that include all of the terms in the search query.

Request Parameters

This section lists the parameters that you can use when making a search request. The parameters are split into two lists. The first list contains parameters that are relevant to all search requests. The second list contains parameters that are only relevant to advanced search requests.

Three request parameters are required:

• The client parameter must be set to google-csbe
• The output parameter specifies the format of the returned XML results; results can be returned with (xml) or without (xml_no_dtd) a reference to Google's DTD. We recommend setting this value to xml_no_dtd. Note: If you do not specify this parameter, then results will be returned in HTML instead of XML.
  
• The cx parameter which represents the unique ID of the engine.
  

The most commonly used request parameters other than the ones mentioned above are:

• num—the requested number of search results
• q—the search term(s)
• start—the starting index for the results

Sample WebSearch Queries

The examples below show a couple of WebSearch HTTP requests to illustrate how different query parameters are used. Definitions for the different query parameters are provided in the WebSearch Query Parameter Definitions and the Advanced Search Query Parameters sections of this document.

This request asks for the first 10 results (start=0&num=10) for the query term "red sox" (q=red+sox). The query also specifies that results should come from Canadian web sites (cr=countryCA) and should be written in French (lr=lang_fr). Finally, the query specifies values for the client, output, and cx parameters, all three of which are required.

http://www.google.com/search?
  start=0
  &num=10
  &q=red+sox
  &cr=countryCA
  &lr=lang_fr
  &client=google-csbe
  &output=xml_no_dtd
  &cx=00255077836266642015:u-scht7a-8i

This example uses some of the advanced search query parameters to further customize the search query. This request uses the as_q parameter (as_q=red+sox) instead of the q parameter. It also uses the as_eq parameter to exclude any documents containing the word "Yankees" from the search results (as_eq=yankees).

http://www.google.com/search?
  start=0
  &num=10
  &as_q=red+sox
  &as_eq=Yankees
  &client=google-csbe
  &output=xml_no_dtd
  &cx=00255077836266642015:u-scht7a-8i  

WebSearch Query Parameter Definitions

    <!DOCTYPE GSP SYSTEM "google.dtd">

Advanced Search

The additional query parameters listed below the image are relevant to advanced search queries. When you submit an advanced search, the values of several parameters (e.g. as_eq, as_epq, as_oq, etc.) are all factored into the query terms for that search. The image shows Google's Advanced Search page. On the image, the name of each advanced search parameter is written in red text inside of or next to the field on the page to which that parameter corresponds.

Advanced Search Query Parameters

Special Query Terms

Google WebSearch allows the use of several special query terms that access additional capabilities of the Google search engine. These special query terms should be included in the value of the q request parameter. Like other query terms, the special query terms must be URL-escaped. A number of the special query terms contain a colon (:). This character must also be URL-escaped; its URL-escaped value is %3A.

Sample Image Queries

The examples below show a couple of Image HTTP requests to illustrate how different query parameters are used. Definitions for the different query parameters are provided in the Image Query Parameter Definitions sections of this document.

This request asks for the first 5 results (start=0&num=5) for the query term "monkey" (q=monkey), of filetype .png. Finally, the query specifies values for the client, output, and cx parameters, all three of which are required.

http://www.google.com/cse?
  searchtype=image
  start=0
  &num=5
  &q=monkey
  &as_filetype=png
  &client=google-csbe
  &output=xml_no_dtd
  &cx=00255077836266642015:u-scht7a-8i

Image Search Query Parameters

Request Limits

The chart below lists limitations on the search requests that you send to Google:

Internationalizing Queries and Results Presentation

The Google WebSearch service enables you to search for documents in multiple languages. You can specify the character encoding that should be used to interpret your HTTP request and to encode your XML response (using the ie and oe search parameters). You can also filter results to only include documents written in certain languages.

The following sections discuss issues related to searching in multiple languages:

• Character Encoding
• Interface Languages
• Simplified and Traditional Chinese Search

Character Encoding

Servers send data, such as web pages, to user agents, such as browsers, as a sequence of encoded bytes. The user agent then decodes the bytes into a sequence of characters. When sending requests to the WebSearch service, you can specify the encoding schemes for both your search query and for the XML response that you receive.

You can use the ie request parameter to specify the encoding mechanism for the characters in your HTTP request. You can also use the oe parameter to specify the encoding scheme that Google should use to encode your XML response. If you are using an encoding scheme other than ISO-8859-1 (or latin1), please ensure that you specify the correct values for the ie and oe parameters.

Note: If you are providing search functionality for multiple languages, we recommend you use the utf8 (UTF-8) encoding value for both the ie and oe parameters.

Please refer to the Character Encoding Schemes appendix for a complete list of the values that you can use for the ie and oe parameters.

For more general information about character encoding, please see http://www.w3.org/TR/REC-html40/charset.html.

Interface Languages

You can use the hl request parameter to identify the language of your graphical interface. The hl parameter value may affect XML search results, especially on international queries when language restriction (using the lr parameter) is not explicitly specified. In such cases, the hl parameter may promote search results in the same language as the user's input language.

We suggest you explicitly set the hl parameter in search results to ensure that Google selects the highest quality search results for each query.

Please see the Supported Interface Languages section for a complete list of valid values for the hl parameter.

Searching for Documents Written in Specific Languages

You can use the lr request parameter to restrict search results to documents that are written in a particular language or set of languages.

The lr parameter supports Boolean Operators to allow you to specify multiple languages that should be included (or excluded) from search results.

The following examples show how you might use Boolean Operators to request documents in different languages.

For documents written in Japanese:

lr=lang_jp

For documents written in Italian or German:

lr=lang_it|lang_de

For documents not written in Hungarian or Czech:

lr=(-lang_hu).(-lang_cs)

Please see the Language Collection Values section for a complete list of possible values for the lr parameter and the Boolean Operators section for a complete discussion of the use of these operators.

Simplified and Traditional Chinese Search

Simplified Chinese and Traditional Chinese are two writing variants of the Chinese language. The same concept may be written differently in each variant. Given a query in one of the variants, the Google WebSearch service can return results that include pages in both variants.

To use this feature:

1. Set the c2coff request parameter to 0
   and
2. Do one of the following:
   • Do not set the lr request parameter
     or
   • Set the lr request parameter to lr=lang_zh-TW|lang_zh-CN

The following example shows the query parameters you would include in a request for results in both simplified and traditional Chinese. (Note that additional required information, such as the client, is not included in the example.)

search?hl=zh-CN
    &lr=lang_zh-TW|lang_zh-CN
    &c2coff=0

Filtering Results

Google WebSearch provides a number of ways to filter your search results:

• Automatic Filtering of Search Results
• Language and Country Filtering
• Filtering Adult Content with SafeSearch

Automatic Filtering of Search Results

In an effort to provide the best search results possible, Google uses two techniques to automatically filter search results that are generally considered undesirable:

• Duplicate Content—If multiple documents contain the same information, then only the most relevant document of that set is included in your search results.

• Host Crowding—If there are many search results from the same site, Google may not show all the results from that site or may show the results lower in
  the ranking than they otherwise would have been.

We recommend you leave these filters on for typical search requests because the filters significantly enhance the quality of most search results. However, you can bypass these automatic filters by setting the filter query parameter to 0 in your search request.

Language and Country Filtering

The Google WebSearch service returns results from a master index of all Web documents. The master index contains subcollections of documents that are grouped by particular attributes, including language and country of origin.

You can use the lr and cr request parameters to restrict search results to subcollections of documents that are written in particular languages or originate from particular countries, respectively.

Google WebSearch determines the language of a document by analyzing:

• the top-level domain (TLD) of the document's URL
• language meta tags within the document
• the primary language used in the body text of the document

Please also see the definition of the lr parameter, the section on Searching for Documents Written in Specific Languages and the Language Collection Values that can be used as values for the lr parameter for more information on restricting results based on language.

Google WebSearch determines the country of a document by analyzing:

• the top-level domain (TLD) of the document's URL
• the geographic location of the Web server's IP address

Please also see the definition of the cr parameter and the Country Collection Values that can be used as values for the cr parameter for more information on restricting results by country of origin.

Note: You can combine language values and country values to customize your search results. For example, you could request documents that are written in French and come from France or Canada, or you could request documents that come from Holland and are not written in English. The lr and cr parameters both support Boolean Operators.

Filtering Adult Content with SafeSearch

Many Google customers do not want to display search results for sites that contain adult content. Using our SafeSearch filter, you can screen for search results that contain adult content and eliminate them. Google's filters use proprietary technology to check keywords, phrases and URLs. While no filters are 100 percent accurate, SafeSearch will remove the overwhelming majority of adult content from your search results.

Google strives to keep SafeSearch as current and comprehensive as possible by continually crawling the Web and by incorporating updates from user suggestions.

SafeSearch is available in the following languages:

You can adjust the degree to which Google filters your results for adult content using the safe query parameter. The following table explains Google's SafeSearch settings and how those settings will affect your search results:

If you have SafeSearch activated and you find sites that contain offensive content in your results, please email the site's URL to safesearch@google.com, and we will investigate the site.

XML Results

• Google XML Results DTD
• About the XML Response
• XML Results for Regular and Advanced Search Queries
• Regular/Advanced Search: Sample Query and XML Result
• Regular/Advanced Search: XML Tags

Google XML Results DTD

Google uses the same DTD to describe the XML format for all types of search results. Many of the tags and attributes are applicable for all search types. Some tags, however, are applicable only for certain search types. Consequently, the definitions in the DTD may be less restrictive than the definitions given in this document.

This document describes those aspects of the DTD that are relevant for WebSearch. When you look at the DTD, if you're working on WebSearch, you can safely ignore tags and attributes that are not documented here. If the definition differs between the DTD and the documentation, that fact is noted in this document.

Google can return XML results either with or without a reference to the most recent DTD. The DTD is a guide to help search administrators and XML parsers understand Google's XML results. Because Google's XML grammar may change from time to time, you should not configure your parser to use the DTD to validate each XML result.

Additionally, you should not configure your XML parser to fetch the DTD each time you submit a search request. Google updates the DTD infrequently, and these requests create unnecessary delay and bandwidth requirements.

Google recommends that you use the xml_no_dtd output format to get XML results. If you specify the xml output format in your search request, the only difference is the inclusion of the following line in the XML results:

<!DOCTYPE GSP SYSTEM "google.dtd">

You can access the latest DTD at http://www.google.com/google.dtd.

Please note that not all features in the DTD may be available or supported at this time.

About the XML Response

• All element values are valid HTML suitable for display unless otherwise noted in the XML tag definitions.
• Some element values are URLs that need to be HTML-encoded before they are displayed.
• Your XML parser should ignore undocumented attributes and tags. This allows your application to continue working without modification if Google adds more features to the XML output.
• Certain characters must be escaped when included as values in XML tags. Your XML processor should convert these entities back to the appropriate characters. If you do not convert entities properly, the browser may, for example, render the & character as "&". The XML Standard documents these characters; these characters are reproduced in the table below:

  Character	Escaped Forms	Entity	Character Code
  Ampersand	&	&	&
  Single Quote	'	'	'
  Double Quote	"	"	"
  Greater Than	>	>	>
  Less Than	<	&lt;	&#60;

XML Results for Regular and Advanced Search Queries

Regular/Advanced Search: Sample Query and XML Result

This sample WebSearch request asks for 10 results (num=10) about the search term "socer" (q=socer), which is the word "soccer" intentionally spelled wrong for this example.)

http://www.google.com/search?
    q=socer
    &hl=en
    &start=10
    &num=10
    &output=xml
    &client=google-csbe
    &cx=00255077836266642015:u-scht7a-8i 

This request yields the XML result below. Note that there are several comments in the XML result to indicate where certain tags not included in the result would appear.

<?xml version="1.0" encoding="ISO-8859-1" standalone="no" ?>

<GSP VER="3.2">
   <TM>0.452923</TM>
   <Q>socer</Q>

<PARAM name="cx" value="00255077836266642015:u-scht7a-8i" original_value="00255077836266642015%3Au-scht7a-8i"/>
   <PARAM name="hl" value="en" original_value="en"/>
   <PARAM name="q" value="socer" original_value="socer"/>
   <PARAM name="output" value="xml" original_value="xml"/>
   <PARAM name="client" value="google-csbe" original_value="google-csbe"/>
   <PARAM name="num" value="10" original_value="10"/>
   <Spelling>
      <Suggestion q="soccer"><b><i>soccer</i></b></Suggestion>
   </Spelling>
   <Context>

<title>Sample Vacation CSE</title>
    <Facet>
      <FacetItem>
        <label>restaurants</label>
        <anchor_text>restaurants</anchor_text>
      </FacetItem>
      <FacetItem>
        <label>wineries</label>
        <anchor_text>wineries</anchor_text>
      </FacetItem>
    </Facet>
    <Facet>
      <FacetItem>
        <label>golf_courses</label>
        <anchor_text>golf courses</anchor_text>
      </FacetItem>
    </Facet>
    <Facet>
     <FacetItem>
        <label>hotels</label>
        <anchor_text>hotels</anchor_text>
      </FacetItem>
    </Facet>
    <Facet>
      <FacetItem>
        <label>nightlife</label>
        <anchor_text>nightlife</anchor_text>
      </FacetItem>
    </Facet>
    <Facet>
      <FacetItem>
        <label>soccer_sites</label>
        <anchor_text>soccer sites</anchor_text>
      </FacetItem>
    </Facet>
   </Context>
   <RES SN="1" EN="10">
      <M>6080</M>
      /*
       * The FI tag after the comment indicates that the result
       * set has been filtered. If the number of results were exact, the
       * FI tag would be replaced by an XT tag in the same format.
       */
      <FI />
      <NB>
         /*
          * Since the request is for the first page of results, the PU tag,
          * which contains a link to the previous page of search results,
          * is not included in this XML result. If the sample result did include
          * a previous page of results, it would be listed here, in the same format
          * as the NU tag on the following line
          */
         <NU>/search?q=socer&hl=en&lr=&ie=UTF-8&output=xml&client=test&start=10&sa=N</NU>
      </NB>
      <R N="1">
         <U>http://www.soccerconnection.net/</U>
         <UE>http://www.soccerconnection.net/</UE>
         <T>SoccerConnection.net</T>
              <CRAWLDATE>May 21, 2007</CRAWLDATE>
         <S><b>soccer</b>; players; coaches; ball; world cup;<b>...</b></S>
  <Label>transcodable_pages</Label>
    <Label>accessible</Label>
         <Label>soccer_sites</Label>
         <LANG>en</LANG>
         <HAS>
            <DI>
               <DT>SoccerConnection.net</DT>
               <DS>Post your <b>soccer</b> resume directly on the Internet.</DS>
            </DI>
            <L/>
            <C SZ="8k" CID="kWAPoYw1xIUJ"/>
            <RT/>
         </HAS>
      </R>
      /*
       * The result includes nine more results, each enclosed by an R tag.
       */
   </RES>
</GSP>

Regular/Advanced Search: XML Tags

XML responses for regular search requests and advanced search requests both use the same set of XML tags. These XML tags are shown in the XML example above and explained in the tables below.

The XML tags below are listed alphabetically by tag name, and each tag definition contains a description of the tag, an example showing how the tag would appear in an XML result and the format of the tag's content. If the tag is a subtag of another XML tag or if the tag has subtags or attributes of its own, that information is also provided in the tag's definition table.

Certain symbols may be displayed next to some subtags in the definitions below. These symbols, and their meanings, are:

This example uses the refinement label golf_courses to
filter search results about Palm Springs:
    q=Palm+Springs+more:golf_courses

The URL-escaped version of this query is:
    q=Palm+Springs+more%3Agolf_courses

XML Results for Image Search Queries

This sample Image request asks for 5 results (num=5) about the search term "monkey" (q=monkey).

http://www.google.com/cse?
  searchtype=image
  &num=2
  &q=monkey
  &client=google-csbe
  &output=xml_no_dtd
  &cx=00255077836266642015:u-scht7a-8i

This request yields the XML result below.

<GSP VER="3.2">
  <TM>0.395037</TM>
  <Q>monkeys</Q>

  <PARAM name="cx" value="011737558837375720776:mbfrjmyam1g" original_value="011737558837375720776:mbfrjmyam1g" url_<escaped_value="011737558837375720776%3Ambfrjmyam1g" js_escaped_value="011737558837375720776:mbfrjmyam1g"/>
  <PARAM name="client" value="google-csbe" original_value="google-csbe" url_escaped_value="google-csbe" js_escaped_value="google-csbe"/>
  <PARAM name="q" value="monkeys" original_value="monkeys" url_escaped_value="monkeys" js_escaped_value="monkeys"/>
  <PARAM name="num" value="2" original_value="2" url_escaped_value="2" js_escaped_value="2"/>
  <PARAM name="output" value="xml_no_dtd" original_value="xml_no_dtd" url_escaped_value="xml_no_dtd" js_escaped_value="xml_no_dtd"/>
  <PARAM name="adkw" value="AELymgUP4VYSok20wy9SeYczEZ5UXxpBmRsJH4oC4aXhVuZgwGKuponcNXjrYkkw2bRv1BylIm89ndJ-Q4vxvyW0tcbiqipcQC9op_cBG84T12WMvX8660A" original_value="AELymgUP4VYSok20wy9SeYczEZ5UXxpBmRsJH4oC4aXhVuZgwGKuponcNXjrYkkw2bRv1BylIm89ndJ-Q4vxvyW0tcbiqipcQC9op_cBG84T12WMvX8660A" url_escaped_value="AELymgUP4VYSok20wy9SeYczEZ5UXxpBmRsJH4oC4aXhVuZgwGKuponcNXjrYkkw2bRv1BylIm89ndJ-Q4vxvyW0tcbiqipcQC9op_cBG84T12WMvX8660A" js_escaped_value="AELymgUP4VYSok20wy9SeYczEZ5UXxpBmRsJH4oC4aXhVuZgwGKuponcNXjrYkkw2bRv1BylIm89ndJ-Q4vxvyW0tcbiqipcQC9op_cBG84T12WMvX8660A"/>
  <PARAM name="hl" value="en" original_value="en" url_escaped_value="en" js_escaped_value="en"/>
  <PARAM name="oe" value="UTF-8" original_value="UTF-8" url_escaped_value="UTF-8" js_escaped_value="UTF-8"/>
  <PARAM name="ie" value="UTF-8" original_value="UTF-8" url_escaped_value="UTF-8" js_escaped_value="UTF-8"/>
  <PARAM name="boostcse" value="0" original_value="0" url_escaped_value="0" js_escaped_value="0"/>

  <Context>
    <title>domestigeek</title>
  </Context>

  <ARES/>
  <RES SN="1" EN="2">
    <M>2500000</M>
    <NB>
      <NU>/images?q=monkeys&num=2&hl=en&client=google-csbe&cx=011737558837375720776:mbfrjmyam1g&boostcse=0&output=xml_no_dtd
        &ie=UTF-8&oe=UTF-8&tbm=isch&ei=786oTsLiJaaFiALKrPChBg&start=2&sa=N
      </NU>
    </NB>
    <RG START="1" SIZE="2"/>
      <R N="1" MIME="image/jpeg">
        <RU>http://www.flickr.com/photos/fncll/135465558/</RU>
        <U>
          http://farm1.static.flickr.com/46/135465558_123402af8c.jpg
        </U>
        <UE>
          http://farm1.static.flickr.com/46/135465558_123402af8c.jpg
        </UE>
        <T>Computer <b>Monkeys</b> | Flickr - Photo Sharing!</T>
        <RK>0</RK>
        <BYLINEDATE>1146034800</BYLINEDATE>
        <S>Computer <b>Monkeys</b> | Flickr</S>
        <LANG>en</LANG>
        <IMG WH="500" HT="305" IID="ANd9GcQARKLwzi-t4lpWi2AERV3kJb4ansaQzTn3MNDZR9fD_JDiktPKByKUBLs">
          <SZ>88386</SZ>
          <IN/>
        </IMG>
        <TBN TYPE="0" WH="130" HT="79" URL="http://t0.gstatic.com/images?q=tbn:ANd9GcQARKLwzi-
t4lpWi2AERV3kJb4ansaQzTn3MNDZR9fD_JDiktPKByKUBLs"/>
      </R>
      <R N="2" MIME="image/jpeg">
        <RU>
          http://www.flickr.com/photos/flickerbulb/187044366/
        </RU>
        <U>
          http://farm1.static.flickr.com/73/187044366_506a1933f4.jpg
        </U>
        <UE>
          http://farm1.static.flickr.com/73/187044366_506a1933f4.jpg
        </UE>
        <T>
          one. ugly. <b>monkey</b>. | Flickr - Photo Sharing!
        </T>
        <RK>0</RK>
        <BYLINEDATE>1152514800</BYLINEDATE>
        <S>one. ugly. <b>monkey</b>.</S>
        <LANG>en</LANG>
        <IMG WH="400" HT="481" IID="ANd9GcQ3Qom0bYbee4fThCQVi96jMEwMU6IvVf2b8K5vERKVw-
           EF4tQQnDDKOq0"><SZ>58339</SZ>
          <IN/>
        </IMG>
        <TBN TYPE="0" WH="107" HT="129" URL="http://t1.gstatic.com/images?q=tbn:ANd9GcQ3Qom0bYbee4fThCQ
          Vi96jMEwMU6IvVf2b8K5vERKVw-EF4tQQnDDKOq0"/>
      </R>
  </RES>
</GSP>

Image Search: XML Tags

The table below shows additional XML tags used in XML responses for image search queries.

Certain symbols may be displayed next to some subtags in the definitions below. These symbols, and their meanings, are: