search mobile facets autocomplete spellcheck crawler rankings weights synonyms analytics engage api customize documentation install setup technology content domains user history info home business cart chart contact email activate analyticsalt analytics autocomplete cart contact content crawling custom documentation domains email engage faceted history info install mobile person querybuilder search setup spellcheck synonyms weights engage_search_term engage_related_content engage_next_results engage_personalized_results engage_recent_results success add arrow-down arrow-left arrow-right arrow-up caret-down caret-left caret-right caret-up check close content conversions-small conversions details edit grid help small-info error live magento minus move photo pin plus preview refresh search settings small-home stat subtract text trash unpin wordpress x alert case_deflection advanced-permissions keyword-detection predictive-ai sso

Synonyms

Synonyms allow you to relate two words together that contextually have the same meaning in your dataset. Sometimes, users will use different terminology, leading them to poor search relevance and bad search results. You can help improve their search experience by creating synonym sets.

Get a Set of Synonyms

Retrieves a synonym set by id.

GET /api/as/v1/engines/{ENGINE_NAME}/synonyms/{SYNONYM_SET_ID}

Returns

A JSON object containing the requested id and the synonyms set keyed by synonyms. Returns an error if the API key does not have read permissions for the requested engine or if the synonym set does not exist.

Example
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/synonyms/syn-5b11ac66c9f9292013220ad3' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
{
  "id": "syn-5b11ac66c9f9292013220ad3",
  "synonyms": [
    "ludicrous speed",
    "tesla"
  ]
}

Example
No Java example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/synonyms/syn-5b11ac66c9f9292013220ad3' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Java example available, showing cURL
{
  "id": "syn-5b11ac66c9f9292013220ad3",
  "synonyms": [
    "ludicrous speed",
    "tesla"
  ]
}

Example
No Node example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/synonyms/syn-5b11ac66c9f9292013220ad3' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Node example available, showing cURL
{
  "id": "syn-5b11ac66c9f9292013220ad3",
  "synonyms": [
    "ludicrous speed",
    "tesla"
  ]
}

Example
No Ruby example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/synonyms/syn-5b11ac66c9f9292013220ad3' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Ruby example available, showing cURL
{
  "id": "syn-5b11ac66c9f9292013220ad3",
  "synonyms": [
    "ludicrous speed",
    "tesla"
  ]
}

Example
No Python example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/synonyms/syn-5b11ac66c9f9292013220ad3' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Python example available, showing cURL
{
  "id": "syn-5b11ac66c9f9292013220ad3",
  "synonyms": [
    "ludicrous speed",
    "tesla"
  ]
}

Example
No Javascript example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/synonyms/syn-5b11ac66c9f9292013220ad3' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Javascript example available, showing cURL
{
  "id": "syn-5b11ac66c9f9292013220ad3",
  "synonyms": [
    "ludicrous speed",
    "tesla"
  ]
}

List Synonyms

Retrieves synonym sets for an engine.

GET /api/as/v1/engines/{ENGINE_NAME}/synonyms

Arguments

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.

Returns

A paginated array of synonym sets represented by a JSON object with id and synonyms as keys. Returns an error if the API key does not have read permissions for the requested engine or if the optional page parameter is not well formed.

Example
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/synonyms' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 3,
      "size": 25
    }
  },
  "results": [
    {
      "id": "syn-5b11ac7beaa0b20b416516d3",
      "synonyms": [
        "violet",
        "purple"
      ]
    },
    {
      "id": "syn-5b11ac72c9f9296b35220ac9",
      "synonyms": [
        "cool car",
        "pt cruiser"
      ]
    },
    {
      "id": "syn-5b11ac66c9f9292013220ad3",
      "synonyms": [
        "ludicrous speed",
        "tesla"
      ]
    }
  ]
}

Example
No Java example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/synonyms' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Java example available, showing cURL
{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 3,
      "size": 25
    }
  },
  "results": [
    {
      "id": "syn-5b11ac7beaa0b20b416516d3",
      "synonyms": [
        "violet",
        "purple"
      ]
    },
    {
      "id": "syn-5b11ac72c9f9296b35220ac9",
      "synonyms": [
        "cool car",
        "pt cruiser"
      ]
    },
    {
      "id": "syn-5b11ac66c9f9292013220ad3",
      "synonyms": [
        "ludicrous speed",
        "tesla"
      ]
    }
  ]
}

Example
No Node example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/synonyms' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Node example available, showing cURL
{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 3,
      "size": 25
    }
  },
  "results": [
    {
      "id": "syn-5b11ac7beaa0b20b416516d3",
      "synonyms": [
        "violet",
        "purple"
      ]
    },
    {
      "id": "syn-5b11ac72c9f9296b35220ac9",
      "synonyms": [
        "cool car",
        "pt cruiser"
      ]
    },
    {
      "id": "syn-5b11ac66c9f9292013220ad3",
      "synonyms": [
        "ludicrous speed",
        "tesla"
      ]
    }
  ]
}

Example
No Ruby example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/synonyms' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Ruby example available, showing cURL
{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 3,
      "size": 25
    }
  },
  "results": [
    {
      "id": "syn-5b11ac7beaa0b20b416516d3",
      "synonyms": [
        "violet",
        "purple"
      ]
    },
    {
      "id": "syn-5b11ac72c9f9296b35220ac9",
      "synonyms": [
        "cool car",
        "pt cruiser"
      ]
    },
    {
      "id": "syn-5b11ac66c9f9292013220ad3",
      "synonyms": [
        "ludicrous speed",
        "tesla"
      ]
    }
  ]
}

