NAV undefined
undefined
shell

Introduction

Welcome to the Cludo API! You can use our API to do searches and access your statistics. In addition to live searching, All of the functionality of the My.Cludo dashboard can be achieved through the API.

Authorization

Cludo uses two types of authorization. For public searching Cludo uses our custom Search authorization, wheras all other api endpoints require Basic authorization.

curl -X GET \
-I https://api.cludo.com/api/v3/search \
-H "Authorization: SiteKey Q3VzdG9tZXJJZDpTaXRlSWQ6U2l0ZUtleQ==" \

#result header example:
> GET /api/v3/search HTTP/1.1
> Host: https://api.cludo.com
> Authorization: SiteKey Q3VzdG9tZXJJZDpTaXRlSWQ6U2l0ZUtleQ==

When making a search, you must set a authorization header with the SiteKey authorization type.

Authorization: SiteKey <Base64({CustomerId}:{SiteId}:{SiteKey})>

This authorization type consists of a Base64-encoding of your CustomerId, the SiteId to access, and the SiteKey separated by :.

SiteKey is only used for public access to search content. For intranet and secure solutions, use Basic authorization.

If you wish to create a non-public search engine, please contact Cludo for more information on the setup procedure.

Basic authorization

curl -X GET \
-I https://api.cludo.com/api/v3/search \
-u {CustomerId}:{CustomerKey} \

#result header example:
> GET /api/v3/search HTTP/1.1
> Host: https://api.cludo.com
> Authorization: Basic Q3VzdG9tZXJJZDpDdXN0b21lcktleQ==

All API endpoints, except search, requires Basic auth over HTTP, where the username is your CustomerId, and the password is your CustomerKey. You can contact Cludo to get your id and key.

Most HTTP clients provide ways to automatically set your id and key upon the request header, but sometimes you may need to set it explicity. To do so, Base64-encode a string containing your id and key separated by a :.

Authorization: Basic <Base64({CustomerId}:{CustomerKey})>

Searching

Currently Cludo offers two types of searches:

Full searches

Full searches are the standard way to search with Cludo. With these requests you have a great varity of functions available to express your search. To read more about the HTTP response, click here.

HTTP request

curl 
-x POST \
-i https://api.cludo.com/api/v3/{CustomerId}/{EngineId}/search \
-H "Content-Type: application/json" \
-u {CustomerId}:{CustomerKey} \
-d <JSON BODY> \

Go here to se a full example of a request body and here to se a response body.

POST https://api.cludo.com/api/v3/{CustomerId}/{EngineId}/search

Parameter Description
CustomerId Your customer id
EngineId The id of the search engine to use for the search

Query parameters

There are several features available when making a full search. The features can be grouped into these five categories, each controling a different element of the search:

Query

{
  "query": "My search string",
  "operator": "or"
}

When making a search, the main feature is the user text input, specified with the query property. This property is used by the searchengine to filter and rank the search results based on importance. A query is simply just the terms you wish to exist in the search result, such as:

school activity

In this example search results containing either school or activity will be returned, but if a search result contains both terms, it will be considered more important, and will be shown before search results containin only one of the terms.

The default behavior for all searches is to match at least one term. The alternative is to require all terms to match. To change the behavior for a search, just set the operator property.
Possible values for the operator are:

Advanced queries

If more advanced queries are needed, either use the other HTTP request properties, or use the query string syntax.

Filtering

{
  "postFilters": {
    "Category": ["Publications", "Events"],
    "date": ["EventDate", "20170601", "20170630"]
  },
  "postFilterOperator": "or",

  "filters": {
    "Domain": ["http://www.mydomain.com"],
    "range": ["Price", 20, 100],
    "date": ["EventDate", "20170601", "20170630"]
  },

  "notFilters": {
    "date": ["ProductionYear", "", 2015]
  }, 
  "enableFacetFiltering": true
}

Filtering limits search request fields to match given values, such as a price within a given range, a date within a specific month, or have a given category.

Currently, three properties are used to set filters: filters, notFilters and postFilters. Which property you use, depends on when in the search process the filter is added: filters and notFilters are executed along with the query, and will affect the ranking and facets, whereas the postFilter only filters out not matching search results, but does not affect facets. To enable postFilters on facets use the enableFacetFiltering property.

