Introduction

Welcome to the Cludo API!

You can use our API to do searches, access your statistics, and manage pretty much anything related to your service. In short - all functionality found in My Cludo can be achieved through the API.

Regions

We have our servers located in multiple datacenters around the world. However, it's important that you're interacting with the correct API hostname for the region in which your account was created, as making calls to a different region will be rejected as unauthorized.

To find out which API hostname you should be interacting with, go to the API Settings page within MyCludo.

Samples

In all of the samples we provide here, we will be using api.cludo.com as the hostname. Remember to replace this with the hostname you should be interacting with instead.

For example, if the hostname displayed to you within MyCludo is api-us1.cludo.com, you should replace api.cludo.com with api-us1.cludo.com in the sample.

Authentication

We offer different means of authentication depending on the action you're looking to perform.

For public facing search, we support our custom site key authentication
Otherwise, we support basic authentication

Site key authentication

Site key authentication is a means of authentication that can only be used for search, and exists to facilitate public facing search where you don't want to expose your API key, which is otherwise the case with basic authentication.

Header

$ curl "https://api.cludo.com/api/v3/search"
    -H "Authorization: SiteKey NDU0NTU4OTo3NTc4MDMwOlNlYXJjaEtleQ=="

Authorization: SiteKey <Customer ID>:<Engine ID>:SearchKey

Parameters

Key	Type	Description
Customer ID	int	Your ID
Engine ID	int	The ID of the specific engine

Basic authentication

Header

$ curl "https://api.cludo.com/api/v3/someEndpoint"
    -u 4545589:3ede38fdc0824e18bb3adb9a21fbbdc8

$ curl "https://api.cludo.com/api/v3/someEndpoint"
    -H "Authorization: Basic NDU0NTU4OTozZWRlMzhmZGMwODI0ZTE4YmIzYWRiOWEyMWZiYmRjOA=="

Authorization: Basic <Customer ID>:<API Key>

Parameters

Key	Type	Description
Customer ID	int	Your ID
API Key	string	Your API key

Searching

Currently Cludo offers two types of searches:

Full searches
Auto complete searches

Full searches

Full searches is the standard way to search with Cludo. With these requests you have a great variety 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}:{API_Key} \
-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
Filtering
Ranking
Grouping
Rendering

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:

or
and

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"]
  },
  "postFiltersOperator": "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 postFiltersOperator property. Its possible values are:

and
or

Syntax

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

values
number ranges
date ranges

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:

Field to filter
Minimum value
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:

Field to filter
Minimum date-time
Maximum date-time

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

2017-06-13T02:50:25+00:00
2017-06-13T02:50:25Z
20170613T025025Z
2017-06-13

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:

JsonObject
JsonHtml

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"]
  },
  "postFiltersOperator": "or",
  "enableFacetFiltering": true,
  "enableRelatedSearches": 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](#full-searches_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](#full-searches_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](#full-searches_response_facets).
[Ranking](#full-searches_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](#full-searches_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](#full-searches_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.
*[Related Searches](#full-searches_relatedSearches)**
enableRelatedSearches	no	bool	false	If you want to also get related searches for the specific search term.

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.
GenerativeAnswerAvailable	bool	True/False indicating the likelihood for providing a good generative answer for the 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"
  ],
  "RelatedSearchDocuments": [  
      {  
         "SearchTerm": "search term 1",
         "DocsCount": 10
      },
      {  
         "SearchTerm": "search term 2",
         "DocsCount": 5
      }
   ]
}

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.
RelatedSearchDocuments	Related searches model	An array of related searches.

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>",
  "RelatedSearchesResult": "<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.
RelatedSearchesResult	string	The html generated string of the related searches 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}:{API_Key} \
-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}:{API_Key} \
-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:

Operators
Grouping
Sentences
Fields
Wildcards
Fuzzyness
Ranges
Boosting

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:

AND
OR
NOT

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 the concept of actually recording what your visitors are searching for and what they're interested in. Without it, Cludo would simply serve as a search solution and wouldn't be able to provide you with statistics and other crucial data features.

Queries

Record a search query.

Request

$ curl "https://api.cludo.com/api/v3/4545589/7578030/search/pushstat/querylog"
    -X POST
    -H "Content-Type: application/json"
    -d '{
            "sz": "4096x2160",
            "ua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.77 Safari/537.36",
            "refurl": "https://www.cludo.com/site-search-features/",
            "refpt": "Customizable, whitebox AI driven site search built for marketers - Cludo",
            "sw": "government",
            "brl": "en-US",
            "pn": "1",
            "hn": "www.cludo.com",
            "rc": "7",
            "fquery": "",
            "ban": "2",
            "bnrs": "2673284,3933858",
            "rt": "34",
            "ql": "",
            "qid": "be74e31601814d8fb90750e5a7082916",
            "sid": "",
            "qsid": "1696ba3d02e74658a3673b509435b082"
        }'

