The Click Scoring API allows programmatic access to record click and query "events", which can be used when developing a custom search application to record user click behavior and use it to impact relevance scores following data processing.
This API does not enable or disable Click Scoring, nor kick off log processing. Those actions are covered by the Settings and Activities APIs, respectively. More details about Click Scoring are available in the section on the Click Scoring Relevance Framework.
API Entry Points
/api/collection/collection/click: get statistics about recent Click Scoring events (queries or clicks) or record events.
Get Recent Events
GET /api/collections/collection/click
Input
Path Parameters
Enter path parameters.
| Key | Description |
|---|---|
| collection | The collection name. |
Query Parameters
None.
Output
Output Content
| Key | Type | Description |
|---|---|---|
| buffer_size | integer | The number of events in the buffer, if it is enabled. |
| buffering | boolean | Is true if buffering has been enabled. Buffering allows the Click Scoring process to store events in memory for later writing to the log files. It's meant to be used as a temporary measure and is most useful when log files are being moved during the Click Scoring analysis processes. When this is changed to false events in the buffer are flushed to the log files. |
| click_count | integer | The number of click events recorded. |
| logs_count | integer | The number of Click-related log files in use. |
| query_count | integer | The number of query events recorded. |
Response Codes
200: OK
Examples
Input
curl http://localhost:8888/api/collections/collection1/click
Output
{
"buffer_size": 0,
"buffering": false,
"click_count": 3,
"logs_count": 1,
"query_count": 4
}
Record User Queries and Clicks
The PUT request makes an entry into the click-collection.log file, which is where all queries and clicks are recorded for later processing.
PUT /api/collections/collection/click
Input
Path Parameters
Enter path parameters.
| Key | Description |
|---|---|
| collection | The collection name. |
Query Parameters
None.
Output
Output Content
| Key | Type | Description |
|---|---|---|
| type | string | The type of event being recorded. A value of "q" indicates a query event; a value of "c" indicates a click event. |
| req | string | A unique request ID. It is used for both types of events. |
| q | string | Used for query events, the user's query. |
| qt | long | Used for query events, the time of the query, in milliseconds since epoch. |
| hits | integer | Used for query events, the number of hits for the query. |
| u | string | Optionally used for query events, the user ID. |
| ct | long | Used for click events, the time of the click, in milliseconds since epoch. |
| doc | string | Used for click events, the document ID that the user selected. |
| pos | integer | Used for click events, the position of the document in the result list. |
Response Codes
200: Success
Examples
Input
Example Query Event:
curl -X PUT -H 'Content-type: application/json' -d '
{
"type":"q",
"req":"34509586770",
"q":"ipod",
"qt":1329157201,
"hits":545
}' http://localhost:8888/api/collections/collection1/click
Example Click Event:
curl -X PUT -H 'Content-type: application/json' -d '
{
"type":"c",
"req":"34509598766",
"ct":1329157350,
"doc":"http://www.apple.com",
"pos":6
}' http://localhost:8888/api/collections/collection1/click
Output
Corresponding entries in the click-collection.log file:
Q 1329157201 ipod none~34509586770 545
C 1329157350 none~34509598766 http://www.apple.com 6