By default, when specifying multiple post filters, then all filters must match, before a search result is valid. To change this behavior use the postFilterOperator property. Its possible values are:

Syntax

When adding a filter to any of the properties, you must first decide which type of filter is neded:

Values

Examples on using a value filter:

"Category": ["Publications", "Events"]
"DocumentType": ["PDF"]

The value filter limits a field to specific values. This is recommended when you have a limited, known amount of choices such as with categories, car brands or file types in which you show to the user via facets.

The value filter type is simply just a range of values to match.

Range

Examples on using a range filter:

"range": ["Price", 20, 100]
"range": ["WheelRimSize", 25.5, ""]
"range": ["PoolSize", "", 2000]
"range": ["LegoPieces", "500.75", "750.57"]

The range filter is used to limit a number field to be within or greater- or less-than-or-equal-to than the specified value(s). The filter consists of three parameters:

  1. Field to filter
  2. Minimum value
  3. Maximum value

Use comma ',' as the parameter separator, and a dot '.' as a decimal separator. String representation of the values are also allowed. To use only one end of the range, just insert an empty string as value. If both value parameters are empty, then the filter will be ignored.

Date

Examples on using a date filter:

"date": ["ProductionYear", "2015", "2017"]
"date": ["PremiereDate", "2017-06-01", ""]
"date": ["Exipration", "", "2020-12-24T20:00"]

The date filter is used to limit a date-time field to be within, before or after the specified date(e). The filter consists of three parameters:

  1. Field to filter
  2. Minimum date-time
  3. Maximum date-time

Both date-time values must be strings and in ISO 8601 format, such as:

If no time part is specified, then the full date is included in the search, meaning the date-time 2017-06-13T22:13 wil be considered within a range using 2017-06-13. If only one limit is needed just insert an empty string into the one to ignore. If both value parameters are empty, then the filter will be ignored.

Ranking

{
  "sort": {
    "City": "asc",
    "Street": "asc",
    "LastName": "desc"
  },
  "valueBoost": [
    {
      "fieldName": "Category",
      "Boosts": [
        {
          "Boost": 23.4,
          "Values": ["A", "B", "C"]
        }
      ]
    }
  ]
}

When searching, the Cludo will attempt to order the search results, based on how well they match the given query. For most searches the Cludo ranking algorithm will be enough, but if you need to override the ranking completely, or at least affect affect certain aspects of it, then use the sort property or the valueBoost property.

Custom sort

A custom sort set on the sort property, overrides the entire ranking algorithm with the given sort model. The sort type is a model, where the property names are the fields to sort, and the values specifies the direction of the sort. The order of the properties determine the order of the sort.

Value boost

Value boostings set on the valueBoost property, will increase search results matching a given boost to be ranked higher than others. The valueBoost property type is an array of boost models, each consisting of the field to boost and an array of boostings, determining the boost value when matching a given value.

Grouping

{
  "perPage": 10,
  "page": 2
}

Grouping allows you to slice a search result into batches, and return each bach in a controlled manner. This allows paging of search results.

The perPage property controls the amount of search results returned in the HTTP response, wheras the page property selects the page to return.

Both properties must be a positive integer.

Rendering

{
  "responseType": "JsonHtml",
  "template": "MainSite Template",
  "overlay": "Overlay Template V2"
}

The final step before returning search results is selecting how you want the results presented. For this you use the responseType property with one of the following options:

To read more about the variation in the HTTP Response click here.

JsonObject returns all data as json, wheras JsonHtml pre-renders the search results, and the facets with a pre-determined template.

The template to use is specified with the template property when you have a Business or Enterprise solution and with the overlay property when you have a Essensial or Professional solution.

HTTP Response

Depending on the requested responseType described here, one of the two types of responses may be received. Their differences lies within how the search results, facets and suggestions are returned.

JsonObject response

The JsonObject response returns all data as json models, to be processed client side by JavaScript or other code.

JsonHtml response

The JsonHtml response returns search results and facets as pre-rendered HTML code, ready to be injected into a HTML page.

