University Research Program for Google Search

Google Research Home > University Research Programs > Google Search > Documentation

Documentation

Below you will find documentation outlining how to use the University Research Program for Google Search. Please remember that this service is only available for authorized researchers. If you are interested in applying to use this service, please visit the registration page.

Also note that in order to provide a reliable service, for each approved application, researchers may use this service for 2 years. After that period, researchers are certainly welcome to reapply.

If you have questions or trouble using the service, please visit the forum.

Request

Protocol

Requests to the search service are performed over HTTP using a GET request.

Base URL

The base URL of the search service is:

http://research.google.com/university/search/service

Request parameters

Each search request contains the following parameters. Parameters are appended to the base URL as url-encoded query string arguments as "key=value" pairs, delimited by "&" characters.

All of the following parameters are required.

Parameter Description
clid Assigned by Google and must be included in each search request.
rsz

Indicates the desired number of search results. Requests of size "small" will attempt to return 10 results. Requests of type "large" will attempt to return 20 results.

Values: {"small", "large"}

start

Indicates the index of the first desired search result, starting from 0.

Values: An integer between 0 and 980, inclusive.

q Indicates the url-encoded search terms.

Throttling

Requests to the service MUST be throttled, otherwise access to the service may be blocked, either temporarily, or permanently. A time period of at least one second must be allowed between requests.

Example requests

The following is an example search query for the term [google], starting with the first search result, with 10 results in the response:

http://research.google.com/university/search/service?clid=program-university.edu&start=0&rsz=small&q=google

The following is an example search query for the quoted term ["university research"], starting with the 21st search result, with 20 results in the response:

http://research.google.com/university/search/service?clid=program-university.edu&start=20&rsz=large&q=%22university+research%22

Response

Response codes

200 OK

The service will return an HTTP 200 OK status code on a successful request. The search results will follow in the body of the response.

400 Bad Request

The service will return an HTTP 400 Bad Request status code on invalid requests, such as when one or more of the required query parameters is missing or can not be parsed. The request should not be retried.

403 Forbidden

The service will return an HTTP 403 Forbidden status code if the specified "clid" and the client IP address do not match those required for access to the service. The request should not be retried with this clid from this client IP address.

500 Internal Server Error

The service will return an HTTP 500 Internal Server Error status code if the server can not handle the request for unanticipated reasons. The request may be retried after a delay of at least one second.

503 Service Unavailable

The service will return an HTTP 503 Service Unavailable status code if the server is busy or if the client has sent too many requests within a given time interval. The request may be retried after a delay of at least one second.

Namespace

The XML namespace of the search response elements is:

http://research.google.com/university/search

Response Elements

Successful search queries will return an XML document containing the search results, with the following RELAX NG schema:

default namespace = "http://research.google.com/university/search"

element GSP { # Root element.
  element Q { text }, # The original query.

  # PARAM[@name='num'] contains the number of results requested.

  # PARAM[@name='start'] contains the start position requested.
  element PARAM {
    attribute name { "num" | "start" },
    attribute value { xsd:integer }
  }+,

  # The resultset. Will not be returned if there are no matches.

  element RES {
    # The position of the first element returned (1-based).
    attribute SN { xsd:integer },

    # The position of the last element returned (1-based).
    attribute EN { xsd:integer },


    # Estimated total matches.
    element M { xsd:integer },

    # A single result.
    element R {
      # Position of this result in the total resultset (1-based).
      attribute N { xsd:integer },


      # The URL of the result.
      element U { text },

      # The escaped URL of the result.
      element UE { text },

      # The title of the result.
      element T { text },

      # The title of the result with bold tags stripped out.

      element TNB { text }
    }+
  }?
}
The "GSP" element

The root element of the search response.

Children: Q, PARAM, RES

The "Q" element

Contains the search terms specified in the search request.

Parent: GSP

The "PARAM" element

Echoes the request parameters.

