Curations API
editCurations API
editWant to start with the core concepts? Give the Curations guide a read.
Curations hide or promote result content.
Each query may only belong to one curation.
Authentication
editFor authentication, the Curations endpoint requires...
-
A Host Identifier:
[HOST_IDENTIFIER]
-
The name of your Engine:
[ENGINE]
-
A Private API Key:
[PRIVATE_API_KEY]
curl -X GET 'https://[instance id].ent-search.[region].[provider].cloud.es.io/api/as/v1/engines/[ENGINE]/curations' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer [PRIVATE_API_KEY]'
List Curations
editList All Curations
editReturn an array of all active curations.
GET /api/as/v1/curations
-
page
(optional) - Can provide... current for current page total_pages for the net number of pages total_results for the overall number of results size for the amount of results per page. Expects integers within all fields. Defaults to 25 per page.
Example - A GET
request for all curations.
curl -X GET 'https://[instance id].ent-search.[region].[provider].cloud.es.io/api/as/v1/engines/national-parks-demo/curations' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxxxxxx'
Example Response
{ "meta": { "page": { "current": 1, "total_pages": 1, "total_results": 3, "size": 25 } }, "results": [ { "id": "cur-a1b2c3", "queries": [ "banana", "bananana", "bonana", "nanner" ], "promoted": [ "doc-a1b2c3", "doc-234", "doc-a3b4c5" ], "hidden": [ "doc-a9b8c7", "doc-a8b7c6", "doc-abc" ] }, { "id": "cur-a2b3c4", "queries": [ "cherry", "cherri", "sherry" ], "promoted": [ "doc-a1b1c1", "doc-a2b2c2" ], "hidden": [] }, { "id": "cur-a3b4c5", "queries": [ "grape" ], "promoted": [], "hidden": [ "doc-a3b3c3" ] } ] }
List All Curations with Pagination
editExample - A GET
request for all curations, paginated. Returns the 2nd page of results, with 20 results per page.
curl -X GET 'https://[instance id].ent-search.[region].[provider].cloud.es.io/api/as/v1/engines/national-parks-demo/curations' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxxxxxx' \ -d '{ "page": { "size": 20, "current": 2 } }'
Example Response
{ "meta": { "page": { "current": 2, "total_pages": 2, "total_results": 30, "size": 20 } }, "results": [ ## Truncated! ] }
List a Single Curation
editGET /api/as/v1/engines/[ENGINE]/curations/[CURATION_ID]
Example - A GET
request for the curation with id 123
.
curl -X GET 'https://[instance id].ent-search.[region].[provider].cloud.es.io/api/as/v1/engines/national-parks-demo/curations/a1b2c3' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxxxxxx'
Example Response
{ "meta": { "page": { "current": 1, "total_pages": 1, "total_results": 1, "size": 25 } }, "results": [ { "id": "cur-a1b2c3", "queries": [ "banana", "bananana", "bonana", "nanner" ], "promoted": [ "doc-a1b2c3", "doc-a2b3c4", "doc-a3b4c5" ], "hidden": [ "doc-a9b8c7", "doc-a8b7c6", "doc-a7b6c5" ] } ] }
Create New Curation
editPOST /api/as/v1/engines/[ENGINE]/curations
-
queries
(required) -
You can provide one or many query strings within an array.
A query may only belong to one curation. -
promoted
(optional) -
Supply an array with the documents to promote.
The array order determines precedence: 0, 1, 2, ….
You must provide a value for either promoted or hidden, or include both. If creating a curation for a meta engine, see Curations and meta engines. -
hidden
(optional) -
Supply an array with the documents to hide.
You must provide a value for either promoted or hidden, or include both. If creating a curation for a meta engine, see Curations and meta engines.
Example - A POST
request to create a new curation.
curl -X POST 'https://[instance id].ent-search.[region].[provider].cloud.es.io/api/as/v1/engines/national-parks-demo/curations' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxxxxxx' \ -d '{ "queries": [ "banana", "bananana", "bonana", "nanner" ], "promoted": [ "doc-123", "doc-234", "doc-345" ], "hidden": [ "doc-987", "doc-a8b7c6", "doc-765" ] }'
Example Response
{ "id": "cur-a1b2c3" }
Update Curation
editPUT /api/as/v1/engines/[ENGINE]/curations
-
queries
(required) -
You can provide one or many query strings within an array.
A query may only belong to one curation. -
promoted
(optional) -
Supply an array with the documents to promote.
The array order determines precedence: 0, 1, 2, ….
You must provide a value for either promoted or hidden, or include both. If creating a curation for a meta engine, see Curations and meta engines. -
hidden
(optional) -
Supply an array with the documents to hide.
You must provide a value for either promoted or hidden, or include both. If creating a curation for a meta engine, see Curations and meta engines.
Example - A PUT
request to update curation 123
to change promoted documents and to cease hiding two documents.
curl -X PUT 'https://[instance id].ent-search.[region].[provider].cloud.es.io/api/as/v1/engines/national-parks-demo/curations/cur-a1b2c3' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxxxxxx' \ -d '{ "queries": [ "banana", "bananza", "bananas", "bonana" ], "promoted": [ "doc-a1b2c3", "doc-a3b3c4", "doc-445" ], "hidden": [ "doc-a9b8c7" ] }'
Example Response
{ "id": "cur-a1b2c3" }
Delete Curation
editDELETE /api/as/v1/curations/[CURATION_ID]
Example - A DELETE
request to destroy the curation with id 123
.
curl -X DELETE 'https://[instance id].ent-search.[region].[provider].cloud.es.io/api/as/v1/engines/national-parks-demo/curations/cur-a1b2c3' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxxxxxx'
Example Response
{ "deleted": true }
Curations and Sorting
editYou may expect a curation to always be in its curated position, regardless of sort. But that’s not always the case.
It’s helpful to understand cases where a curation will and will not have priority when using sorting.
Curations are applied when there is...
- No sort field(s).
-
A sort against the
_score
field.
Curations are not applied when there is...
- A sort against a custom field.
-
A multi sort against
_score
, followed by a custom field.
Curations and meta engines
editWhen creating curations for meta engines, scope the ID of each promoted and hidden document to the source engine containing the document.
Specify each document ID using the following format:
<source_engine_id>|<document_id>
The following example for a meta engine creates a curation that promotes documents from different source engines.
curl -X POST 'https://[instance id].ent-search.[region].[provider].cloud.es.io/api/as/v1/engines/national-parks-demo/curations' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxxxxxx' \ -d '{ "queries": [ "popular parks" ], "promoted": [ "eastern-national-parks|park_shenandoah", "western-national-parks|park_yosemite" ] }'
Errors
editRequest parameters can be quite particular.
Did you get an error? Perhaps it is one of these?
Error Message |
Method |
Solution |
"queries must be supplied" |
POST/PUT |
Queries are a required field. Make sure you have included at least one. |
"queries must be a non empty array of strings" |
POST/PUT |
Even if you are supplying one query, you will need to encapsulate it within an array. |
"query already exists under another curation: |
POST/PUT |
Each query can belong to one curation. |
"promoted must be a non empty array of strings" |
POST/PUT |
Even if you are supplying one document, you will need to encapsulate it within an array. Must be a string. |
"hidden must be a non empty array of strings" |
POST/PUT |
Even if you are supplying one document, you will need to encapsulate it within an array. Must be a string. |
"promoted contains invalid document ids: [ |
POST/PUT |
The document that you included in the array could not be found, or the string was malformed in some way. |
"hidden contains invalid document ids: [ |
POST/PUT |
The document that you included in the array could not be found, or the string was malformed in some way. |
"curation must include either promoted or hidden" |
POST/PUT |
A curation without at least one promotion or one hidden item is not a curation at all! Please include one. |
"curation does not exist for id: cur-a1b2c3" |
DELETE |
The request was received, and the API wanted to delete something, but was unable to locate the curation given the |
What’s Next?
editYour Curations can become mighty tools in improving the relevance, and thus the overall experience, of search queries. Business goals, too, as you can get your visitors where you would like them to be. If you want to take a deep look into how users are interacting with your Engines, the Analytics and Clickthrough endpoints are worth exploring. Another useful technique to deploy are Synonyms.