Table of request properties

Full HTTP request example:

{
  "query": "The search string here",
  "operator": "or",

  "filters": {
    "range": ["Price", 20, 100]
  },
  "notFilters": {
    "date": ["EventDate", "20170601", "20170630"]
  },
  "postFilters": {
    "Category": ["Publications", "Events"]
  },
  "postFilterOperator": "or",
  "enableFacetFiltering": true,

  "sort": {
    "City": "asc"
  },
  "valueBoost": [
    {
      "fieldName": "Category",
      "Boosts": [
        {
          "Boost": 23.4,
          "Values": ["A", "B", "C"]
        }
      ]
    }
  ],

  "responseType": "JsonHtml",
  "template": "MainSite Template",
  "overlay": "Overlay Template V2"
}
Parameter Required Type Default value Description
Query
query yes string The text you want to search for.
operator no enum Engine specific Specify if one or more query terms should match, or all terms must match.
Possible values are:
  • or
  • and
Filtering
filters no Filter Model Specify range and date filters to limit the search results.
notFilters no Filter Model Specify exclusion range and date filters to limit the search results.
postFilters no postFilter Model Specify facet filters to limit the search results.
postFiltersOperator no enum and The relation between post filters.
Possible values are:
  • or
  • and
enableFacetFiltering no bool false If you require post filters to be set on the HTTP response facets. See also Response facets.
Ranking
sort no Sort Model Set a value to override the default sort behavior with an explicit one.
valueBoost no ValueBoost Model Allows explicit search result boosting based on specific values.
Grouping
perPage no uint32 10 Amount of search results in the response. Use together with page to batch the results.
page no uint32 1 The page index of search results to return. Use together with perPage to batch the results.
Rendering
responseType no enum JsonObject The resulting format to return the search results as in the HTTP Response.
template no string The name of the template to use for rendering JsonHTML.
overlay no string The name of the overlay template to use for rendering JsonHTML.

Table of response properties

Depending on the responseType property on the request, the reponse have different properties.

Common properties

Common properties for both response types are:

Parameter Type Description
QueryId string A random string identifying the search query.
ResponseTime uint64 The time in milliseconds it took the Cludo servers to make the search.
FixedQuery string If no results where found for the original query, the searchengine will attempt another search with spelling corrections. If so, the corrected terms will be displayed here.
TotalDocument uint32 The total amount of matches found.
Banners Banner model array An array of banners matching the search query.
Synonyms string array An array of synonyms matching the search query.

JsonObject response

Full JsonObject HTTP response example:

{
  "QueryId": "c77f19d9a4b243b182466ca31cf9848c",
  "ResponseTime": 40,
  "FixedQuery": "tollroad",
  "Suggestions": [
    {
      "Text": "roadpricing",
    }
  ],
  "TotalDocument": 80,
  "TypedDocuments": [ 
    {
      "ResultIndex": 1,
      "Fields": {
        "Title": {
          "Field": "Title",
          "Value": "Amazing title about tollroads",
          "Values": [ "Amazing title about tollroads"],
          "Highlights": ["Amazing title about <b>tollroads</b>"],
          "IsArray": false
        },
        "Description":{
          "Field": "Description",
          "Value": "A long description",
          "Values": [ "A long description"],
          "Highlights": ["A long description"],
          "IsArray": false
        },
        "NewsArea":{
          "Field": "NewsArea",
          "Value": "Sports",
          "Values": ["Sports"],
          "Highlights": ["Sports"],
          "IsArray": false
        }
      },
      "FieldNames": [
        "Title",
        "Description",
        "NewsArea"
      ]
    }
  ], 
  "Facets": {
    "Category": {
      "FieldName": "Category",
      "MissingCount": 0,
      "AllCount": 35,
      "Items": [
        {
          "Key": "News",
          "Count": 30,
          "Facets": {
             "NewsArea": {
              "FieldName": "NewsArea",
              "MissingCount": 0,
              "AllCount": 30,
              "Items": [
                {
                  "Key": "Sports",
                  "Count": 20,
                  "Facets": {}
                },
                {
                  "Key": "Politics",
                  "Count": 10,
                  "Facets": {}
                }
              ]
            }
          }
        },
          {
          "Key": "Events",
          "Count": 5,
          "Facets": {}
        }
      ]
    }  
  },
  "Banners": [
    {
      "Banner":"<A HMTL STRING>",
      "Name":"My banner"
    }
  ],
  "Synonyms": [
    "highwaypricing"
  ]
}