$ curl "https://api.cludo.com/api/v3/4545589/7578030/search/pushstat/querylog?sz=4096x2160&ua=Mozilla%2F5.0%20(Windows%20NT%2010.0%3B%20Win64%3B%20x64)%20AppleWebKit%2F537.36%20(KHTML%2C%20like%20Gecko)%20Chrome%2F70.0.3538.77%20Safari%2F537.36&refurl=https%3A%2F%2Fwww.cludo.com%2Fsite-search-features%2F&refpt=Customizable%2C%20whitebox%20AI%20driven%20site%20search%20built%20for%20marketers%20-%20Cludo&sw=government&brl=en-US&pn=1&hn=www.cludo.com&rc=7&fquery=&ban=2&bnrs=2673284%2C3933858&rt=34&ql=&qid=be74e31601814d8fb90750e5a7082916&sid=&qsid=1696ba3d02e74658a3673b509435b082"
    -X POST

POST https://api.cludo.com/api/v3/<Customer ID>/<Engine ID>/search/pushstat/querylog

POST https://api.cludo.com/api/v3/<Customer ID>/<Engine ID>/search/pushstat/querylog?<Query parameters>

URL parameters

Parameter	Type	Description
Customer ID	int	Your ID
Engine ID	int	The ID of the specific engine that was used for this query

Body/Query parameters

Key	Represents	Type	Description
sz	Screen size	string	The pixel resolution of the visitor's screen
ua	User agent	string	The visitor's user agent string
refurl	Referal url	string	The URL of the page the query originated from
refpt	Referal page title	string	The title of the page the query originated from
sw	Query	string	The query
brl	Browser language	string	The language of the visitor's browser
pn	Page number	string	The page number requested in the search
hn	Host name	string	The host name of the page the query originated from
rc	Result count	string	The amount of results for the query
fquery	Fixed query	string	The actual performed query, if the original query was intercepted and adjusted by Cludo (e.g. spelling mistakes)
ban	Banners count	string	The number of banners shown
bnrs	Banner IDs	string	The IDs of the banners shown (comma separated)
rt	Response time	string	The time it took to perform the query
ql	Quicklink ID	string	The quicklink ID, if a quicklink redirection occurs
qid	Query ID	string	A unique string used as the ID of the query
sid	Visitor session ID	string	A unique string used as the ID of the visitor session
qsid	Query session ID	string	A unique string used as the ID of the query session
dt	Device Type	string	The type of device from which the search has been performed. Currently, our cludo.js script supplies the abstract device types - mobile, tablet, or desktop. These accepted values are case sensitive and an important part of our visualization services. If not passed correctly, all services relying on them won't work as expected.

Clicks

Record a search result click.

Request

$ curl "https://api.cludo.com/api/v3/4545589/7578030/search/pushstat/clicklog"
    -X POST
    -H "Content-Type: application/json"
    -d '{
            "ls": "searchresult",
            "sz": "4096x2160",
            "ua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.77 Safari/537.36",
            "refurl": "https://www.cludo.com/site-search-features/",
            "refpt": "Customizable, whitebox AI driven site search built for marketers - Cludo",
            "sw": "government",
            "brl": "en-US",
            "pn": "1",
            "hn": "www.cludo.com",
            "qid": "be74e31601814d8fb90750e5a7082916",
            "sid": "",
            "qsid": "1696ba3d02e74658a3673b509435b082",
            "clurl": "https://www.cludo.com/government/",
            "cli": "1",
            "cloi": "",
            "title": "Government"
        }'

$ curl "https://api.cludo.com/api/v3/4545589/7578030/search/pushstat/clicklog?ls=searchresult&sz=4096x2160&ua=Mozilla%2F5.0%20(Windows%20NT%2010.0%3B%20Win64%3B%20x64)%20AppleWebKit%2F537.36%20(KHTML%2C%20like%20Gecko)%20Chrome%2F70.0.3538.77%20Safari%2F537.36&refurl=https%3A%2F%2Fwww.cludo.com%2Fsite-search-features%2F&refpt=Customizable%2C%20whitebox%20AI%20driven%20site%20search%20built%20for%20marketers%20-%20Cludo&sw=government&brl=en-US&pn=1&hn=www.cludo.com&qid=be74e31601814d8fb90750e5a7082916&sid=&qsid=1696ba3d02e74658a3673b509435b082&clurl=https%3A%2F%2Fwww.cludo.com%2Fgovernment%2F&cli=1&cloi=&title=Government"
    -X POST

POST https://api.cludo.com/api/v3/<Customer ID>/<Engine ID>/search/pushstat/clicklog

POST https://api.cludo.com/api/v3/<Customer ID>/<Engine ID>/search/pushstat/clicklog?<Query parameters>

URL parameters

Parameter	Type	Description
Customer ID	int	Your ID
Engine ID	int	The ID of the specific engine that was used for the query

Body/Query parameters

