Search
Clear search
Close search
Google apps
Main menu
true

Search Protocol Reference

Advanced Search Reporting Service /click Protocol

Advanced search reporting enables administrators to see what types of links a user chooses on a search results page, and more generally to track all actions that a user performs such as clicking navigational links. This information enables administrators to improve access and latency of search results, and to understand user click behavior. This document contains reference information about request parameters and the information logged by the search appliance about user click behavior.

An administrator enables advanced search reporting in the Admin Console’s Search > Search Features > Front Ends > Output Format page. The search appliance then modifies search result pages by inserting JavaScript on the page for tracking all links that a user clicks. When a user clicks a link in the search results, the JavaScript executes in the browser, requesting a URL from the search appliance. The URL starts with /click and contains information about the link. The arguments given in the URL are logged on the search appliance, and the search appliance returns a response to the browser. The browser then retrieves the URL on which the user clicked.

The /click URL is not visible to users. This URL has little effect on user-perceived latency because the processing is performed on the client side, and both the request and response are as minimal as possible.

This document enables advanced administrators to understand the /click URL information that is sent to the search appliance. Administrators who monitor network data may see this information. Programmers can also use this information in custom applications.

For information about configuring advanced search reporting in the Admin Console, see "Gathering Information about the Search Experience" in Creating the Search Experience. For information on search requests, Request Format.

The following describes how an advanced search reporting request is handled by the search appliance.

  1. The user submits a search request to the Google Search Appliance.
  2. The search appliance sends back search results.
  3. The user clicks a URL in the search results.
  4. The browser sends the associated URL to the search appliance.
  5. The browser also sends a hidden /click URL to the search appliance containing advanced search reporting parameters about the link that the user clicked. For more information, see Request Parameters.
  6. The search appliance responds to the browser by sending an HTTP status code of 204 (no content) to acknowledge receipt of the /click URL. For more information, see See Responses.
  7. The search appliance takes the /click URL information and uses the URL to write advanced search reporting information to a log file. Administrators view the log on the Admin Console. For more information on advanced search reporting and the Admin Console, see "Gathering Information about the Search Experience" in Creating the Search Experience.

Back to top

Request Parameters


Advanced search reporting requires the site parameter. Ensure that you include &site= collection in request URLs, where collection is the collection being queried.

The end user does not see a /click URL. If an administrator uses a program such as tcpdump to view data on the Internet connection, the /click information is visible. Administrators or programmers can use this information for debugging or in an application. The parameters in the /click URL are as follows.

URL Parameter

Description

Example

cd

Click data. This is additional, user-provided information to give more information or context about the click. This is not interpreted by the search appliance and is just logged. This would typically only be used by people who perform advanced customization and need to log additional information.

cd=malta

ct

Required parameter. Click type. A value that identifies the type of link that a user clicks. For the value, use underscores or a dot without spaces and use alpha-numeric characters. For a complete list of click types, see "Click Types in Advanced Search Reports" in Creating the Search Experience.

This is an extensible field. You can add your own values to this parameter. We recommend that you do not use any values that Google has already defined. We recommend that you use a sequence containing alpha-numeric characters, underscores, hyphens, and periods.

ct=c

q

Query text

q=island+countries

r

Rank of the result on which the user clicks.

r=7

s

Specifies the index number of the first entry in the result set.

s=24

url

URL that the user clicked.

url=http%3A//www.foo.com/

site

Required parameter. If this parameter does not have a valid value, other parameters in the query string do not work as expected. Limits search results to the contents of the specified collection. You can search multiple collections by separating collection names with the OR character, which is notated as the pipe symbol, or the AND character, which is notated as a period. For more information about the site parameter, see site.

&site= collection

The following is an example request for advanced search reporting parameters:

/click?ct=desk.news&r=7&url=http%3A//www.foo.com/bar.html&q=olympics&site=default_collection

The request URL contains the following parameters:

Value

Description

/click

Start of the advanced search reporting URL.

ct=desk.news

User clicked the News link at the top of the search page.

r=7

The rank priority of the click is 7.

url=http%3A//www.foo.com/bar.html

The URL on which the user clicked.

q=olympics

The search query the user entered that created the search page.

site=default_collection

The collection that is searched.

When a user clicks a cluster label the following example appears:

ct=cluster&cd=spanish+cuisine&q=spain&site=default_collection

This URL contains the following information:

Value

Description

ct=cluster

User clicked a cluster label on the search page.

cd=spain+cuisine

The click data identifies the click for “spain cuisine.”

url=http%3A//www.foo.com/bar.html

The URL on which the user clicked.

q=spain

The search query the user entered that created the search page.

site=default_collection

The collection that is searched.

Back to top

Responses


In response to the /click URL, the search appliance always sends the same HTTP response back to the browser to acknowledge receipt. The response has a status code of 204 (no content) and a MIME type of image/gif.

The Google implementation running on the client generates a URL with JavaScript as a dummy image object. The result is ignored, because the response does not affect the client behavior. Its purpose is to log the user interactions on the server side.

Back to top

Was this article helpful?
How can we improve it?