Unique to the JsonObject response:


Parameter Type Description
Suggestions suggestion model array An array of suggestions for alternative searches.
TypedDocuments Typed document model array An array of the search results.
Facets Facet model Model containg all facets currently implemented on the engine.

JsonHtml response

Full JsonHtml HTTP response example:

{
  "QueryId": "c77f19d9a4b243b182466ca31cf9848c",
  "ResponseTime": 40,
  "FixedQuery": "tollroad",
  "DidYouMean": "roadpricing",
  "TotalDocument": 80,
  "SearchResult": "<A HTML STRING>", 
  "Facets": "<A HTML STRING>",
  "Banners": [
    {
      "Banner":"<A HMTL STRING>",
      "Name":"My banner"
    }
  ],
    "Synonyms": [
    "highwaypricing"
  ]
}

Unique to the JsonHtml response:

Parameter Type Description
DidYouMean string The first suggestion, if any.
Facets string The html generated string of the facets, created with the template set in the request.
SearchResult string The html generated string of the search results, created with the template set in the request.

AutoComplete searches

AutoComplete searches is a more minimalistic way of searching; Ideal for dropdown lists, helping the user input the correct search words.

HTTP request

There are two ways you may make a Autocomplete request. GET or POST.

HTTP GET request

curl 
-X GET \
-I -G https://api.cludo.com/api/v3/{CustomerId}/{EngineId}/autocomplete \
-u {CustomerId}:{CustomerKey} \
-d query={query} \
-d responsetype={responseType} \
-d filters={filters} \
-d results={results} \

GET https://api.cludo.com/api/v3/{CustomerId}/{EngineId}/autocomplete?query={query}&responsetype={responseType}&filters={filters}&results={results}

Parameter Description
CustomerId Your customer id
EngineId The id of the search engine to use for the search

HTTP POST request

curl 
-X POST \
-I https://api.cludo.com/api/v3/{CustomerId}/{EngineId}/autocomplete \
-u {CustomerId}:{CustomerKey} \
-H "Content-Type: application/json" \
-d <JSON BODY> \

POST https://api.cludo.com/api/v3/{CustomerId}/{EngineId}/autocomplete

Parameter Description
CustomerId Your customer id
EngineId The id of the search engine to use for the search

Query parameters

Parameter Description
query The string query to search for
responsetype the format to return the search results in.
filters filters to add to the search
results the amount of search results to return
template The template to render rich autocomplete
overlay The overlay template to render rich autocomplete

HTTP response

Depending on the responseType set in the request, different types of responses may be received.

Not specified response

An example of a HTTP response with no response type:

[
    "Feats",
    "Feets",
    "Features"
]

If no response type is set, then an array of titles will be returned

JsonHtml response

Full JsonHtml HTTP response example:

{
  "QueryId": "c77f19d9a4b243b182466ca31cf9848c",
  "ResponseTime": 40,
  "TotalResults": 8,
  "TotalSuggestions": 2,
  "Facets": "<A HTML STRING>",
  "SearchResult": "<A HTML STRING>"
}

Parameter Type Description QueryId string A random string identifying the search query. ResponseTime uint64 The time in milliseconds it took the Cludo servers to make the search. TotalResults uint32 The total amount of matches found. TotalSuggestions uint32 The total amount of suggestions. Facets string The html generated string of the facets, created with the template set in the request. SearchResult string The html generated string of the search results, created with the template set in the request.

JsonObject response

Full JsonObject HTTP response example:

