- App Search Guide: other versions:
- Installation
- Getting started
- Authentication
- Limits
- Users and access
- Guides
- Adaptive relevance events logs reference
- Analytics Tags
- Crawl web content
- Crawl a private network using a web crawler on Elastic Cloud
- Crawl custom fields using proxy
- Curations
- Elasticsearch search
- Elasticsearch index engines
- Create Elasticsearch index engines
- Configure dynamic field mappings and analyzers in an Elasticsearch index engine
- Elasticsearch engines text field conventions
- Facets
- Hierarchical Facets
- Indexing Documents
- Language Optimization
- Log settings
- Meta Engines
- Precision tuning (beta)
- Query Suggestions
- Search UI
- Relevance Tuning
- Result Settings
- Result Suggestions
- Role based access control (RBAC)
- Sanitization, Raw or Snippet
- Search
- Synonyms
- View web crawler events logs
- App Search web crawler
- Web crawler FAQ
- Web crawler reference
- Web crawler events logs reference
- API Reference
- Adaptive relevance API reference (beta)
- Analytics APIs
- Analytics clicks API
- Analytics counts API
- Analytics queries API
- API logs API
- Click API
- Credentials API
- Curations API reference
- Documents API
- Elasticsearch search API
- Engines API
- Log settings API
- Multi search API
- Query suggestion API
- Schema API
- Search API
- Search API boosts
- Search API facets
- Search API filters
- Search API group
- Search API precision (beta)
- Search API result fields
- Search API search fields
- Search API sort
- Search API analytics tags
- Search settings API
- Search Explain API
- Source engines API
- Synonyms API
- Web crawler API reference
- API Clients
- Configuration
- Known issues
- Troubleshooting
Synonyms API
editSynonyms API
editCheckout the Synonyms guide for deeper concepts.
Search API precision has no effect in queries that contain synonyms.
Create synonym sets.
Authentication
editFor 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
editList All Synonyms
editRetrieves 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
editExample
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
editRetrieves 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
editCreates 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
editUpdates 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
editDelete 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
editThe 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?
editConfiguring 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.
On this page