Key	Represents	Type	Description
ls	Log source	string	Definition of the log source. For tracking regular clicks, it must be set to searchresult. For tracking banner clicks, it must be set to banner.
sz	Screen size	string	The pixel resolution of the visitor's screen
ua	User agent	string	The visitor's user agent string
refurl	Referal url	string	The URL of the page the query originated from
refpt	Referal page title	string	The title of the page the query originated from
sw	Query	string	The query
brl	Browser language	string	The language of the visitor's browser
pn	Page number	string	The page number requested in the search
hn	Host name	string	The host name of the page the query originated from
qid	Query ID	string	A unique string used as the ID of the query
sid	Visitor session ID	string	A unique string used as the ID of the visitor session
qsid	Query session ID	string	A unique string used as the ID of the query session
clurl	Click URL	string	The URL of the clicked search result
cli	Clicked search result index	string	The index of the clicked search result
cloi	Clicked banner ID	string	The ID of the banner, if it was a banner that was clicked
title	Title	string	The title of the clicked search result
dt	Device Type	string	The type of device from which the search has been performed. Currently, our cludo.js script supplies the abstract device types - mobile, tablet, or desktop. These accepted values are case sensitive and an important part of our visualization services. If not passed correctly, all services relying on them won't work as expected.

IP addresses

Some of our features are driven directly by the IP address of the visitor, like excluding analytics from certain ranges in My Cludo or our geo analytics. Usually we get that automatically as the tracking is initiated by our script on the visitor's machine, but if the tracking request to us doesn't originate from the visitor, you will need to provide the real IP address to us separately.

You can do so by providing an additional HTTP header with the tracking request.

Header

$ curl "https://api.cludo.com/api/v3/4545589/7578030/search/pushstat/querylog"
    -H "X-Real-IP: 127.0.0.1"

$ curl "https://api.cludo.com/api/v3/4545589/7578030/search/pushstat/clicklog"
    -H "X-Real-IP: 127.0.0.1"

X-Real-IP: <IP address>

Parameters

Key	Type	Description
IP address	string	The IP address of the visitor

Statistics

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

Search counts
Search count totals
Click counts

Search counts per day

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

Request

$ curl "https://api.cludo.com/api/v3/4545589/7578030/statistics/searchHistogram?type=successful&from=2016-08-14T22:00:00.000Z&to=2016-08-22T12:44:38.799Z&timezone=00:00"
    -u 4545589:3ede38fdc0824e18bb3adb9a21fbbdc8

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

{
    "totalSearches": [
        {
            "Key": "2016-08-14", 
            "Value": 200
        },
        {
            "Key": "2016-08-15", 
            "Value": 900
        },
        {
            "Key": "2016-08-16", 
            "Value": 0
        }
    ],
    "uniqueSearches": [
        {
            "Key": "2016-08-14", 
            "Value": 100
        },
        {
            "Key": "2016-08-15", 
            "Value": 450
        },
        {
            "Key": "2016-08-16", 
            "Value": 0
        }
    ]
}

GET https://api.cludo.com/api/v3/<Customer ID>/<Engine ID>/statistics/searchHistogram?type=<Type>&from=<From>&to=<To>&timezone=<Timezone>

URL parameters

Parameter | Type | Default | Description --------- | ------- | ----------- Customer ID | int | | Your ID Engine ID | int | | The ID of the specific engine Type | string | 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 From | string | | Datetime when you want statistics from eg. 2016-08-14T22:00:00.000Z To | string | | Datetime when you want the statistics to eg. 2016-08-18T22:00:00.000Z Timezone | string | 00:00 (UTC) | The timezone (UTC offset) the histogram should be formatted with, eg.:
00:00 - UTC
02:00 - UTC+2 (CEST)
-05:00 - UTC-5 (CDT)

Search count totals

Retrieves the search count, for a specified period.

Request

$ curl "https://api.cludo.com/api/v3/4545589/7578030/statistics/totalSearches?from=2019-03-28T22:00:00.000Z&to=2019-04-30T21:59:59.999Z&onlyIncludeUnique=false&includePreviousPeriod=false"
    -u 4545589:3ede38fdc0824e18bb3adb9a21fbbdc8

The above command returns the following JSON structure:

{
    "withinCurrentPeriod": 25000,
    "withinPreviousPeriod": null
}

GET https://api.cludo.com/api/v3/<Customer ID>/<Engine ID>/statistics/totalSearches?from=<From>&to=<To>&onlyIncludeUnique=<Only Include Unique>&includePreviousPeriod=<Include Previous Period>

URL parameters

Click counts

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

Request

$ curl "https://api.cludo.com/api/v3/4545589/7578030/statistics/clickCounts?from=2019-03-28T22:00:00.000Z&to=2019-04-30T21:59:59.999Z&query=&clickTarget=page&orderBy=count&sortOrder=descending&limit=10&pageNumber=1"
    -u 4545589:3ede38fdc0824e18bb3adb9a21fbbdc8

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,
                "uniqueCount": 11,
                "previousCount": 10,
                "previousUniqueCount": 5
            }
        ]
    }
]

