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

« Source engines API Web crawler API reference »

› ›

Synonyms API

edit

Synonyms API

edit

Checkout the Synonyms guide for deeper concepts.

Search API precision has no effect in queries that contain synonyms.

Create synonym sets.

Authentication

edit

For authentication, the Synonyms endpoint requires...

The name of your Engine: [ENGINE]
A Private API Key: [PRIVATE_API_KEY]

curl -X GET '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/[ENGINE]/synonyms' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer [PRIVATE_API_KEY]'

List Synonyms

edit

List All Synonyms

edit

Retrieves synonym sets for an Engine.

GET <ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/{ENGINE_NAME}/synonyms

page (optional): A JSON object containing current and size, where current is the current page number and size is the page size. The maximum for size is 25, and be will truncated if a larger size is requested. The default is the first page of synonym sets with pagination at 25.

Example - A GET request for all synonyms, paginated. Returns the 2nd page of results, with 20 results per page.

curl -X GET '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/national-parks-demo/synonyms' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'

Example Response

{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 3,
      "size": 25
    }
  },
  "results": [
    {
      "id": "syn-5b11ac66c9f9292013220ad3",
      "synonyms": [
        "park",
        "trail"
      ]
    },
    {
      "id": "syn-5b11ac72c9f9296b35220ac9",
      "synonyms": [
        "protected",
        "heritage"
      ]
    },
    {
      "id": "syn-5b11ac66c9f9292013220ad3",
      "synonyms": [
        "hectares",
        "acres"
      ]
    }
  ]
}

List All Synonyms with Pagination

edit

Example

curl -X GET '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/national-parks-demo/synonyms' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "page": {
    "size": 20,
    "current": 2
  }
}'

Example Response

{
  "meta": {
    "page": {
      "current": 2,
      "total_pages": 2,
      "total_results": 30,
      "size": 20
    }
  },
  "results": [
    ## Truncated!
  ]
}

Lists a Single Synonym

edit

Retrieves a synonym set by id.

GET <ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/{ENGINE_NAME}/synonyms/{SYNONYM_SET_ID}

Example

curl -X GET '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/national-parks-demo/synonyms/syn-5b11ac66c9f9292013220ad3' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'

Example Response

{
  "id": "syn-5b11ac66c9f9292013220ad3",
  "synonyms": [
    "park",
    "trail"
  ]
}

Create a Synonym Set

edit

Creates a new synonym set for an Engine.

You may only create one set of synonyms per API call.

The endpoint will not accept an array of arrays!

A synonym set can contain up to 32 words.

POST <ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/{ENGINE_NAME}/synonyms

synonyms (required): An array of strings containing at least two unique strings.

Example

curl -X POST '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/national-parks-demo/synonyms' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "synonyms": ["park", "trail"]
}'

Example Response

{
  "id": "syn-5b11ac72c9f9296b35220ac9",
  "synonyms": [
    "park",
    "trail"
  ]
}

Update a Synonym Set

edit

Updates an existing synonym set for an Engine by id.

You may only update one set of synonyms per API call.

The endpoint will not accept an array of arrays!

A synonym set can contain up to 32 words.

PUT <ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/{ENGINE_NAME}/synonyms/{SYNONYM_SET_ID}

synonyms (required): An array of strings containing at least two unique strings.

Example

curl -X PUT '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/national-parks-demo/synonyms/syn-5b11ac72c9f9296b35220ac9' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "synonyms": ["road", "trail"]
}'

Example Response

{
  "id": "syn-5b11ac72c9f9296b35220ac9",
  "synonyms": [
    "road",
    "trail"
  ]
}

Delete a Synonym

edit

Delete a synonym set by id.

DELETE <ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/{ENGINE_NAME}/synonyms/{SYNONYM_SET_ID}

Example

curl -X DELETE '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/national-parks-demo/synonyms/syn-5b11ac66c9f9292013220ad3'  \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'

Example Response

{
  "deleted": true
}

Errors

edit

The endpoint will return an error if:

The API Key does not have write permissions for the requested Engine.
The requested synonym set does not exist.
The synonym object is not well formed.
The request tried to create multiple synonym sets.

What’s Next?

edit

Configuring Synonyms is a useful way to guide your users to the right content. It is most useful when you know the precise terms that they are searching for. For that, you should explore the Analytics and Clickthrough end-points, so that you are aware of your insightful capabilities. If you are looking to provide even more precise and curated results, venture to the Curations end-point.

« Source engines API Web crawler API reference »