IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

› ›

Search API

edit

Search API

edit

Submit a search and receive a set of results with meta data.

GET /api/as/v1/engines/<engine_name>/search

POST /api/as/v1/engines/<engine_name>/search

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, OR, and NOT.

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 to 1000.

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 to 100.

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)

See Search API precision (beta).

boosts (optional)

See Search API boosts.

search_fields (optional)

See Search API search fields.

result_fields (optional)

See Search API result fields.

analytics.tags (optional)

See Search API analytics tags.

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 through 9999 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

edit

Request:

curl -X POST 'https://[instance id].ent-search.[region].[provider].cloud.es.io:443/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 'https://[instance id].ent-search.[region].[provider].cloud.es.io:443/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 'https://[instance id].ent-search.[region].[provider].cloud.es.io:443/api/as/v1/engines/national-parks-demo/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
  "query": "wyoming AND montana OR california NOT washington"
}'

Common issues

edit

When 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 to 1 and less than or equal to 1000.
The value of page.current is not greater than or equal to 1 and less than or equal to 100.
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

« Schema API Search API boosts »