GET https://api.cludo.com/api/v3/<Customer ID>/<Engine ID>/statistics/clickCounts?from=<From>&to=<To>&query=<Query>&clickTarget=<Click Target>&orderBy=<Order By>&sortOrder=<Sort Order>&limit=<Limit>&pageNumber=<Page Number>

URL parameters

Parameter | Type | Default | Description --------- | ------- | ----------- Customer ID | int | | Your ID Engine ID | int | | The ID of the specific engine From | string | | Datetime when you want statistics from eg. 2016-08-14T22:00:00.000Z To | string | | Datetime when you want the statistics to eg. 2016-08-18T22:00:00.000Z Query | string | optional | A search word to filter results by to only get results for a single search term Click Target | string | page | Click type to get results for, currently only supports 'page' which means ordinary search results Order By | string | count | Property to order by Sort Order | string | descending | Sort direction (ascending, descending) Limit | int | 10 | Number of results pr. page Page Number | int | 1 | Page number, zero indexed

Tools

Cludo provides you with a multitude of tools that can be used to provide your visitors with a great user experience.

Page rankings
Quicklinks
Synonyms

Page rankings

Page rankings are useful if you want to control the top search results for your visitors when they search for a pre-defined term.

Data structures

Ranking group

{
    "id": 1689348,
    "WebsiteId": 7578030,
    "name": "Hello, World!",
    "pages": [],
    "rankingterms": []
}

Key	Type	Description
id	int	The ID of the ranking group
WebsiteId	int	The ID of the engine the ranking group belongs to
name	string	The name of the ranking group
pages	array	An array of Ranked pages
rankingterms	array	An array of Terms

Ranked page

{
    "id": 6512590,
    "websiteid": 7578030,
    "RankingId": 1689348,
    "rank": 1,
    "showpage": true,
    "page": {}
}

Key	Type	Description
id	int	The ID of the ranked page
websiteid	int	The ID of the engine the ranked page belongs to
RankingId	int	The ID of the ranking group the ranked page belongs to
rank	int	The rank of the ranked page
showpage	bool	Whether the ranked page should be included
page	Page	A Page

Page

{
    "id": 9728711,
    "websiteid": 7578030,
    "pageid": "https://www.cludo.com/contact",
    "pageurl": "https://www.cludo.com/contact/",
    "searchable": true,
    "url": "http://cludo.com/9728711/",
    "website": "http://cludo.com/7578030/"
}

Key	Type	Description
id	int	The ID of the page
websiteid	int	The ID of the engine the page belongs to
pageid	string	The unique identifier of the page. Usually the URL but could be any string
pageurl	string	The URL of the page
searchable	bool	Whether the page is searchable
url	string	Legacy, disregard
website	string	Legacy, disregard

Term

{
    "id": 8720627,
    "rankingId": 1689348,
    "name": "hello"
}

Key	Type	Description
id	int	The ID of the term
rankingId	int	The ID of the ranking group this term belongs to
name	string	The actual term

Indexed document

{
    "url": "https://www.cludo.com/contact/",
    "title": "Contact",
    "documentId": "https://www.cludo.com/contact",
    "pageId": -1,
    "hasPageId": false,
    "isAddedAlready": false
}

Key	Type	Description
url	string	The URL of the original resource
title	string	The title of the original resource
documentId	string	The unique identifier of the document
pageId	int	Legacy, disregard
hasPageId	bool	Legacy, disregard
isAddedAlready	bool	Whether the document is already added to a ranking group

Get all page rankings

Get all page rankings for the entire account.

Request

$ curl "https://api.cludo.com/api/rankings"
    -u 4545589:3ede38fdc0824e18bb3adb9a21fbbdc8

GET https://api.cludo.com/api/rankings

Response

Will return an array of ranking groups. See data structures.

Get all page rankings by engine

Get all page rankings for a specific engine.

Request

$ curl "https://api.cludo.com/api/rankings/site/7578030"
    -u 4545589:3ede38fdc0824e18bb3adb9a21fbbdc8

GET https://api.cludo.com/api/rankings/site/<Engine ID>

URL parameters

Parameter	Type	Description
Engine ID	int	The ID of the specific engine

Response

Will return an array of ranking groups. See data structures.

Get single page ranking

Get a specific page ranking.

Request

$ curl "https://api.cludo.com/api/rankings/1689348"
    -u 4545589:3ede38fdc0824e18bb3adb9a21fbbdc8

GET https://api.cludo.com/api/rankings/<Page ranking ID>

URL parameters

Parameter	Type	Description
Page ranking ID	int	The ID of the specific page ranking

Response

Will return a single ranking group. See data structures.

Get indexed documents

Get indexed documents for an engine by either title or URL similarity.

Request