Example
No Python example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/synonyms' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Python example available, showing cURL
{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 3,
      "size": 25
    }
  },
  "results": [
    {
      "id": "syn-5b11ac7beaa0b20b416516d3",
      "synonyms": [
        "violet",
        "purple"
      ]
    },
    {
      "id": "syn-5b11ac72c9f9296b35220ac9",
      "synonyms": [
        "cool car",
        "pt cruiser"
      ]
    },
    {
      "id": "syn-5b11ac66c9f9292013220ad3",
      "synonyms": [
        "ludicrous speed",
        "tesla"
      ]
    }
  ]
}

Example
No Javascript example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/synonyms' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Javascript example available, showing cURL
{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 3,
      "size": 25
    }
  },
  "results": [
    {
      "id": "syn-5b11ac7beaa0b20b416516d3",
      "synonyms": [
        "violet",
        "purple"
      ]
    },
    {
      "id": "syn-5b11ac72c9f9296b35220ac9",
      "synonyms": [
        "cool car",
        "pt cruiser"
      ]
    },
    {
      "id": "syn-5b11ac66c9f9292013220ad3",
      "synonyms": [
        "ludicrous speed",
        "tesla"
      ]
    }
  ]
}

Create a Synonym Set

Creates a new synonym set for an engine.

POST /api/as/v1/engines/{ENGINE_NAME}/synonyms

Arguments

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

Returns

A JSON object containing the id of the new synonym set and the synonyms provided in the request. Returns an error if the API key does not have write permissions for the requested engine or if the synonyms is not well formed.

Example
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/synonyms' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "synonyms": ["cool car", "PT Cruiser"]
}'
Example Response
{
  "id": "syn-5b11ac72c9f9296b35220ac9",
  "synonyms": [
    "cool car",
    "PT Cruiser"
  ]
}

Example
No Java example available, showing cURL
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/synonyms' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "synonyms": ["cool car", "PT Cruiser"]
}'
Example Response
No Java example available, showing cURL
{
  "id": "syn-5b11ac72c9f9296b35220ac9",
  "synonyms": [
    "cool car",
    "PT Cruiser"
  ]
}

Example
No Node example available, showing cURL
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/synonyms' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "synonyms": ["cool car", "PT Cruiser"]
}'
Example Response
No Node example available, showing cURL
{
  "id": "syn-5b11ac72c9f9296b35220ac9",
  "synonyms": [
    "cool car",
    "PT Cruiser"
  ]
}

Example
No Ruby example available, showing cURL
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/synonyms' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "synonyms": ["cool car", "PT Cruiser"]
}'
Example Response
No Ruby example available, showing cURL
{
  "id": "syn-5b11ac72c9f9296b35220ac9",
  "synonyms": [
    "cool car",
    "PT Cruiser"
  ]
}

Example
No Python example available, showing cURL
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/synonyms' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "synonyms": ["cool car", "PT Cruiser"]
}'
Example Response
No Python example available, showing cURL
{
  "id": "syn-5b11ac72c9f9296b35220ac9",
  "synonyms": [
    "cool car",
    "PT Cruiser"
  ]
}

Example
No Javascript example available, showing cURL
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/synonyms' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "synonyms": ["cool car", "PT Cruiser"]
}'
Example Response
No Javascript example available, showing cURL
{
  "id": "syn-5b11ac72c9f9296b35220ac9",
  "synonyms": [
    "cool car",
    "PT Cruiser"
  ]
}

Delete a Synonym Set

Delete a synonym set by id.

DELETE /api/as/v1/engines/{ENGINE_NAME}/synonyms/{SYNONYM_SET_ID}

Returns

A JSON object with a deleted property denoting whether the synonym set was successfully deleted. Returns an error if the API key does not have write permissions for the requested engine or if the synonym set does not exist.

Example
curl -X DELETE 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/synonyms/syn-5b11ac66c9f9292013220ad3'  \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
{
  "deleted": true
}

Example
No Java example available, showing cURL
curl -X DELETE 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/synonyms/syn-5b11ac66c9f9292013220ad3'  \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Java example available, showing cURL
{
  "deleted": true
}

Example
No Node example available, showing cURL
curl -X DELETE 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/synonyms/syn-5b11ac66c9f9292013220ad3'  \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Node example available, showing cURL
{
  "deleted": true
}

Example
No Ruby example available, showing cURL
curl -X DELETE 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/synonyms/syn-5b11ac66c9f9292013220ad3'  \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Ruby example available, showing cURL
{
  "deleted": true
}

Example
No Python example available, showing cURL
curl -X DELETE 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/synonyms/syn-5b11ac66c9f9292013220ad3'  \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Python example available, showing cURL
{
  "deleted": true
}

Example
No Javascript example available, showing cURL
curl -X DELETE 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/rent-a-car/synonyms/syn-5b11ac66c9f9292013220ad3'  \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'
Example Response
No Javascript example available, showing cURL
{
  "deleted": true
}

What's Next?

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.


Stuck? Looking for help? Contact Support!