{
  "QueryId": "c77f19d9a4b243b182466ca31cf9848c",
  "ResponseTime": 40,
  "TotalResults": 8,
  "TotalSuggestions": 2,
  "Facets": {
    "Category": {
      "FieldName": "Category",
      "MissingCount": 0,
      "AllCount": 35,
      "Items": [
        {
          "Key": "News",
          "Count": 30,
          "Facets": {
             "NewsArea": {
              "FieldName": "NewsArea",
              "MissingCount": 0,
              "AllCount": 30,
              "Items": [
                {
                  "Key": "Sports",
                  "Count": 20,
                  "Facets": {}
                },
                {
                  "Key": "Politics",
                  "Count": 10,
                  "Facets": {}
                }
              ]
            }
          }
        },
          {
          "Key": "Events",
          "Count": 5,
          "Facets": {}
        }
      ]
    }  
  },
  "Results":[
    {
      "ResultIndex": 1,
      "Fields": {
        "Title": {
          "Field": "Title",
          "Value": "Amazing title about tollroads",
          "Values": [ "Amazing title about tollroads"],
          "Highlights": ["Amazing title about <b>tollroads</b>"],
          "IsArray": false
        },
        "Description":{
          "Field": "Description",
          "Value": "A long description",
          "Values": [ "A long description"],
          "Highlights": ["A long description"],
          "IsArray": false
        },
        "NewsArea":{
          "Field": "NewsArea",
          "Value": "Sports",
          "Values": ["Sports"],
          "Highlights": ["Sports"],
          "IsArray": false
        }
      },
      "FieldNames": [
        "Title",
        "Description",
        "NewsArea"
      ]
    }
  ],
  "Suggestions": [
    {
      "ResultIndex": 1,
      "Fields": {
        "Title": {
          "Field": "Title",
          "Value": "Amazing title about tollroads",
          "Values": [ "Amazing title about tollroads"],
          "Highlights": ["Amazing title about <b>tollroads</b>"],
          "IsArray": false
        },
        "Description":{
          "Field": "Description",
          "Value": "A long description",
          "Values": [ "A long description"],
          "Highlights": ["A long description"],
          "IsArray": false
        },
        "NewsArea":{
          "Field": "NewsArea",
          "Value": "Sports",
          "Values": ["Sports"],
          "Highlights": ["Sports"],
          "IsArray": false
        }
      },
      "FieldNames": [
        "Title",
        "Description",
        "NewsArea"
      ]
    }
  ]
}
Parameter Type Description
QueryId string A random string identifying the search query.
ResponseTime uint64 The time in milliseconds it took the Cludo servers to make the search.
TotalResults uint32 The total amount of matches found.
TotalSuggestions uint32 The total amount of suggestions.
Facets Facet model Model containg all facets currently implemented on the engine.
Results uint32 The total amount of suggestions.
Suggestions uint32 The total amount of suggestions.

Query string syntax

The Cludo query string syntax supports the following command types within the search query string:

To avoid expressing everything as one big string, when making requests from a server, See Filtering, and Ranking.

Operators

When making a search such as school activity, it is usually interpreted as school OR activity, meaning that either term must match. It is possible to specify operators to control the search further. Operators supported are:

You may also use symbols instead of words:

Each operator operates on the 2 terms next to it, except NOT which only negates the term to the right. However, take notice that NOT takes precedence over AND, which again takes precedence over OR. Another way to control the search is to use + and - just before a term. The search string: insurance +car -bike states that car must be present, bike must not be present, and insurance is optional, but its presence increaces the scoring.

Grouping

Examples on using grouping:

(Harvard OR Oxford OR Princeton) AND University
(Harvard Oxford Princeton) AND University
(Hamster OR ginny AND pig) AND (Food OR nutrition)

Multiple terms can be grouped together with parentheses, to form sub-queries:

(mint OR new) AND condition

Sentences

Examples on using sentences:

"Tax deductions"
"car repair"~4

To match a specific sentence, simply wrap the terms with quotes:

"Quick brown fox"

This enforces that all terms must be found, and in the order specified. It's possible to use fuzzyness on sentences to allow unknown terms to occur between the terms specified, but the order of the terms must still be the same. To do this use ~:

"Quick fox"~

Fields

Examples on using fields:

Title:school
Title:"news channel"~3
food AND (Title:"animal (store OR shop)"~2)

To search only within a specific field, add the field name before the search:

Title:Taxdeductions