$ curl "https://api.cludo.com/api/v3/9056485/7578030/search/alldocuments?filter=contact&type=title&functionType=pageranking&page=1&perpage=25"
    -X POST
    -u 4545589:3ede38fdc0824e18bb3adb9a21fbbdc8
    -H "Content-Type: application/json"
    -d '[
            "https://www.cludo.com/site-search-features",
            "https://www.cludo.com/intranet"
        ]'

POST https://api.cludo.com/api/v3/<Customer ID>/<Engine ID>/search/alldocuments?filter=<Filter>&type=<Type>&functionType=<Function type>&page=<Page>&perpage=<Per page>

URL parameters

Parameter	Type	Description
Customer ID	int	Your ID
Engine ID	int	The ID of the specific engine
Filter	string	The search term
Type	string	How you want it to match on the filter. Either any, title, or url
Function type	string	In this context, this must be pageranking
Page	int	Used for pagination. If omitted, it will default to 1
Per page	int	Used for pagination. If omitted, it will default to 25

Body

An array of unique identifiers for documents that you want to exclude from the results. Otherwise, just an empty array.

Response

Will return an array of indexed documents. See data structures.

Create page ranking

Create a page ranking.

Request

$ curl "https://api.cludo.com/api/rankings"
    -X POST
    -u 4545589:3ede38fdc0824e18bb3adb9a21fbbdc8
    -H "Content-Type: application/json"
    -d '{
            "WebsiteId": 7578030,
            "name": "Hello, World!",
            "pages": [
                {
                    "websiteid": 7578030,
                    "rank": 1,
                    "showpage": true,
                    "page": {
                        "name": "Contact Cludo",
                        "websiteid": 7578030,
                        "pageid": "https://www.cludo.com/contact",
                        "pageurl": "https://www.cludo.com/contact/",
                        "searchable": true
                    }
                }
            ],
            "rankingterms": [
                {
                    "name": "hello"
                }
            ]
        }'

POST https://api.cludo.com/api/rankings

Body

A single ranking group. See data structures.

Response

Will return the created ranking group. See data structures.

Update page ranking

Update a specific page ranking.

Request

$ curl "https://api.cludo.com/api/rankings/1689348"
    -X PUT
    -u 4545589:3ede38fdc0824e18bb3adb9a21fbbdc8
    -H "Content-Type: application/json"
    -d '{
            "WebsiteId": 7578030,
            "name": "Hello, World!",
            "pages": [
                {
                    "websiteid": 7578030,
                    "rank": 1,
                    "showpage": true,
                    "page": {
                        "name": "The next generation of site search", 
                        "websiteid": 7578030,
                        "pageid": "https://www.cludo.com",
                        "pageurl": "https://www.cludo.com/",
                        "searchable": true
                    }
                },
                {
                    "id": 6512590,
                    "websiteid": 7578030,
                    "rank": 2,
                    "showpage": true,
                    "page": {
                        "name": "Contact Cludo",
                        "id": 9728711,
                        "websiteid": 7578030,
                        "pageid": "https://www.cludo.com/contact",
                        "pageurl": "https://www.cludo.com/contact/",
                        "searchable": true
                    }
                }
            ],
            "rankingterms": [
                {
                    "id": 8720627,
                    "rankingId": 1689348,
                    "name": "hello"
                },
                {
                    "name": "world"
                }
            ]
        }'

$ curl "https://api.cludo.com/api/rankings"
    -X POST
    -u 4545589:3ede38fdc0824e18bb3adb9a21fbbdc8
    -H "Content-Type: application/json"
    -d '{
            "id": 1689348,
            "WebsiteId": 7578030,
            "name": "Hello, World!",
            "pages": [
                {
                    "websiteid": 7578030,
                    "rank": 1,
                    "showpage": true,
                    "page": {
                        "name": "The next generation of site search", 
                        "websiteid": 7578030,
                        "pageid": "https://www.cludo.com",
                        "pageurl": "https://www.cludo.com/",
                        "searchable": true
                    }
                },
                {
                    "id": 6512590,
                    "websiteid": 7578030,
                    "rank": 2,
                    "showpage": true,
                    "page": {
                        "name": "Contact Cludo",
                        "id": 9728711,
                        "websiteid": 7578030,
                        "pageid": "https://www.cludo.com/contact",
                        "pageurl": "https://www.cludo.com/contact/",
                        "searchable": true
                    }
                }
            ],
            "rankingterms": [
                {
                    "id": 8720627,
                    "rankingId": 1689348,
                    "name": "hello"
                },
                {
                    "name": "world"
                }
            ]
        }'

PUT https://api.cludo.com/api/rankings/<Page ranking ID>

POST https://api.cludo.com/api/rankings

URL parameters

Parameter	Type	Description
Page ranking ID	int	The ID of the specific page ranking

Body

A single ranking group. See data structures.

Response

Will return the updated ranking group. See data structures.

Delete page ranking

Delete a specific page ranking.

Request

