Skip to main content

REST API

Indexing​

The quickest way to get familiar with the indexing API is our POSTMAN collection of endpoints — endpoints are the points where the API connects with Site Search 360. If you're new to POSTMAN, see the POSTMAN website — it's a platform for building and testing API requests.

Keep these principles in mind when working with the API:

  • A page's unique identifier is its URL. Each URL gets indexed once regardless of the data source — no source is more or less powerful than others, so the API can be used alongside Website Crawling, Sitemap Indexing, and other data sources.
  • Re-indexing an existing URL updates it instead of duplicating it. Any changes to the page's content are reflected in the search.
  • Changing a page's URL creates a new entry. If the content stays the same but the URL changes, the crawler treats the page as entirely new. Remove the old URL from the index to avoid duplicate content in the search results.

Pushing a URL to the Index​

Your API setup might look like this:

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

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

The /documents endpoint is responsible for pushing the URL to your search index. Our crawler checks and processes it according to various settings defined in your Control Panel (for instance, blacklisting/no-indexing rules, Data Points, Result Grouping, and Content Extraction), so some entries might be skipped, moved to certain result groups, etc.

Sending Page Content as JSON​

Alternatively, you can send the searchable content in JSON, which changes the setup as follows:

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

The /pageJSON endpoint needs a JSON body request. Our crawler isn't used for this. To make your page's content — and not just the URL/title or whatever else is defined directly in JSON — searchable, set appendPageContent to true in the request. This triggers our crawler to download and index the content of the page, combining it with what was defined in the request.

Content sent as JSON does not respect any rules configured in the Control Panel — for instance, blacklisting/no-indexing rules, Data Points, Result Grouping, and Content Extraction.

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

{
  "url": "https://test.com",
  "documentType": "HTML",
  "title": "My page title",
  "content": "This is a simple test page",
  "appendPageContent": false,
  "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,
  "keywords": ["keyword1", "keyword2", "keyword3"],
  "language": "english"
}

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

By default, documentType is HTML. It can be set to one of the following: HTML, PDF, XLS, DOC, PPT, ODP, ODS, ODT, TXT, YOUTUBE_VIDEO.

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

Indexing Multiple Pages at Once​

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

POST
https://api.sitesearch360.com/sites/pagesJson?token={API_KEY}
[{
  "url": "https://test.com",
  "documentType": "HTML",
  "title": "My page title",
  "content": "This is a simple test page",
  "appendPageContent": false,
  "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,
  "keywords": ["keyword1", "keyword2", "keyword3"],
  "language": "english"
},
...]

Removing Indexed Pages​

You can remove previously indexed pages by specifying a URL or URL pattern:

DELETE
https://api.sitesearch360.com/index/documents?url={URL}&token={API_KEY}

{URL} remains the absolute URL you want to remove.

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

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

Searching​

Your API setup for searching through indexed entries might look like this:

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}

Each parameter has its own meaning:

  • {SITE_ID} is your site ID.
  • {QUERY} is your search query.
  • {FILTER_OPTIONS} (optional) stands for filters found in the result set, which the API returns only if the element is set to true.
  • {FILTERS} (optional) is a JSON array of filters. For example, [{"fid#1": ["val1"]}, {"fid#2": {"min": 2, "max": 5}}]. The following structure must be used when setting up 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) is the name of the data point by which you want the search results sorted.
  • {ORDER} (optional) is the sorting order (ASC for ascending or DESC for descending).
  • {INCLUDE} (optional) corresponds to search snippets — if set to true, your search results will contain the content snippet; the default is false.
  • {HIGHLIGHT} (optional) stands for highlighted terms in your search results (used to signify complete matches between the query and the result) — query terms are highlighted if set to true; the default is false.
  • {CONTENT_GROUPS} (optional) is a JSON array corresponding to specific result groups you want to limit your search to, for instance: ["Group 1","Group 2"].
  • {OFFSET} (optional) is the number of results to skip from the beginning of your search results.
  • {LIMIT} (optional) is the number of results to return within a certain range, for instance [1,100]. The maximum is 100. If no limit is set, the default is 10 results.
  • {LOG} (optional) configures whether to log the query, and can be set to true or false (the default is true).

The search response has 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": []
}
  • suggests is a mapping of content groups to an array of retrieved search results (uncategorized results are listed under _).
  • query is your 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 all available filtering options.
  • activeFilterOptions is an array of all active/applied filter options.

Search results can be presented in any of the following types: HTML, YOUTUBE_VIDEO, PDF, XLS, DOC, PPT, ODP, ODS, ODT, TXT, custom.

To support custom HTML results ("type": "custom"), use the html property, which renders your search result.

Getting Query Suggestions (Autocomplete)​

To get query suggestions (autocomplete) and suggested results based on a query, use this API call:

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

Parameters in this setup are as follows:

  • {SITE_ID} is your site ID.
  • {QUERY} is your search query.
  • {LIMIT} (optional) is the number of results to return, within the range [1,2].
  • {GROUP_RESULTS} (optional) defines whether to combine search suggestions by content group (true by default).
  • {MAX_QUERY_SUGGESTIONS} (optional) defines the maximum number of query suggestions (autocomplete queries) to return. Note that these only show up if matching phrases for the given query have been searched multiple times before.

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

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

Monitoring and Reporting​

Checking Index Status​

To get a JSON file with the number of indexed pages, use:

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

Viewing Indexed Content​

To check which pages have been indexed, use this more detailed request:

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

The following query parameters filter the results:

  • {URL} (optional) is the string that should be part of the URL.
  • {CONTENT_TYPE} (optional) is the content type to filter by (e.g. "HTML" or "PDF").
  • {STATUS} (optional) is the Index Status to filter by (e.g. "200" for successfully indexed entries).
  • {OFFSET} (optional) is the number of results to skip from the beginning of your search results.
  • {LIMIT} (optional) is the number of results to return within a certain range, for instance [1,100].

Query Time Chart​

Use the following request to set up a time chart of queries:

GET
https://api.sitesearch360.com/sites/queries/timechart?start={START_TIMESTAMP}&end={END_TIMESTAMP}&token={API_KEY}
  • {START_TIMESTAMP} is the UNIX timestamp of the beginning of the period during which the desired URLs were indexed.
  • {END_TIMESTAMP} is the UNIX timestamp of the end of the period during which the desired URLs were indexed.

If you have questions about the API or any other topic, email us — we're happy to help.

API Key Management​

You can manage your API keys directly from your Site Search 360 account. This lets you generate, delete, and label API keys on your own.

To access API key management, log in to your Site Search 360 account, go to Account in the Control Panel, and open the API Access tab:

API Access tab

From there, you can:

  • Generate new API keys
  • Delete API keys that are no longer in use
  • Assign descriptive names to API keys for easier identification

Each API key can be managed independently, giving you flexibility in controlling and monitoring your API access.

We recommend creating separate keys for different projects or environments (e.g. staging and production) to simplify key management.