API

API methods

1. Indexing

For a head start, you can also download a POSTMAN collection of the endpoints (what is POSTMAN?).

The unique identifier for an indexed page is its URL. If you have a page with a given URL already indexed, it will be updated (and not duplicated).

POST
https://api.sitesearch360.com/sites/page?url={URL}&token={API_KEY}

Where {URL} is the absolute URL you want to index and {API_KEY} is your search project's API key that you can find under Account > General (if your plan includes API access).

The /page endpoint simply pushes the URL to your search index but our crawler still checks and processes it according to various settings defined in your Control Panel, such as blacklisted URL patterns, Data points, Result Grouping, Content Extraction etc.

You can also send the indexable data directly as a JSON.

POST
https://api.sitesearch360.com/sites/pageJson?token={API_KEY}

/pageJSON needs a JSON body request and our crawler isn't used. To make the PDF content searchable (and not just the title and anything else defined in your JSON), you can set appendPageContent to true in the request: this will trigger our crawler to download and index the PDF content and combine it with the other things defined in their request.

The body of the POST request must contain a JSON object of the following format:

{
  "url": "https://test.com",
  "title": "My page title",
  "content": "This is a simple test page",
  "contentGroup": "services",
  "imageUrl": "https://test.com/image.jpg",
  "dataPoints": [
    {
      "key": "Name of Data Point",
      "value": "Value of Data Point",
      "show": false
    },
    {
      "key": "Price",
      "value": "$3",
      "show": true
    }
  ],
  "filters": [
    {  /* Range filter */
       "key": "fid#1",
       "value": 2.5
    },
    {  /* Multiple choice filter */
       "key": "fid#2",
       "value": ["val1", "val2"]
    }
  ],
  "boost": 3,
  "language": "english"
}

The fields dataPoints, filters, language, and boost are optional.

NOTE: Filters have to be defined in the Control Panel and referenced with the generated Filter-ID.

You can also index up to 100 JSON entries at once.

POST
https://api.sitesearch360.com/sites/pagesJson?token={API_KEY}

The body of the POST request must contain a JSON array consisting of JSON objects in the following format:

[
    {
    "url": "https://test.com",
    "title": "My page title",
    "content": "This is a simple test page",
    "contentGroup": "services",
    "imageUrl": "https://test.com/image.jpg",
    "dataPoints": [
        {
        "key": "Name of Data Point",
        "value": "Value of Data Point",
        "show": false
        },
        {
        "key": "Price",
        "value": "$3",
        "show": true
        }
    ],
    "filters": [
        {  /* Range filter */
            "key": "fid#1",
            "value": 2.5
        },
        {  /* Multiple choice filter */
            "key": "fid#2",
            "value": ["val1", "val2"]
        }
    ],
    "boost": 3,
    "language": "english"
    },
    …
]
DELETE
https://api.sitesearch360.com/sites/page?url={URL}&token={API_KEY}

Where {URL} is the absolute URL you want to index.

DELETE
https://api.sitesearch360.com/sites/pages?urlPattern={URL_PATTERN}&token={API_KEY}

Where {URL_PATTERN} is a regular expression. All URLs matching the expression will be removed from the index.

2. Searching

GET
https://global.sitesearch360.com/sites?query={QUERY}&site={SITE_ID}&filterOptions={FILTER_OPTIONS}&filters={FILTERS}&sort={SORT}&sortOrder={ORDER}&offset={OFFSET}&limit={LIMIT}&includeContent={INCLUDE}&highlightQueryTerms={HIGHLIGHT}&includeContentGroups={CONTENT_GROUPS}&log={LOG}

Where

  • {SITE_ID} is your siteId.

  • {QUERY} is your search query.

  • {FILTER_OPTIONS} (optional) if set to true the API will return possible filters found in the result set.

  • {FILTERS} (optional) is a JSON array of filters. For example, [{"key": "fid#2", "values": [{"name": "val1"}]},{"key": "fid#1", "min": 2, "max": 5}]. Use the following structure when setting the filters in the ss360Config.results.filters property — [{"key": "fid#2", "name": "My Filter 2", "values": [{"name": "val1", "value": "val1"}]},{"key": "fid#1", "name": "My Filter 1", "min": 2, "max": 5}].

  • {SORT} (optional) The name of the data point by which you want to sort.

  • {ORDER} (optional) The sorting order, either ASC for ascending or DESC for descending.

  • {INCLUDE} (optional) if set to true, the results will contain the content snippet. By default it is false.

  • {HIGHLIGHT} (optional) if set to true, the query terms will be marked up with a . By default the parameter is false.

  • {CONTENT_GROUPS} (optional) if you only want to search within certain content groups, you can specify them in a JSON array here. For example, ["group1","group2"].

  • {OFFSET} (optional) is the number of results to skip from the beginning.

  • {LIMIT} (optional) is the number of results to return within range [1,100].

  • {LOG} (optional, true|false) whether to log the query or not (default is true).