$ curl "https://api.cludo.com/api/rankings/1689348"
    -X DELETE
    -u 4545589:3ede38fdc0824e18bb3adb9a21fbbdc8

DELETE https://api.cludo.com/api/rankings/<Page ranking ID>

URL parameters

Parameter	Type	Description
Page ranking ID	int	The ID of the specific page ranking

Quicklinks

Quicklinks are useful if you want to redirect your visitors to a specific url when they search for a pre-defined term.

Data structures

Quicklink

{
    "id": 5807805,
    "websiteId": 7578030,
    "url": "https://www.cludo.com/contact/",
    "terms": []
}

Key	Type	Description
id	int	The ID of the quicklink
websiteId	int	The ID of the engine the quicklink belongs to
url	string	The URL to redirect to
terms	array	An array of terms

Term

{
    "name": "contact"
}

Key	Type	Description
name	string	The term that should trigger the redirect

Get quicklink

Get a specific quicklink.

Request

$ curl "https://api.cludo.com/api/quicklinks/5807805"
    -u 4545589:3ede38fdc0824e18bb3adb9a21fbbdc8

GET https://api.cludo.com/api/quicklinks/<Quicklink ID>

URL parameters

Parameter	Type	Description
Quicklink ID	int	The ID of the specific quicklink

Response

Will return a single quicklink. See data structures.

Get quicklinks by engine

Get all quicklinks for a specific engine.

Request

$ curl "https://api.cludo.com/api/engine/7578030/quicklinks"
    -u 4545589:3ede38fdc0824e18bb3adb9a21fbbdc8

GET https://api.cludo.com/api/engine/<Engine ID>/quicklinks

URL parameters

Parameter	Type	Description
Engine ID	int	The ID of the specific engine

Response

Will return an array of quicklinks. See data structures.

Get quicklinks by engine and term

Get all quicklinks for a specific engine and term.

Request

$ curl "https://api.cludo.com/api/engine/7578030/quicklinkterms?searchword=contact"
    -u 4545589:3ede38fdc0824e18bb3adb9a21fbbdc8

GET https://api.cludo.com/api/engine/<Engine ID>/quicklinkterms?searchword=<Term>

URL parameters

Parameter	Type	Description
Engine ID	int	The ID of the specific engine

Query parameters

Parameter	Type	Description
Term	string	The specific term.

Response

Will return an array of quicklinks. See data structures.

Create quicklink

Create a quicklink.

Request

$ curl "https://api.cludo.com/api/quicklinks"
    -X POST
    -u 4545589:3ede38fdc0824e18bb3adb9a21fbbdc8
    -H "Content-Type: application/json"
    -d '{
           "websiteId": 7578030,
           "url": "https://www.cludo.com/contact/",
           "terms": [
               {
                   "name": "contact"
               }
           ]
       }'

POST https://api.cludo.com/api/quicklinks

Body

A single quicklink. See data structures.

Response

Will return the created quicklink. See data structures.

Update quicklink

Update a specific quicklink.

Request

$ curl "https://api.cludo.com/api/quicklinks/5807805"
    -X PUT
    -u 4545589:3ede38fdc0824e18bb3adb9a21fbbdc8
    -H "Content-Type: application/json"
    -d '{
           "websiteId": 7578030,
           "url": "https://www.cludo.com/contact/",
           "terms": [
               {
                   "name": "contact"
               }
           ]
       }'

$ curl "https://api.cludo.com/api/quicklinks"
    -X POST
    -u 4545589:3ede38fdc0824e18bb3adb9a21fbbdc8
    -H "Content-Type: application/json"
    -d '{
           "id": 5807805,
           "websiteId": 7578030,
           "url": "https://www.cludo.com/contact/",
           "terms": [
               {
                   "name": "contact"
               }
           ]
       }'

PUT https://api.cludo.com/api/quicklinks/<Quicklink ID>

POST https://api.cludo.com/api/quicklinks

URL parameters

Parameter	Type	Description
Quicklink ID	int	The ID of the specific quicklink

Body

A single quicklink. See data structures.

Response

Will return the updated quicklink. See data structures.

Delete quicklink

Delete a quicklink.

Request

$ curl "https://api.cludo.com/api/quicklinks/5807805"
    -X DELETE
    -u 4545589:3ede38fdc0824e18bb3adb9a21fbbdc8

DELETE https://api.cludo.com/api/quicklinks/<Quicklink ID>

URL parameters

Parameter	Type	Description
Quicklink ID	int	The ID of the specific quicklink

Synonyms

Synonyms are useful if you have the content your visitors are looking for, but they're searching for other words for the same thing.

Data structures

Synonyms Group

{
    "groupId": 1,
    "words": ["work", "job", "career"],
    "language": "en"
}

Key	Type	Description
groupId	int	The ID of the synonyms group
words	array	Collection of words which are synonyms
language	string	A two-letter ISO language code

Get all synonyms by language

Get all synonyms groups for a specific language.

Request