or to match a sentence in a field:

Title:"Car insurance"

Wildcards

Examples on using wildcards:

school*
ba?k
analy*

Searching with wildcards lets the searchengine insert zero or more characters within the string, in an attempt to match results. Use ? to specify a single character wildcard and * to specify a zero or more characters wildcard. Both and multiple may be used simultaneously.

For example: *bike will match bike, mountainbike, citybike and other terms ending with bike, wheras si?e will match site and size but not resize.

Fuzzyness

Examples on using fuzzyness:

trukc~   -> truck  (transposition)
bron~    -> brown  (insertion)
schoool~ -> school (deletion)
skhool~  -> school (substitution)

Fuzzyness helps with misspellings, by allowing insertion, deletion, substitution or transposition of characters. To allow fuzzyness add ~ to the end of a word. The amount of fuzzyness allowed may be specified by adding a number such as ~2. Fuzzyness are also available to sentences, to allow extra terms between the ones written.

"Car insurance"~2 will match "Car and motorcycle insurance", since ~2 allows up to 2 extra terms between the specified terms.

The less changes to a search, the more relevant scoring will the search result get.

Ranges

Examples on using ranges:

Price:[20 TO 40]
ProductionYear:[2016 TO 2017]
ShoeSize:[8 TO *]
Price:[20 TO 40}

To search for ranges of numbers, dates or strings, use square bracks to specify inclusive ranges <field>:[min TO max] and exclusive ranges with curly brackets <field>:{min TO max}. It is allowed to mix inclusive and exclusive ranges, and if an open range is required, use * as value.

Boosting

Examples on using boosting:

car^2 bike
hamster^2 "ginny pig"
vodka^0.5 gin^2 "white wine"^3

Sometimes, to the user, one term is more important than another. To indicate this importance to the searchengine, add a boosting score to terms with ^# where # is the boosting factor. The boost value must be a positive number, and decimals are allowed. A boosting value between 0 and 1 reduces the importance of a word, whereas one over 1 increases the importance.

Tracking

Tracking is important, otherwise it is hard to adapt your search to fit your users needs, therefore Cludo provides tracking of searches and clicked search results.

When tracking, you may log search queries, and search result clicks.

Queries

The command below tracks a user search. This is only necessary if you don't use the CludoJS script.

curl -X POST \
    https://api.cludo.com/api/v3/{CustomerId}/{EngineId}/search/pushstat/querylog \
    -H 'content-type: application/json' \
    -d '{
        "sz" : "1440x900",
        "ua" : "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/60.0.3112.113 Safari/537.36",
        "refurl" : "https://www.mysite.com/article/monkeys.html",
        "refpt" : "Article about monkeys | My Site",
        "sw" : "robots",
        "brl" : "en-US",
        "pn" : "1",
        "hn" : "www.mysite.com",
        "rc" : "29",
        "fquery" : "",
        "ban" : "0",
        "rt" : "13",
        "ql" : "",
        "qid" : "{QueryId}",
        "sid" : "{SessionId}",
        "qsid" : "{QuerySessionId}"
    }' \

Use this endpoint to track search statistics.

HTTP Request

POST https://api.cludo.com/api/v3/{CustomerId}/{EngineId}/search/pushstat/querylog

Parameter Description
CustomerId Your customer id
EngineId The id of the search engine to use for the search

HTTP Payload

The payload of the query log request must be in json format. The properties are described below.

Parameter Abbreviation for Description
sz Screen size The resolution of the users screen
E.g.
2560x1440
ua User agent The users user agent
E.g.
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/50.0.2661.102 Safari/537.36
refurl Referal url The URL of the page the user was at when doing the initial search.
E.g.
https://www.mysite.com/article/monkeys.html
refpt Referal page title The title of the page the user was at when doing the intial search
E.g.
Article about monkeys | My Site
sw search word The sentence searched for
brl browser language The browser language
pn Page number The page number requested in the search
hn Host name The host name of the page where the search is done at.
E.g.
www.mysite.com
rc Result count How many searches were returned to the user.
E.g.
5
fquery Fixed Query If we catch spelling mistakes the fixed query will be set to the fixed spelling mistakes.
E.g.
If the search word is carz, the fixed query would be cars
ban Banners The number of banners shown
rt Response time How fast was the search done
ql Quicklink If a Quicklink redirection occur, then set the ql parameter with the quicklink id, so we can track it
qid Query id A unique string used as the id of the query
sid Session id A unique string used as the id of the user sesson
qsid Query session id A unique string used as the id of the query within the user session

