Click Tracking API Instructions

The click tracking API endpoint lets you send in click events, which allows you to see click data on your Admin Click Analytics page. We also use this click data to strengthen the search results algorithm for your site.

Read more about click tracking here. This API uses the post method for click tracking.

Getting Started

The endpoint is https://api.gsa.gov/technology/searchgov/v2/clicks/

Parameters include:

  • url
  • query
  • affiliate
  • position
  • module_code
  • access_key

A full example of this is

curl -i -X POST \ -H "Content-Type: application/x-www-form-urlencoded" \ -H "Content-Length: 0" \ -A "user agent string" \ "https://api.gsa.gov/technology/searchgov/v2/clicks/?url=https://foo.gov/clicked&affiliate=<AFFILIATE_NAME>&access_key=<AFFILIATE_ACCESS_KEY>&module_code=BOOS&query=test%20query&position=1"

Please note that we only support this particular content type (application/x-www-form-urlencoded).

OpenAPI Specification File

You can view the full details of this API in the OpenAPI Specification file available here: Open API specification file for the Clicks API

Required Parameters

All parameters below are required unless noted otherwise. As a reminder, all parameters must be uri-encoded.

  • You can find your site handle on the Search.gov Admin Center Settings page.
  • Your access key is unique to your site handle so they must be paired properly to return results. If you have more than one search site set up, make sure you’ve selected the right one to get the right handle/key combination.
Parameters Description
url The URL of the link that was clicked.
query The search term that surfaced this result and ended in a click.
affiliate You can find your site handle in the Admin Center on your settings page.
position The position/rank of the result on your search results page. Was it the first result or the second?
module_code The module code for the source of the clicked result. Must be a valid module code. See https://search.gov/manual/module-codes.html
access_key Your API access key. You can find this under Your Site > Activate > API Key. Note: The API key from api.data.gov will not work for this API. It must be the one from Search.gov’s admin center.

Expected Results

  • Success - A response status code of 200 and empty body.
  • Missing Required Parameters - A response status code of 400 and an error message describing the missing parameters. ["Query can't be blank"]
  • Invalid Or Inactive Affiliate - A response status code of 401 and an error message. ["Affiliate is invalid"]
  • Invalid API Access Key - A response status code of 401 and an error message. ["Access key is invalid"]
  • Unparseable URL - A response status code of 401 and an error message. ["Url is not a valid format"]
  • Invalid Module Code - A response status code of 401 and an error message. ["Module code {MODULE} is not a valid module"] ​

Terms of Service

​ By using this API, you agree to our Terms of Service.

Contact Us

Please never hesitate to reach out! Email the Search.gov team.

Back to top