Search API
editSearch API
editSubmit a search and receive a set of results with meta data.
GET <ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/<engine_name>/search
POST <ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/<engine_name>/search
See the Authentication guide for information on how to authenticate to the search API.
Request body
edit-
query
(required) -
String or number to match.
The value
''
(empty string) matches all documents. (Note that API limits for documents returned applies. See Response body for more details.)The following Lucene query syntax is supported:
- double quoted strings
-
+
and-
-
AND
andNOT
OR
logic is not supported, due to a known issue. Refer to Known issues for details and a workaround.
-
page
(optional) -
Object to delimit the pagination parameters.
-
page.size
(optional) -
Number of results per page.
Must be greater than or equal to
1
and less than or equal to1000
.Defaults to
10
.See Paginate search results for implementation guidance.
-
page.current
(optional) -
Page number of results to return.
Must be greater than or equal to
1
and less than or equal to100
.Defaults to
1
.See Paginate search results for implementation guidance.
-
sort
(optional) -
See Search API sort.
-
group
(optional) -
See Search API group.
-
facets
(optional) -
See Search API facets.
-
filters
(optional) -
See Search API filters.
-
precision
(optional) -
boosts
(optional) -
See Search API boosts.
-
search_fields
(optional) -
result_fields
(optional) -
analytics.tags
(optional) -
record_analytics
(optional) -
If
true
, generates an analytics query event for the search request.Defaults to
true
.
Response body
edit-
results
-
Array of results matching the search.
Each result includes a document and meta data.
Array is empty when you paginate beyond 10,000 results.
See Paginate search results for implementation guidance.
-
meta
-
Object delimiting the results meta data.
-
meta.request_id
-
String ID representing the request. Guaranteed to be unique.
Use the ID with the API logs API to search for API requests.
-
meta.warnings
-
Array of warnings for the query.
Included with error responses and success responses, so inspect all responses for warnings.
-
meta.alerts
-
Array of alerts for your deployment.
Included with error responses and success responses, so inspect all responses for alerts.
-
meta.page
-
Object delimiting the pagination meta data.
-
meta.page.current
-
Number representing the current page of results.
-
meta.page.size
-
Number representing the results per page.
-
meta.page.total_pages
-
Number representing the total pages of results.
Value is
0
when you paginate beyond 10,000 results.See Paginate search results for implementation guidance.
-
meta.page.total_results
-
Number representing the total results across all pages.
The values
0
through9999
are exact counts.The value
10000
is a pseudo keyword representing greater than or equal to 10,000 results.See Display the total number of search results and Count the documents within an engine for implementation guidance.
Examples
editRequest:
curl -X POST '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/national-parks-demo/search' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \ -d '{ "query": "everglade" }'
Response:
{ "meta": { "warnings": [], "request_id": "2992570ab570b581ac6c457bddf68835", "page": { "total_pages": 1, "size": 10, "current": 1, "total_results": 3 }, "alerts": [] }, "results": [ { "world_heritage_site": { "raw": "true" }, "states": { "raw": [ "Florida" ] }, "location": { "raw": "25.32,-80.93" }, "nps_link": { "raw": "https://www.nps.gov/ever/index.htm" }, "acres": { "raw": 1508968.1 }, "date_established": { "raw": "1934-05-30T05:00:00+00:00" }, "title": { "raw": "Everglades" }, "visitors": { "raw": 930907 }, "square_km": { "raw": 6106.6 }, "description": { "raw": "The Everglades are the largest tropical wilderness in the United States. This mangrove and tropical rainforest ecosystem and marine estuary is home to 36 protected species, including the Florida panther, American crocodile, and West Indian manatee. Some areas have been drained and developed; restoration projects aim to restore the ecology." }, "_meta": { "score": 1396363.1 }, "id": { "raw": "park_everglades" } }, # ... More documents (truncated) ] }
Request for a specific page and page size (returns results six through ten):
curl -X GET '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/national-parks-demo/search' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \ -d '{ "query": "park", "page": { "size": 5, "current": 2 } }'
Request using Lucene query syntax within the query:
curl -X POST '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/national-parks-demo/search' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \ -d '{ "query": "wyoming AND montana NOT washington" }'
Common issues
editWhen constructing search API requests, some common issues are:
-
The
query
parameter is omitted. -
The value of
query
is not a string or a number. -
The value of
page
is not a JSON object. -
The value of
page.size
is not greater than or equal to1
and less than or equal to1000
. -
The value of
page.current
is not greater than or equal to1
and less than or equal to100
. - The query requests more than 10000 results, returning an empty response.
The following sections have moved:
Performing a single search query → Search API
Performing a multiple search query → Multi search API
Before you search → Request body
Page → Request body, Response body
Limit on results per query → Request body, Response body
Performing a single search query with Lucene query syntax → Examples