Clicks

The command below tracks a user search result click. This is only necessary if you don't use the CludoJS script.

curl -X POST \
    https://api.cludo.com/api/v3/{CustomerId}/{EngineId}/search/pushstat/clicklog \
    -H 'content-type: application/json' \
    -d '{
        "sz" : "1440x900",
        "ua" : "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/60.0.3112.113 Safari/537.36",
        "refurl" : "https://www.mysite.com/article/monkeys.html",
        "refpt" : "Article about monkeys | My Site",
        "sw" : "robots",
        "brl" : "en-US",
        "pn" : "1",
        "hn" : "www.mysite.com",
        "enid" : "58",
        "qid" : "{QueryId}",
        "sid" : "{SessionId}",
        "qsid" : "{QuerySessionId}",
        "clurl" : "https://www.mysite.com/article/robots",
        "cli" : "2",
        "title" : "Article about robots"
    }' \

Use this endpoint to track user search result click statistics.

HTTP Request

POST https://api.cludo.com/api/v3/{CustomerId}/{EngineId}/search/pushstat/clicklog

Parameter Description
CustomerId Your customer id
EngineId The id of the search engine to use for the search

HTTP Payload

The payload of the query log request must be in json format. The properties are described below.

Parameter Abbreviation for Description
sz Screen size The resolution of the users screen
E.g.
2560x1440
ua User agent The users user agent
E.g.
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/50.0.2661.102 Safari/537.36
refurl Referal url The URL of the page the user was at when doing the initial search.
E.g.
https://www.mysite.com/article/monkeys.html
refpt Referal page title The title of the page the user was at when doing the intial search
E.g.
Article about monkeys | My Site
sw search word The sentence searched for
brl browser language The browser language
pn Page number The page number requested in the search
hn Host name The host name of the page where the search is done at.
E.g.
www.mysite.com
qid Query id A unique string used as the id of the query
sid Session id A unique string used as the id of the user sesson
qsid Query session id A unique string used as the id of the query within the user session
clurl Clicked url The url the user clicked
cli Clicked link index The index of the search result the user clicked
title Title The title of the url the user clicked

Statistics

Cludo have several API endpoints related to pushing and retrieving statistics of searches.

Search counts per day

curl 
-X GET \
-I -G https://api.cludo.com/api/v3/{customerId}/{engineId}/statistics/GetOveralStatistics \
-d from=2016-08-14T22:00:00.000Z \
-d to=2016-08-22T12:44:38.799Z \
-d type=successful \

The above command returns daily aggregated data in the following json structure:

[
    {
        "Key": "2016-08-15", 
        "Value": 201
    },
    {
        "Key": "2016-08-16", 
        "Value": 993
    },
    {
        "Key": "2016-08-17", 
        "Value": 0
    }
]

Retrieves a list of search counts summed by day for a specified period.

HTTP request

GET https://api.cludo.com/api/v3/{customerId}/{engineId}/statistics/GetOveralStatistics

Parameter Default Description
from Datetime when you want statistics from eg. 2016-08-14T22:00:00.000Z
to Datetime when you want the statistics to eg. 2016-08-18T22:00:00.000Z
type all What statistics do you want. Options are
all - all statistics
unsuccessfull - only retrive search statistics without any results
successful - only retrieve search statistics which returned results

Search count totals

curl 
-X GET \
-I -G https://api.cludo.com/api/v3/{customerId}/{engineId}/statistics/GetTotalSearches \
-d from=2016-08-14T22:00:00.000Z \
-d to=2016-08-22T12:44:38.799Z \
-d type=Autocomplete \

The above command returns just a single digit with the sum for the given period:

1500

Retrieves a list of search counts for a specific requst type, for a specified period.

HTTP request