$ curl "https://api.cludo.com/api/synonymsgroup/en"
    -u 4545589:3ede38fdc0824e18bb3adb9a21fbbdc8

GET https://api.cludo.com/api/synonymsgroup/<Language>

URL parameters

Parameter	Type	Description
Language	string	A two-letter ISO language code

Response

Will return an array of synonyms groups. See data structures.

Get single synonyms group

Get a specific synonyms group.

Request

$ curl "https://api.cludo.com/api/synonymsgroup/9457415"
    -u 4545589:3ede38fdc0824e18bb3adb9a21fbbdc8

GET https://api.cludo.com/api/synonymsgroup/<Synonym Group ID>

URL parameters

Parameter	Type	Description
Synonym Group ID	int	The ID of the specific synonyms group

Response

Will return a single synonyms group. See data structures.

Create synonyms group

Create a synonyms group.

Request

$ curl "https://api.cludo.com/api/synonymsgroup"
    -X POST
    -u 4545589:3ede38fdc0824e18bb3adb9a21fbbdc8
    -H "Content-Type: application/json"
    -d '{
            "words": ["work", "job", "career"],
            "language": "en"
        }'

POST https://api.cludo.com/api/synonymsgroup

Body

A single synonyms group composed of multiple words which are synonyms. See data structures.

Response

Will return the created synonyms group. See data structures.

Update synonyms group

Update a specific synonyms group.

Request

$ curl "https://api.cludo.com/api/synonymsgroup"
    -X PUT
    -u 4545589:3ede38fdc0824e18bb3adb9a21fbbdc8
    -H "Content-Type: application/json"
    -d '{
            "groupId": 1,
            "words": ["work", "job", "opportunity"],
            "language": "en"
        }'

PUT https://api.cludo.com/api/synonyms/<Synonyms Group ID>

URL parameters

Parameter	Type	Description
Synonyms Group ID	int	The ID of the specific synonyms group

Body

A single synonyms group. See data structures.

Response

Will return the updated synonyms group. See data structures.

Delete synonym

Delete one or more synonyms groups.

Request

$ curl "https://api.cludo.com/api/synonymsgroup?groupIds=1&groupIds=2&groupIds=3"
    -X DELETE
    -u 4545589:3ede38fdc0824e18bb3adb9a21fbbdc8

DELETE https://api.cludo.com/api/synonymsgroup?groupIds=<Synonym Group ID>&groupIds=<Synonym Group ID>

Query parameters

Parameter	Type	Description
Synonym Group ID	int	The ID of the specific synonyms group

Banners

Banners allow you to display custom content when users search for specific terms. They are excellent for promoting current information, upcoming events, promotions, or highlighting general information such as opening hours. Banners can also be used to suggest external links to users that would not otherwise appear in the search results.

Data structures

Banner

{
    "name": "My Banner",
    "htmlcode": "<p id=\"my_id\">some example content</p>... other html content",
    "bannerterms": [
        { "name": "trigger_term1" },
        { "name": "trigger_term2" }
    ],
    "websiteid": some_engine_identifier,
    "isDisabled": false,
    "from": "2024-11-14T22:00:00.000Z",
    "to": "2024-11-16T22:00:00.000Z"
}

Key	Type	Description
name	string	The name of the banner.
htmlcode	string	The HTML content to display in the banner.
bannerterms	array	A collection of terms/triggers that will display the banner.
websiteid	int	The ID of the engine where the banner is displayed.
isDisabled	bool	A flag determining if the banner should be shown or not.
from	string	The start date and time (in ISO 8601 format) from when the banner should be active.
to	string	The end date and time (in ISO 8601 format) until when the banner should be active.

Get all banners by engine

Retrieves all banners for a specific engine.

Request

$ curl "https://api-eu1.cludo.com/api/banners/site/13691"
    -u 4545589:3ede38fdc0824e18bb3adb9a21fbbdc8

GET https://api-eu1.cludo.com/api/banners/site/<Engine ID>

URL parameters

Parameter	Type	Description
Engine ID	int	The ID of the specific engine for which to retrieve banners.

Response

Will return an array of banners. See data structures.

Get single banner

Retrieves a specific banner by its ID.

Request

$ curl "https://api-eu1.cludo.com/api/banners/25048"
    -u 4545589:3ede38fdc0824e18bb3adb9a21fbbdc8

GET https://api-eu1.cludo.com/api/banners/<Banner ID>

URL parameters

Parameter	Type	Description
Banner ID	int	The ID of the specific banner

Response

Will return a single banner. See data structures.

Create banner

Creates a new banner.

Request

$ curl "https://api-eu1.cludo.com/api/banners"
    -X POST
    -u 4545589:3ede38fdc0824e18bb3adb9a21fbbdc8
    -H "Content-Type: application/json"
    -d '{
            "name": "Example Banner",
            "htmlcode": "<p id=\"my_p\">my content</p>",
            "bannerterms": [{"name": "trigger_term1"}, {"name": "trigger_term2"}],
            "isDisabled": false,
            "websiteid": 1234,
            "from": "2024-11-14T22:00:00.000Z",
            "to": "2024-11-16T22:00:00.000Z"
        }'

