API Referenceedit

App Search provides you with a variety of endpoints to craft intuitive, relevant and useful search experiences.

However you choose to wield these APIs, it will be valuable to first explore...

Using the API examples

Enterprise Search API references provide curl examples for many API operations. To run these examples, copy and paste them into your terminal.

Substitute all placeholders, such as access tokens, with values specific to your deployment. Some API references use shell variables— define those variables in your shell to substitute values without modifying the examples.

Unfortunately, you cannot use Enterprise Search APIs with the Kibana Console, which only interfaces with the Elasticsearch REST API.

Schema Design, Field Type Overviewedit

When it comes to schema design, remember four key points:

  1. Always index new fields as the same type as existing documents.

    • eg. An existing date field should not receive geolocation data.
  2. Nested objects are not supported. You must flatten them.
  3. Arrays are supported.
  4. Fields cannot be deleted once they have been created.

App Search fields can be one of four different types:

text fieldsedit

Text fields are at the heart of search.

They enable deeply analyzed full text search.

This is the default type for all new fields.

Any group of characters or text that you want to search over should be text.

Text can be in many languages, with intelligence respective of the configured Engine language.

eg. A description of an object, the name of a product, the content of a review.

number fieldsedit

A single-precision, floating-point value (32 bits): 3.14 or 42.

Number fields enable fine grained sorting, filtering, faceting, and boosting.

eg. A price, a review score, the number of visitors, or a size.

(If you need to represent a larger number, consider a text field as a workaround.)

date fieldsedit

Dates must be in ISO 8601 format, eg: "2013-02-27T18:09:19".

eg. A product release or publish date, birth date, an air date.

geolocation fieldsedit

Geolocation fields are latitude-longitude pairs, representing locations.

Examples: A store where a product is located; the location of a venue.

Specify a geolocation using any of the following formats:

"location": "41.12,-71.34" 

"location": "drm3btev3e86" 

"location": [ -71.34, 41.12 ] 

"location" : "POINT (-71.34 41.12)" 

Geo-point expressed as a string with the format: "lat,lon"

Geo-point expressed as a geohash

Geo-point expressed as an array with the format: [ lon, lat]

Geo-point expressed as a well-known text POINT with the format: "POINT(lon lat)"

For more details, see Geo-point field type in the Elasticsearch documentation. However, be aware Enterprise Search supports fewer formats than Elasticsearch. Enterprise Search supports only the formats shown above.

Supported Features, By Field Typeedit

Each field type has its own feature compatibility.

Queriesedit

Type Search Queries Query Suggestions Result Fields Search Fields

text

Yes

Yes

Yes

Yes

number

No

No

No

No

date

No

No

No

No

geolocation

No

No

No

No

Boostsedit

Type Value Boosts Functional Boosts Proximity Boosts Recency Boosts

text

Yes

No

No

No

number

Yes

Yes

Yes

No

date

Yes

No

No

Yes

geolocation

Yes

No

Yes

No

Filters, Facets, Grouping, Sortingedit

Type Value Facet Range Facet Value Filter Range Filter Geo Filter Grouping Sorting

text

Yes

No

Yes

No

No

Yes

Yes

number

Yes

Yes

Yes

Yes

No

Yes

Yes

date

Yes

Yes

Yes

Yes

No

Yes

Yes

geolocation

No

Yes

No

No

Yes

No

Yes

Parameter Encodingedit

All App Search endpoints accept parameters as a JSON-encoded request body.

This is the recommended method and the one you will see in all of our examples.

However, you can also submit query parameters using form encoding.

For example:

Example - JSON request body

curl -X GET '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/national-parks-demo/documents/list' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "page": {
    "current": 2,
    "size": 15
  }
}'

... compared with:

Example - Rails-style query parameters

curl -X GET '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/national-parks-demo/documents/list?page[size]=15&page[current]=2' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'

Both options will return the same response, which is the second page of results with 15 pages per result:

Example - Same response!

{
  "meta": {
    "page": {
      "current": 2,
      "total_pages": 3,
      "total_results": 41,
      "size": 15
    }
  },
  "results": [
    {
       "nps_link": {
         "raw": "https://www.nps.gov/wrst/index.htm"
       },
       "title": {
         "raw": "Wrangell–St. Elias"
       },
       "date_established": {
         "raw": "1980-12-02T06:00:00+00:00"
       },
       "world_heritage_site": {
         "raw": "true"
       },
       "states": {
         "raw": [
           "Alaska"
         ]
       },
       "description": {
         "raw": "An over 8 million acres (32,375 km2) plot of mountainous country—the largest National Park in the system—protects the convergence of the Alaska, Chugach, and Wrangell-Saint Elias Ranges, which include many of the continent's tallest mountains and volcanoes, including the 18,008-foot Mount Saint Elias. More than a quarter of the park is covered with glaciers, including the tidewater Hubbard Glacier, piedmont Malaspina Glacier, and valley Nabesna Glacier."
       },
       "visitors": {
         "raw": 79047
       },
       "id": {
         "raw": "park_wrangell–st.-elias"
       },
       "location": {
         "raw": "61,-142"
       },
       "square_km": {
         "raw": 33682.6
       },
       "acres": {
         "raw": 8323146.48
       },
       "_meta": {
         "score": 0.00437395
       }
    },
    # ... Truncated!
  ]
}

Query Syntaxedit

When performing queries using the Search API, you may apply select Lucene Query Syntax functions.

The supported functions are: double quoted strings, + and -, AND, and NOT.

OR logic is not supported, due to a known issue. Refer to Known issues for details and a workaround.

Example - Performing a single query search using Lucene Query Syntax.

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 OR california NOT washington"
}'

Compression, gzipedit

The API supports gzip.

Your requests to App Search can contain an Accept-Encoding header.

Use the header to notify the API that you are capable of accepting and unpacking responses that are compressed via gzip.

curl -X POST '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/national-parks-demo/search' \
-H 'Content-Type: application/json' \
-H 'Accept-Encoding: gzip' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
  "query": "everglade"
}'

Error Handlingedit

There are three types of errors that you might run into when creating API requests:

Invalid Keysedit

Your choice of Key will depend on the endpoint you choose to access:

Key Name Key Prefix Endpoint

Public Search Key

public-

Search endpoint only.

Private API Key

private-

All endpoints except Credentials. It is recommended that you use the Public Search Key when using the Search endpoint.

Private Admin Key

admin-

Credentials endpoint only.

If you use the incorrect key or format the key in an incorrect way, then you will receive a 400 error akin to:

{
  "error": "Invalid authentication token."
}

Decoding Error, Malformed Requestsedit

If you happen to make a mistake with your formatting, you will receive a 400 error:

{
  "errors": [
    "There was a decoding error. Please ensure your request is valid."
  ]
}

To address this, ensure that your any JSON objects or URL parameters are formatted in the correct manner.

Endpoint Specific Errorsedit

Each API Reference will show you how to structure your requests.

If you happen to make a mistake, there are a variety of helpful errors that will inform you upon what to fix.

Despite receiving a status code of 200, you will not succeed in making your request.

Look for the Errors section at the end of each endpoint.

Errors might look like this:

{
  "errors": [
    "Missing required parameter: filters[date][from]"
  ]
}
{
  "errors": [
    "curation must include either promoted or hidden"
  ]
}

The following sections have moved:

LimitsRequest body, Response body