Search

Use the Search API to perform searches.

Manage Search API keys

To submit a request to the Search API (either the /search or /suggest endpoint), an app must include a valid Search API key in an X-API-Key header in the HTTP request.

Tip
For a specific Site Search app, you can use a single Search API key for all search apps that use Search API calls, or use multiple keys, for example, one per search app. Using multiple keys lets you turn off searches for a specific specific app by revoking that app’s Search API key.

Create a Search API key

To create a Search API key
  1. In the Site Search menu, click Search APIs.

  2. Click Generate a New Key to generate a Search API key.

    Your Search API key is listed. Click Download API key to download a search-api-key.json file that contains the key. Or write the key down or copy it somewhere. It won’t be shown again.

  3. Under Search for results, Site Search displays an example of a curl command with the GET request to search.

    To copy the sample curl command, hover over it and click Copy.

Enter or update a key’s comment (description)

To enter or update a key’s comment
  1. In the Site Search menu, click Search APIs.

  2. Click in the Comment field of the Search API key for which you want to enter or update the comment.

  3. Enter or update the comment.

Delete a key

To delete a key
  1. In the Site Search menu, click Search APIs.

  2. Hover over the Search API key you want to delete, and then click Delete Delete.

Search for documents

Use the Search API to search for documents.

Makeup of a search request

A search request has these parts:

HTTP request header

An HTTP request for the Search API must contain the X-API-Key header, a custom HTTP header to contain the Search API key.

REST verb

The REST verb for searches is GET.

Search API endpoint

The URI of the Search API endpoint is:

/api/v1/search

You append this URI to the end of the URL for the Site Search app (everything through pathname):

https://subdomain.lucidworks.cloud/pathname/api/v1/search

Request parameters

Specify which documents to search for, which information to return, and how the returned information is organized by including search-request parameters in the URL query string of a search request.

These are the available search-request parameters:

Parameter Description and example Type Default

q

Query term to search for

q=fusion server

string

*:*

(all documents)

f

Query filter or filters to apply

A query filter constrains the search results based on the value of a field (the value or values are in square brackets). To constrain based on multiple fields, include multiple f parameters.

f=department['computers']&f=category['accessories','cases']

Note
Surround the values in the square brackets with single or double quotation marks. For multiple values of one field (logical OR), repeat multiple f parameters (one for every term) and put an asterisk () at the end of each f value (for example, f=department['computers']&f=department['accessories']*). For more than one field, include multiple f parameters.

string, integer, or float

none

rpp

Results per page

rpp=10

integer

10

p

Page of results to show

p=6

