Search
README
To set up it, simply install EPICA application in your Shopify store and feed will configure automatically. Make sure that you complete this step before usage and reading this document.
Validation
The main endpoint for search(/api/v1/search) do not need authorization, but also need a write_key which you can find in our platform in account settings. As EPICA company client, you can also have an auth token. You can read more about it here.
Public API (use write_key)
Search
Shopify product has several variants and when you are searching, we display most relevant of them. This public endpoint does not need any auth. There are GET and POST methods here:
GET method works fast but returns only 6 most relevant products and some extra information about it. We use it in the search widget
POST method works a little bit longer but has extra features like filtering and paging. You can see it in full search page
Purpose | Search |
---|---|
Endpoint | /api/v1/search |
Method | GET |
(GET) Request params
(GET) Response fields
| query: (type: string) search query anonymous_id: (type: uuid) person identifier, generated by epica.js autocomplete_items: (type: array(string)) query suggestions {
"found_products": [
{
"price": 51.0,
"title": "INSULAR Mummy Diaper Backpack Fashionable Large Capacity Mother Bag Multifunctional Travel Baby Backpack bag Nappy Bags",
"score": 191.12119,
"url": "https://demo-ec.epica.ai/products/insular-mummy-diaper-backpack-fashionable-large-capacity-mother-bag-multifunctional-travel-baby-backpack-stroller-bag-nappy-bags?variant=26562489581632",
"discount_percent": 0,
"image": "https://cdn2.shopify.com/s/files/1/0055/3143/5072/products/product-image-816957997.jpg?v=1552300692",
"sku": "3207712833600_26562489581632",
"discount": 51.0
},
{
"price": 64.0,
"title": "Diaper bag nappy",
"score": 191.57248,
"url": "https://demo-ec.epica.ai/products/baby-stroller-bag-fashion-mummy-bags-large-diaper-bag-backpack-baby-organizer-maternity-bags-for-mother-handbag-nappy-backpack?variant=26562746449984",
"discount_percent": 0,
"image": "https://cdn2.shopify.com/s/files/1/0055/3143/5072/products/product-image-508608478.jpg?v=1552300978",
"sku": "3207756709952_26562746449984",
"discount": 64.0
}
],
"found_products_count": 44,
"autocomplete_items": [
"red bag dollar",
"red bags",
"bag"
],
"query": "red bag",
"found_categories": [
{
"url": "https://demo-ec.epica.ai/collections/home-page",
"title": "Home Page"
},
{
"url": "https://demo-ec.epica.ai/collections/diaper-bags",
"title": "Diaper Bags"
}
]
} |
(POST) Request body params
| query: (type: string) search query anonymous_id: (type: uuid) person identifier, generated by epica.js {
"found_products_count": 44,
"query": "red bag",
"found_products": [
{
"price": 51.0,
"title": "INSULAR Mummy Diaper Backpack Fashionable Large Capacity Mother Bag Multifunctional Travel Baby Backpack bag Nappy Bags",
"score": 191.12119,
"url": "https://demo-ec.epica.ai/products/insular-mummy-diaper-backpack-fashionable-large-capacity-mother-bag-multifunctional-travel-baby-backpack-stroller-bag-nappy-bags?variant=26562489581632",
"discount_percent": 0,
"image": "https://cdn2.shopify.com/s/files/1/0055/3143/5072/products/product-image-816957997.jpg?v=1552300692",
"sku": "3207712833600_26562489581632",
"discount": 51.0
},
...
{
"price": 61.0,
"title": "Insular Mummy Maternity Diaper Bag Large Capacity Baby Stroller Bag Travel Nappy Backpack Designer Nursing Bag For Baby Care",
"score": 23.472298,
"url": "https://demo-ec.epica.ai/products/insular-mummy-maternity-diaper-bag-large-capacity-baby-stroller-bag-travel-nappy-backpack-designer-nursing-bag-for-baby-care?variant=26562233925696",
"discount_percent": 0,
"image": "https://cdn2.shopify.com/s/files/1/0055/3143/5072/products/product-image-786499954.jpg?v=1552300411",
"sku": "3207670890560_26562233925696",
"discount": 61.0
}
],
"page": 1,
"filters": [
{
"max": 282.0,
"title": "Price",
"current_max": 282.0,
"type": "price",
"current_min": 1.0,
"min": 1.0
},
{
"based_on": "tag",
"position": 1,
"title": "All tag",
"filter": "",
"type": "filter",
"values": [
{
"name": "0",
"count": 1
},
...
{
"name": "car seats",
"count": 1
}
],
"id": 1
},
{
"based_on": "collection",
"position": 2,
"title": "All collection",
"filter": "",
"type": "filter",
"values": [
{
"name": "Diaper Bags",
"count": 23
},
{
"name": "Highchairs & Booster Seats",
"count": 1
},
{
"name": "Home Page",
"count": 44
}
]
...
}
],
"total_pages": 3
} |
Errors |
|
Curl Example | GET: curl -X GET -H "Content-Type: application/json" "https://api.epica.ai/api/v1/search?query=red%20stroller&write_key=6682adba374255dc50091d6d3702f36d" |
Platform API (need auth_token)
Filters
You can create your own filters based on search fields. There are some default filters after the initialization of the search app. Here is an example of how we use it
Purpose | Filters for full search |
---|---|
Endpoint | /api/v1/search/filters |
Method | GET |
(GET) Response fields
| filters: (type: array(object)) list of all filters
|
(POST/PUT) Request body params (POST/PUT) Request body example
| filters: (type: array(object)) list of new filters |
(DELETE) Request body params (DELETE) Request body example
| filter_ids: (type: array(int)) list of filter ids to be delete |
Errors |
|
Curl Example |
Filter values
This endpoint is used to get all possible values for the filter
Purpose | Setup fields for search |
---|---|
Endpoint | /api/v1/search/filter/items/{filter_id} |
Method | GET |
(GET) Request URL example (GET) Response fields (GET) Response example | /api/v1/search/filter/items/1
|
Errors |
|
Curl Example |
Fields setup
By default, all fields are included in the search, but you can exclude some of them. The endpoint is used in settings.
Purpose | Setup fields for search |
---|---|
Endpoint | /api/v1/search/fields |
Method | GET |
(GET) Response fields (GET) Response example | search_fields: (type: array(object)) list of fields available for search |
(PUT) Request body params (PUT) Request body example
| fields: (type: array(object)) list of the field which should be modified |
Errors |
|
Curl Example |
Info
It should take time between installation and usage
Purpose | Check the status of the search |
---|---|
Endpoint | /api/v1/search/info |
Method | GET |
(GET) Response body fields | availability: (type: bool) is search app ready or not |
Errors |
|
Curl Example |
Config
We are planning a lot of configs. Now there is only one serve config display_not_active_products.
Purpose | Store config |
---|---|
Endpoint | /api/v1/search/config |
Method | GET PUT |
(GET) Response body fields | display_not_active_products: (type: bool, default: false) filter by field active. Display all products if false |
(PUT) Request params | display_not_active_products: (type: bool, default: false) filter by field active. Display all products if false |
Errors |
|
Curl Example |
Reindex content
It is admin v0 endpoint. It's used for all components rebuilding (feed, models, recommenders)
Purpose | Full rebuild |
---|---|
Endpoint | /api/v0/search/reindex |
Method | POST |
(POST) Request body params | schema: (type: string) company schema name. system field |
Errors |
|