The search response will have the following structure:

{
    "suggests": {
        "_": [
            {
                "name": "Search result title",
                "image": "https://mysite.com.com/sample.jpg",
                "link": "https://mysite.com/sample.html",
                "type": "HTML",
                "content": "This is the search snippet.",
                "dataPoints": [
                    {
                        "key": "Data Point Name",
                        "value": "Data Point Value",
                        "show": true
                    }
                ]
            },
            …
        ],
        "Products": [
            …
        ]
    },
    "query": "The search query",
    "totalResults": 360,
    "totalResultsPerContentGroup": {
        "_": 5,
        "Products": 355  
    },
    "sortingOptions": ["Date"],
    "sorting": "",
    "filterOptions": [],
    "activeFilterOptions": []
}

Where

  • suggests is a mapping of content groups to array retrieved search results. All uncategorized results are categorized as _.

  • query is the search query.

  • totalResults is the number of all available search results.

  • totalResultsPerContentGroup is a mapping of all available search results per content group.

  • sortingOptions is an array of all available sorting options.

  • sorting is the active/selected sorting option.

  • filterOptions is an array of available filtering options.

  • activeFilterOptions is an array of applied filter options.

NOTE: To support HTML custom results ("type": "custom") you need to use the html property to render the search result.

GET
https://global.sitesearch360.com/sites/suggest?query={QUERY}&limit={LIMIT}&site={SITE_ID}&groupResults={GROUP_RESULTS}

Where

  • {SITE_ID} is your siteId.

  • {QUERY} is your search query.

  • {LIMIT} (optional) is the number of results to return within range [1,20].

  • {GROUP_RESULTS} (optional) whether to group search suggestions by content group (default: true).

NOTE: To support HTML custom suggestions ("type": "custom") you need to use the suggestionHtml property to render the search suggestion.

Searches are logged automatically (if {LOG} is true). If you do not use the Site Search 360 Javascript but only the API, you can use this endpoint to also log abandoned search suggestions and selected suggestions.

3. MISC

POST
https://api.sitesearch360.com/sites/queries/log

Where you have to send the following parameters in the POST body:

  • query: The query to log.

  • action: The action, either "select" (search suggestion was selected) or "abandon" (search suggestions started but query not executed).

  • timeToAction (optional): The number of milliseconds before the user abandoned or selected the query.

  • site: Your site id.

  • apiKey: Your API key.

GET
https://api.sitesearch360.com/sites/indexStatus?token={API_KEY}

This endpoint returns a json with the number of indexed pages.

To check which pages have been indexed, you can use an even more elaborate request.

GET
https://api.sitesearch360.com/sites/indexedContent?url={URL}&contentType={CONTENT_TYPE}&status={STATUS}&offset={OFFSET}&limit={LIMIT}&token={API_KEY}

Where you can use the following query parameters to filter the results:

  • {URL} (optional): The string that should be part of the URL.

  • {CONTENT_TYPE} (optional): The content type you want to filter by, e.g. "HTML" or "PDF".

  • {STATUS} (optional): The index status you want to filter by, e.g. 200 for successfully indexed.

  • {OFFSET} (optional) is the number of results to skip from the beginning.

  • {LIMIT} (optional) is the number of results to return within range [1,100].

This endpoint allows you access to what you see in the index status table under Index.

GET
https://api.sitesearch360.com/sites/queries/frequent?start={START_TIMESTAMP}&end={END_TIMESTAMP}&token={API_KEY}

Where

  • {START_TIMESTAMP} is the UNIX timestamp of the begin of the period.

  • {END_TIMESTAMP} is the UNIX timestamp of the end of the period.

GET
https://api.sitesearch360.com/sites/queries/timechart?start={START_TIMESTAMP}&end={END_TIMESTAMP}&token={API_KEY}

Where