GET https://api.cludo.com/api/v3/{customerId}/{engineId}/statistics/GetTotalSearches

Parameter Default Description
from Datetime when you want statistics from eg. 2016-08-14T22:00:00.000Z
to Datetime when you want the statistics to eg. 2016-08-18T22:00:00.000Z
type Search Options are
Search - Regular searches
Autocomplete - Regular autocomplete
RichAutocomplete - Rich Autocomplete that does both regular autocomplete and search in one call.

Click counts

curl 
-X GET \
-I -G https://api.cludo.com/api/v3/{customerId}/{engineId}/statistics/clickcounts \
-d from=2016-08-14T22:00:00.000Z \
-d to=2016-08-22T12:44:38.799Z \

The above command returns daily aggregated data in the following json structure:

[
    {
        "pageNumber": 0,
        "pageSize": 10,
        "totalItems": 1,
        "items": [
            {
                "title": "Cludo click tracking statistics",
                "clickTarget": "http://cludo.com/all-about-clicktracking.pdf",
                "count": 22,
                "previousCount": 10
            }
        ]
    }
]

Retrieves a list of clicked targets for a specified period, ordered by popularity by default.

HTTP Request

GET https://api.cludo.com/api/v3/{customerId}/{engineId}/statistics/clickcounts?from=2017-05-17T22:00:00.000Z&to=2017-05-25T14:06:36.412Z

Parameter Default Description
from Datetime when you want statistics from eg. 2016-08-14T22:00:00.000Z
to Datetime when you want the statistics to eg. 2016-08-18T22:00:00.000Z
searchWord optional A search word to filter results by to only get results for a single search term
clickTarget page Click type to get results for, currently only supports 'page' which means ordinary search results
orderBy count Property to order by
sortOrder desc Sort direction (asc, desc)
pageSize 10 Number of results pr. page
pageNumber 0 Page number, zero indexed

Data indexing

Usually all indexing of pages, files and so on will be handled by the Cludo crawlers, but if nessesary, then Cludo provides some API endpoints to control the data in your data storage.

The following three endpoints are currently available:

Typically, pushurls should be used when you just want to add or update content using the supplied crawler's configuration. Use the push endpoint when you want to have total control over the data model indexed, or if you need to index content that is not accessible to the crawler.

URL pushing

Since full domain crawls are only made rarely (maybe once a day), then new pages to your website won't appear in search results before the domain is recrawled. If you cannot wait for a complete recrawl, then you may push the urls in question, which will be crawled within a couple of minutes.

HTTP request

The command below pushes urls for (re)crawling:

curl
-X POST \
-I https://api.cludo.com/api/v3/{CustomerId}/content/{CrawlerId}/pushurls \
-u {CustomerId}:{CustomerKey} \
-d '[
        "https://www.cludo.com/en/products/",
        "https://www.cludo.com/en/features/
    ]'

POST https://api.cludo.com/api/v3/{CustomerId}/content/{CrawlerId}/pushurls

Parameter Description
CustomerId Your customer id
CrawlerId The id of the crawler to schedule urls to crawl

HTTP body

The body content is simply a newline list of urls to crawl.

Data pushing

If you don't have any crawlers setup, or know exactly how your data is stored, you may directly push search results into your data storage with this endpoint.

HTTP request

The command below indexes data directly:

curl
-X POST \
-I https://api.cludo.com/api/v3/{CustomerId}/content/{CrawlerId}/push \
-u {CustomerId}:{CustomerKey} \

POST https://api.cludo.com/api/v3/{CustomerId}/content/{CrawlerId}/push

Parameter Description
CustomerId Your customer id
CrawlerId The id of the crawler to index the data into

HTTP body

An example of a HTTP body for a data index request:

[
  {
    "Title":"My title",
    "Description":"Description",
    "CustomField1":222,
    "CustomField2":"News"
  },
  {
    "Title":"My title",
    "Description":"Description",
    "CustomField1":123,
    "CustomField2":"Events"
  }
]

The body consists of result models of the data you wish to index. Each model consist of the field name with the associated value to set.

See an example in the code menu.

Try It Out

Request

Url Parameters

Body Parameters

Response