POST https://api-eu1.cludo.com/api/banners

Body

A single synonyms group composed of multiple words which are synonyms. See data structures.

Response

A banner object containing the details of the new banner. See data structures.

Update banner

Updates a specific banner by its ID.

Request

$ curl "https://api-eu1.cludo.com/api/banners/1234"
    -X PUT
    -u 4545589:3ede38fdc0824e18bb3adb9a21fbbdc8
    -H "Content-Type: application/json"
    -d '{
            "id": 1234,
            "name": "Updated example Banner",
            "htmlcode": "<p id=\"my_p\">updated content</p>",
            "bannerterms": [
                { "name": "trigger_term1" },
                { "name": "trigger_term2" },
                { "name": "new_trigger_term3" }
            ],
            "isDisabled": false,
            "websiteid": 23454,
            "from": "2024-11-14T22:00:00.000Z",
            "to": "2024-11-16T22:00:00.000Z"
        }'

PUT https://api-eu1.cludo.com/api/banners/<Banner ID>

URL parameters

Parameter	Type	Description
Banner ID	int	The ID of the specific banner to update

Body

A banner object with the updated details. See data structures.

Response

Will return the updated banner object. See data structures.

Delete banner

Delete s banner by its ID.

Request

$ curl "https://api.cludo.com/api/banners/1234"
    -X DELETE
    -u 4545589:3ede38fdc0824e18bb3adb9a21fbbdc8

DELETE https://api.cludo.com/api/banner/<Banner ID>

Query parameters

Parameter	Type	Description
Banner ID	int	The ID of the specific banner to be deleted

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:

pushurls
push
delete

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 "https://api.cludo.com/api/v3/4545589/content/2368899/pushurls"
    -X POST
    -u 4545589:3ede38fdc0824e18bb3adb9a21fbbdc8
    -H "Content-Type: application/json"
    -d '[
            "https://www.cludo.com/en/products/",
            "https://www.cludo.com/en/features/"
        ]'

POST https://api.cludo.com/api/v3/<Customer ID>/content/<Crawler ID>/pushurls

Parameter	Description
Customer ID	Your ID
Crawler ID	The ID of the specific crawler you'd like to crawl the given URLs

HTTP body

The pushurls takes a collection of pages.

If it’s one page, the request body would look like this:

[
  "https://example.com/page/to/index"
]

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}:{API_Key} \

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",
    "Type": "PageContent",
    "CustomField1":222,
    "CustomField2":"News"
  },
  {
    "Title":"My title",
    "Description":"Description",
    "Type": "PageContent",
    "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.

Body parameters

Key	Type	Description
Title	string	The title of a search result
Description	string	The description of a search result
Type	string	Must be PageContent for pages and FileContent for files
CustomField	string / int	Custom field, can be set to anything

Deleting data

If a page or file is removed from your website, you don't want for it to appear in your search results anymore, as it will lead to dead links. It will be removed upon a recrawl regardless, but if it can't wait, you can use this endpoint to manually delete it.

HTTP request

The command below deletes search results:

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

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

Parameter	Description
CustomerId	Your customer id
CrawlerId	The id of the crawler to delete the results from

HTTP body

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

[
    {
        "https://www.cludo.com/some-page/": "PageContent"
    },
    {
        "some-string": "PageContent"
    },
    {
        "https://www.cludo.com/some-file.pdf": "FileContent"
    }
]

The body consists of an array of key/value pairs. The key is the ID of the resource and the value is the type of the resource.

Data	Type	Valid values
Resource ID	String	Any. The ID of page and file resources will be their URL by default.
Resource Type	String	FileContent PageContent

Need help?

Introduction

Regions

Samples

Authentication

Site key authentication

Header

Parameters

Basic authentication

Header

Parameters

Searching

Full searches

HTTP request

Query parameters

Query

Advanced queries

Filtering

Syntax

Values

Range

Date

Ranking

Custom sort

Value boost

Grouping

Rendering

Related Searches

HTTP Response

JsonObject response

JsonHtml response

Table of request properties

Table of response properties

Common properties

JsonObject response

JsonHtml response

AutoComplete searches

HTTP request

HTTP GET request

HTTP POST request

Query parameters

HTTP response

Not specified response

JsonHtml response

JsonObject response

Query string syntax

Operators

Grouping

Sentences

Fields

Wildcards

Fuzzyness

Ranges

Boosting

Tracking

Queries

Request

URL parameters

Body/Query parameters

Clicks

Request

URL parameters

Body/Query parameters

IP addresses

Header

Parameters

Statistics

Search counts per day

Request

URL parameters

Search count totals

Request

URL parameters

Click counts

Request

URL parameters

Tools

Page rankings

Data structures

Ranking group