When the name attribute contains the string "num" the value attribute contains the number of results requested (either "10" or "20")

When the name attribute contains the string "start" the value attribute contains the index of the first desired search result, starting from 0.

Parent: GSP

Attributes: name, value

The "RES" element

The result set. Contains the search result elements. Will not be returned if there are zero matching search results.

The value of the SN attribute contains the position of the first search result in the complete result set, starting from 1.

The value of the EN attribute contains the position of the first search result in the complete result set, starting from 1.

Parent: GSP

Attributes: SN, EN

Children: M, R

The "M" element

The estimated total matches.

Parent: RES

The "R" element

A single search result.

The value of the N attribute contains the position of this search result in the complete result set, starting from 1.

Parent: RES

Attributes: N

Children: U, UE, T, TNE

The "U" element

The URL of this search result.

Parent: R

The "UE" element

The url-escaped URL of this search result.

Parent: R

The "T" element

The title of this search result, with the search terms enclosed in XML-encoded <b></b> tags.

Parent: R

The "TNB" element

The title of this search result.

Parent: R

Example response

<?xml version="1.0" encoding="utf-8"?>
<GSP xmlns="http://research.google.com/university/search">
  <Q>google</Q>
  <PARAM name="num" value="10"/>
  <PARAM name="start" value="0"/>
  <RES SN="1" EN="10">
    <M>74400000</M>
    <R N="1">
      <U>http://www.google.com/</U>
      <UE>http://www.google.com/</UE>
      <T>&lt;b&gt;Google&lt;/b&gt;</T>
      <TNB>Google</TNB>
    </R>
    <R N="2">
      <U>http://www.google.com/addurl/</U>
      <UE>http://www.google.com/addurl/</UE>
      <T>Add your URL to &lt;b&gt;Google&lt;/b&gt;</T>
      <TNB>Add your URL to Google</TNB>
    </R>
    <R N="3">
      <U>http://maps.google.com/</U>
      <UE>http://maps.google.com/</UE>
      <T>&lt;b&gt;Google&lt;/b&gt; Maps</T>
      <TNB>Google Maps</TNB>
    </R>
    <R N="4">
      <U>http://news.google.com/</U>
      <UE>http://news.google.com/</UE>
      <T>&lt;b&gt;Google&lt;/b&gt; News</T>
      <TNB>Google News</TNB>
    </R>
    <R N="5">
      <U>http://video.google.com/</U>
      <UE>http://video.google.com/</UE>
      <T>&lt;b&gt;Google&lt;/b&gt; Video</T>
      <TNB>Google Video</TNB>
    </R>
    <R N="6">
      <U>http://groups.google.com/</U>
      <UE>http://groups.google.com/</UE>
      <T>&lt;b&gt;Google&lt;/b&gt; Groups</T>
      <TNB>Google Groups</TNB>
    </R>
    <R N="7">
      <U>http://images.google.com/</U>
      <UE>http://images.google.com/</UE>
      <T>&lt;b&gt;Google&lt;/b&gt; Image Search</T>
      <TNB>Google Image Search</TNB>
    </R>
    <R N="8">
      <U>http://www.google.org/</U>
      <UE>http://www.google.org/</UE>
      <T>&lt;b&gt;Google&lt;/b&gt;.org</T>
      <TNB>Google.org</TNB>
    </R>
    <R N="9">
      <U>http://directory.google.com/</U>
      <UE>http://directory.google.com/</UE>
      <T>&lt;b&gt;Google&lt;/b&gt; Directory</T>
      <TNB>Google Directory</TNB>
    </R>
    <R N="10">
      <U>http://earth.google.com/</U>
      <UE>http://earth.google.com/</UE>
      <T>&lt;b&gt;Google&lt;/b&gt; Earth</T>
      <TNB>Google Earth</TNB>
    </R>
  </RES>
</GSP>

Example Code

To see some sample code, click here.


©2008 Google - Google Home - About Google