Tip
You will need to do the math on pagination. If the API response reports 34 hits and there are 10 results per page, then requesting page 5 will return page 4, along with a warning message at the end of the response: `Requested 5 pages when only 4 are available.

integer

1

s

List of fields to sort by

s=+popularity&-price

Preface the field with + for ascending order or - for descending order. To sort by multiple fields, separate them with ampersands (&). In the example shown here, sorting is first by popularity (ascending) and then by price (descending)

string, multivalued

none

fi

List of fields to return

fi=id,department,description,price

If you don’t specify which fields to return, the Search API returns all fields. Use this to determine which fields are available, and for debugging.

comma-separated list

all fields

fa

List of fields to facet on

fa=department,category

comma-separated list

none

topics

List of topics (or single topic) to which to restrict the search

topics=press_releases,news

comma-separated list

none

Note
If a parameter value contains a reserved character, URL encode the character. You might also need to encode other characters. For example, a query parameter for fusion server would be q=fusion%20server or q=fusion+server.

Examples

These are examples of Search API requests and responses. Both requests and responses depend on what data you have indexed. Here, we indexed parts of the https:/doc.lucidworks.com website.

Also see Search API examples for Spellchecking and Did You Mean.

Return all fields for a single document

During development, it can be useful to view all fields that are available for a data source. This curl command omits the f parameter, so the Search API returns all fields. The parameter p is also omitted, so the first page of results is returned. Setting the parameter rpp to 1 causes (with the implied p=1) a single result to be returned. The search was for q=cloud, a term that was expected to be present.

Request

curl -H 'X-API-Key: YOUR_API_KEY' 'https://subdomain.lucidworks.cloud/pathname/api/v1/search?p=1&rpp=1&q=cloud'

Response

This is an example of the response. The response contains fields you expect from the data source and from field mapping, as well as ones that Fusion and Site Search use.

Notice:

  • The query: "query"

  • The number of results: "hits" : { "act" : [ "Long", 34 ]

  • Pagination: "page"

  • Specific results: "result"

  • Fields: "fields"

  • Messages: "messages" (none in this case)

{
  "query" : {
    "target" : "",
    "filters" : [ ],
    "type" : "any",
    "fields" : "",
    "view" : "",
    "collection" : "",
    "autoCorrected" : false,
    "facts" : { },
    "transientParameters" : [ "fa" ],
    "val" : "cloud",
    "rpp" : 1,
    "facets-enabled" : true,
    "max" : -1,
    "page" : 1,
    "facets" : "",
    "sorts" : [ ],
    "custom" : { },
    "other" : { },
    "default" : false
  },
  "hits" : {
    "act" : [ "Long", 34 ]
  },
  "page" : 1,
  "results" : [ {
    "result" : {
      "id" : "https://doc.lucidworks.com/lucidworks-cloud/index.html",
      "fields" : {
        "mimeType_s" : {
          "name" : "mimeType_s",
          "val" : [ "text/html" ]
        },
        "meta_tag_name_publisheddate" : {
          "name" : "meta_tag_name_publisheddate",
          "val" : [ "2018-05-15 23:59:07 +0000" ]
        },
        "_lw_parser_id_s" : {
          "name" : "_lw_parser_id_s",
          "val" : [ "c8644a3a-a2ba-4342-9d71-082e14cba3dd" ]
        },
        "_cloud_fields_ss" : {
          "name" : "_cloud_fields_ss",
          "val" : [ "domain", "file_extension", "file_name", "meta_tag_charset", "name", "meta_tag_name_viewport", "description", "url", "path_1", "meta_tag_name_publisheddate", "type", "meta_tag_name_description" ]
        },
        "description" : {
          "name" : "description",
          "val" : [ "Lucidworks <em>Cloud</em> apps provide many of the powerful features of Fusion with the simplicity of SaaS, and without the overhead of on-premises deployment. Lucidworks <em>Cloud</em> apps share the same administration interface and offer secure data ingestion." ]
        },
        "_lw_data_source_collection_s" : {
          "name" : "_lw_data_source_collection_s",
          "val" : [ "site-search-default" ]
        },
        "type" : {
          "name" : "type",
          "val" : [ "text/html" ]
        },
        "meta_tag_name_description" : {
          "name" : "meta_tag_name_description",
          "val" : [ "Lucidworks Cloud apps provide many of the powerful features of Fusion with the simplicity of SaaS, and without the overhead of on-premises deployment. Lucidworks Cloud apps share the same administration interface and offer secure data ingestion." ]
        },
        "_lw_extracted_page_type" : {
          "name" : "_lw_extracted_page_type",
          "val" : [ "article" ]
        },
        "_lw_parser_charset_s" : {
          "name" : "_lw_parser_charset_s",
          "val" : [ "UTF-8" ]
        },
        "parent_s" : {
          "name" : "parent_s",
          "val" : [ "https://doc.lucidworks.com/lucidworks-cloud/index.html" ]
        },
        "_lw_data_source_type_s" : {
          "name" : "_lw_data_source_type_s",
          "val" : [ "lucid.web/web" ]
        },
        "_cloud_data_source_" : {
          "name" : "_cloud_data_source_",
          "val" : [ "_site-search_web_" ]
        },
        "_lw_data_source_s" : {
          "name" : "_lw_data_source_s",
          "val" : [ "_site-search_web_" ]
        },
        "_lw_extracted_images" : {
          "name" : "_lw_extracted_images",
          "val" : [ "https://doc.lucidworks.com/assets/images/cloud-apps/example-front-end.png" ]
        },
        "_lw_parser_type_s" : {
          "name" : "_lw_parser_type_s",
          "val" : [ "html" ]
        },
        "file_name" : {
          "name" : "file_name",
          "val" : [ "index.html" ]
        },
        "responseHeaders_ss" : {
          "name" : "responseHeaders_ss",
          "val" : [ "Content-Type: text/html", "Content-Length: 33424", "Connection: keep-alive", "Date: Thu, 17 May 2018 15:43:01 GMT", "Last-Modified: Wed, 16 May 2018 00:25:38 GMT", "ETag: \"f83f2d01dd890ea2b4d4ac85269b5df0\"", "Server: AmazonS3", "Age: 1118", "X-Cache: Hit from cloudfront", "Via: 1.1 baba25718271048500893eed324db5bb.cloudfront.net (CloudFront)", "X-Amz-Cf-Id: 96djfi70pufn_QZhXaKr0vJRZDjITbZH_O4AuK2uXMD6d_d4dsZV2w==" ]
        },
        "meta_tag_name_viewport" : {
          "name" : "meta_tag_name_viewport",
          "val" : [ "width=device-width, initial-scale=1" ]
        },
        "_lw_batch_id_s" : {
          "name" : "_lw_batch_id_s",
          "val" : [ "52c077a6c4c9407cbaa279b5f0e9812f" ]
        },
        "_lw_extracted_faviconurl" : {
          "name" : "_lw_extracted_faviconurl",
          "val" : [ "https://lucidworks.com/wp-content/themes/lucidworks/favicon.ico" ]
        },
        "_lw_extracted_description" : {
          "name" : "_lw_extracted_description",
          "val" : [ "Lucidworks Cloud apps provide many of the powerful features of Fusion with the simplicity of SaaS, and without the overhead of on-premises deployment. Lucidworks Cloud apps share the same administration interface and offer secure data ingestion." ]
        },
        "url" : {
          "name" : "url",
          "val" : [ "https://doc.lucidworks.com/lucidworks-cloud/index.html" ]
        },
        "_lw_parser_absolute_resource_name_s" : {
          "name" : "_lw_parser_absolute_resource_name_s",
          "val" : [ "https://doc.lucidworks.com/lucidworks-cloud/index.html" ]
        },
        "meta_tag_charset" : {
          "name" : "meta_tag_charset",
          "val" : [ "UTF-8" ]
        },
        "_lw_data_source_pipeline_s" : {
          "name" : "_lw_data_source_pipeline_s",
          "val" : [ "_site-search_web_" ]
        },
        "domain" : {
          "name" : "domain",
          "val" : [ "doc.lucidworks.com" ]
        },
        "_lw_parser_resource_name_s" : {
          "name" : "_lw_parser_resource_name_s",
          "val" : [ "https://doc.lucidworks.com/lucidworks-cloud/index.html" ]
        },
        "name" : {
          "name" : "name",
          "val" : [ "Lucidworks <em>Cloud</em>" ]
        },
        "file_extension" : {
          "name" : "file_extension",
          "val" : [ "html" ]
        },
        "_lw_parser_diagnostic_id_s" : {
          "name" : "_lw_parser_diagnostic_id_s",
          "val" : [ "e3d93635-7023-4553-abca-2cdf691ad3fa" ]
        },
        "_lw_parser_content_type_s" : {
          "name" : "_lw_parser_content_type_s",
          "val" : [ "text/html" ]
        },
        "path_1" : {
          "name" : "path_1",
          "val" : [ "lucidworks-cloud" ]
        },
        "id" : {
          "name" : "id",
          "val" : [ "https://doc.lucidworks.com/lucidworks-cloud/index.html" ]
        },
        "lastModified_dt" : {
          "name" : "lastModified_dt",
          "val" : [ "2018-05-16T00:25:38.000Z" ]
        },
        "_cloud_data_source_last_recrawl" : {
          "name" : "_cloud_data_source_last_recrawl",
          "val" : [ {
            "act" : [ "Long", 1526940261945 ]
          } ]
        },
        "_lw_extracted_readingtime" : {
          "name" : "_lw_extracted_readingtime",
          "val" : [ {
            "act" : [ "Long", 1 ]
          } ]
        },
        "fetchedDate_dt" : {
          "name" : "fetchedDate_dt",
          "val" : [ "2018-05-21T22:04:23.000Z" ]
        },
        "_lw_parser_parsing_depth_i" : {
          "name" : "_lw_parser_parsing_depth_i",
          "val" : [ 1 ]
        },
        "url_str" : {
          "name" : "url_str",
          "val" : [ "https://doc.lucidworks.com/lucidworks-cloud/index.html" ]
        },
        "_lw_extracted_page_type_str" : {
          "name" : "_lw_extracted_page_type_str",
          "val" : [ "article" ]
        },
        "file_name_str" : {
          "name" : "file_name_str",
          "val" : [ "index.html" ]
        },
        "file_extension_str" : {
          "name" : "file_extension_str",
          "val" : [ "html" ]
        },
        "name_str" : {
          "name" : "name_str",
          "val" : [ "Lucidworks Cloud" ]
        },
        "meta_tag_name_description_str" : {
          "name" : "meta_tag_name_description_str",
          "val" : [ "Lucidworks Cloud apps provide many of the powerful features of Fusion with the simplicity of SaaS, and without the overhead of on-premises deployment. Lucidworks Cloud apps share the same administration interface and offer secure data ingestion." ]
        },
        "meta_tag_name_publisheddate_str" : {
          "name" : "meta_tag_name_publisheddate_str",
          "val" : [ "2018-05-15 23:59:07 +0000" ]
        },
        "path_1_str" : {
          "name" : "path_1_str",
          "val" : [ "lucidworks-cloud" ]
        },
        "meta_tag_name_viewport_str" : {
          "name" : "meta_tag_name_viewport_str",
          "val" : [ "width=device-width, initial-scale=1" ]
        },
        "_lw_extracted_images_str" : {
          "name" : "_lw_extracted_images_str",
          "val" : [ "https://doc.lucidworks.com/assets/images/cloud-apps/example-front-end.png" ]
        },
        "domain_str" : {
          "name" : "domain_str",
          "val" : [ "doc.lucidworks.com" ]
        },
        "type_str" : {
          "name" : "type_str",
          "val" : [ "text/html" ]
        },
        "_lw_extracted_faviconurl_str" : {
          "name" : "_lw_extracted_faviconurl_str",
          "val" : [ "https://lucidworks.com/wp-content/themes/lucidworks/favicon.ico" ]
        },
        "_lw_extracted_description_str" : {
          "name" : "_lw_extracted_description_str",
          "val" : [ "Lucidworks Cloud apps provide many of the powerful features of Fusion with the simplicity of SaaS, and without the overhead of on-premises deployment. Lucidworks Cloud apps share the same administration interface and offer secure data ingestion." ]
        },
        "_version_" : {
          "name" : "_version_",
          "val" : [ {
            "act" : [ "Long", 1601112914343755776 ]
          } ]
        },
        "meta_tag_charset_str" : {
          "name" : "meta_tag_charset_str",
          "val" : [ "UTF-8" ]
        },
        "score" : {
          "name" : "score",
          "val" : [ 11.940009 ]
        }
      },
      "related" : [ ],
      "facts" : { },
      "score" : 11.940009
    }
  } ],
  "facets" : { },
  "facts" : {
    "tracking" : [ {
      "fusionQueryId" : "sBnqh2YT"
    } ]
  },
  "time" : 50,
  "messages" : [ ]

Return three fields for the second page of five documents

In this example, our goal is to obtain specific content for a search. We request page 2 (p=2) with 5 results per page (rpp=5), and to return the fields name, url, and description (fi=name,url,description). The query term is cloud (q=cloud).

Request

curl -H 'X-API-Key: YOUR_API_KEY' 'https://subdomain.lucidworks.cloud/pathname/api/v1/search?p=2&rpp=5&fi=name,url,description&q=cloud'

Notice that only requested fields are returned. Only one of these documents has a description field.

Response

{
  "query" : {
    "target" : "",
    "filters" : [ ],
    "type" : "any",
    "fields" : "name,url,description",
    "view" : "",
    "collection" : "",
    "autoCorrected" : false,
    "facts" : { },
    "transientParameters" : [ "fa" ],
    "val" : "cloud",
    "rpp" : 5,
    "facets-enabled" : true,
    "max" : -1,
    "page" : 2,
    "facets" : "",
    "sorts" : [ ],
    "custom" : { },
    "other" : { },
    "default" : false
  },
  "hits" : {
    "act" : [ "Long", 34 ]
  },
  "page" : 2,
  "results" : [ {
    "result" : {
      "id" : "",
      "fields" : {
        "url" : {
          "name" : "url",
          "val" : [ "https://doc.lucidworks.com/fusion/2.2/Connectors_and_Datasources_Reference/Dropbox-Connector-and-Datasource-Configuration.html" ]
        },
        "name" : {
          "name" : "name",
          "val" : [ "Dropbox Connector and Datasource Configuration" ]
        },
        "score" : {
          "name" : "score",
          "val" : [ 8.711846 ]
        }
      },
      "related" : [ ],
      "facts" : { },
      "score" : 8.711846
    }
  }, {
    "result" : {
      "id" : "",
      "fields" : {
        "url" : {
          "name" : "url",
          "val" : [ "https://doc.lucidworks.com/fusion/2.0/Connectors_and_Datasources_Reference/Dropbox-Connector-and-Datasource-Configuration.html" ]
        },
        "name" : {
          "name" : "name",
          "val" : [ "Dropbox Connector and Datasource Configuration" ]
        },
        "score" : {
          "name" : "score",
          "val" : [ 8.711846 ]
        }
      },
      "related" : [ ],
      "facts" : { },
      "score" : 8.711846
    }
  }, {
    "result" : {
      "id" : "",
      "fields" : {
        "url" : {
          "name" : "url",
          "val" : [ "https://doc.lucidworks.com/fusion/2.1/Connectors_and_Datasources_Reference/Dropbox-Connector-and-Datasource-Configuration.html" ]
        },
        "name" : {
          "name" : "name",
          "val" : [ "Dropbox Connector and Datasource Configuration" ]
        },
        "score" : {
          "name" : "score",
          "val" : [ 8.711846 ]
        }
      },
      "related" : [ ],
      "facts" : { },
      "score" : 8.711846
    }
  }, {
    "result" : {
      "id" : "",
      "fields" : {
        "url" : {
          "name" : "url",
          "val" : [ "https://doc.lucidworks.com/fusion/1.2/Connectors_and_Datasources_Reference/Dropbox-Connector-and-Datasource-Configuration.html" ]
        },
        "name" : {
          "name" : "name",
          "val" : [ "Dropbox Connector and Datasource Configuration" ]
        },
        "score" : {
          "name" : "score",
          "val" : [ 8.711846 ]
        }
      },
      "related" : [ ],
      "facts" : { },
      "score" : 8.711846
    }
  }, {
    "result" : {
      "id" : "",
      "fields" : {
        "description" : {
          "name" : "description",
          "val" : [ "object attributes: { •    : { •     display name: Operation     type: •     default value: '' •     description : The type of mapping to perform: move, copy, delete, add, set, or keep.     enum: { copy move delete set add keep     }     description : The name of the field to be mapped.     description : The name of the field to be mapped to." ]
        },
        "url" : {
          "name" : "url",
          "val" : [ "https://doc.lucidworks.com/fusion/3.0/Connectors_and_Datasources_Reference/Dropbox-Connector-and-Datasource-Configuration.html" ]
        },
        "name" : {
          "name" : "name",
          "val" : [ "Dropbox Connector and Datasource Configuration" ]
        },
        "score" : {
          "name" : "score",
          "val" : [ 8.338039 ]
        }
      },
      "related" : [ ],
      "facts" : { },
      "score" : 8.338039
    }
  } ],
  "facets" : { },
  "facts" : {
    "tracking" : [ {
      "fusionQueryId" : "8oH6xdZm"
    } ]
  },
  "time" : 47,
  "messages" : [ ]