Update API is used for importing search data.
Once Searchanise receives data, it starts indexing this data and after some minutes the data is taken into account in the search results.
The add-on that integrates Searchanise should always track changes in the catalog and send API requests for data actualization.
Request for setting the status of the full import
It’s necessary to send special requests to signify the full import at the beginning and at the end of the initial import of all data and repeated imports of all data.
These are the POST requests sent to https://searchserverapi.com/api/state/update/json with the following parameters:
| Parameter | Description | Value type |
|---|---|---|
| private_key | Private key | string (private key) |
| full_import | Full import status | string (‘start’, ‘done’) |
During the full import, changes are not indexed. They are indexed only after the request about completed full import is received.
An example of the request before the start of the full import
curl -X POST "https://searchserverapi.com/api/state/update/json" -d 'private_key=XXXXXXXXXXXXXXXXXXXX&full_import=start'
> "ok"An example of the request after completion of the full import
curl -X POST "https://searchserverapi.com/api/state/update/json" -d 'private_key=XXXXXXXXXXXXXXXXXXXX&full_import=done'
> "ok"Requests for checking the status of keys, full import, and getting the number of imported products
Once the full import has been completed, it’s good to know whether the indexation is complete and how many products have been imported.
To do so, sent the GET request to https://searchserverapi.com/api/state/get/json with the following parameters:
| Parameter | Description | Value type |
|---|---|---|
| private_key | Private key | string (private key) |
| status | Status of keys and indexation | |
| full_import | Status of the full import | |
| product_count | The number of imported products |
This request will return a JSON object with particular values.
Possible responses for the status parameter
- normal – The data has been received and indexed
- none – The data has not been imported
- update – The data is awaiting indexation
- updating – The data is being indexed
- error – Error during indexation
- disabled – The data has been deleted or keys have been disabled due to non-payment.
Possible responses for the full_import parameter
- start – The full import is in progress
- done – The full import has been completed
An example of the request for getting the status and number of products
curl -X GET "https://searchserverapi.com/api/state/get/json?private_key=XXXXXXXXXXXXXXXXXXXX&status&full_import&product_count"
> {"variable":{"status":"normal","full_import":"done","product_count":"124"}}Request for clearing the database and resetting all settings
In order to delete data from Searchanise, send a POST request to https://searchserverapi.com/api/state/update/json with the following parameters:
| Parameter | Description | Value type |
|---|---|---|
| private_key | Private key | string (private key) |
| addon_status | Add-on status | string (‘enabled’, ‘disabled’, ‘deleted’) |
When sending addon_status=deleted data will be deleted. In order to activate the keys again, send a request to start the full import.
Note: If API keys are paid, data will not be deleted. In this case, data will be deleted only in a month after Searchanise subscription is canceled.
An example of the request for deleting all data and resetting all settings
curl -X POST "https://searchserverapi.com/api/state/update/json" -d 'private_key=XXXXXXXXXXXXXXXXXXXX&addon_status=deleted'
> "ok"An example of the request for getting the status after data is deleted
curl -X GET "https://searchserverapi.com/api/state/get/json?private_key=XXXXXXXXXXXXXXXXXXXX&status&full_import&product_count"
> {"variable":{"status":"disabled","full_import":"done"}}Request to import product data, categories, and pages
Request to import data and settings of the product attributes, filter settings, category data, and pages is a POST request sent to https://searchserverapi.com/api/items/update/json with the following parameters:
| Parameter | Description | Value type |
|---|---|---|
| private_key | Private key | string (private key) |
| data | Object with data in the JSON format (see below). Can be compressed using the ZLIB algorithm (use the gzcompress function for php) | string (json, compressed) |
Parameters for the object with data
| Parameter | Description | Value type |
|---|---|---|
| header | Object with store data and time of updates | object |
| schema | Object with the description of product attributes and filters | object |
| items | Object with products | object |
| categories | Object with categories | object |
| pages | Object with pages | object |
Usually, data are imported in parts:
- The first request contains only the schema object.
- Then all the categories are sent successively by 250 categories.
- Then all the pages are sent successively by 250 pages.
- Then all the products are sent successively by 250 products (you can’t send more than 250 products at a time).
Parameters for the header object
| Parameter | Description | Value type |
|---|---|---|
| id | URL to the store | string (valid url) |
| updated | Date and time of the last update in the ISO 8601 format (can be received using the php date(‘c’) function) | string (ISO8601 datetime) |
This data is not used anywhere yet.
Attribute and filter settings
All products contain data in the form of the “attribute” ⇒ “value” object. Attribute settings are described by an attribute schema. Product filters are built according to attributes and therefore are also defined using the schema.
There are standard attributes that each product has and additional attributes that can be added individually.
Description of standard attributes
| Parameter | Description | Value type | Restrictions on editing |
|---|---|---|---|
| id | Required parameter, unique product id | bigint | Only attribute title can be changed |
| title | Product name. Available in search by default with the weight of 100 | string | Only title, text_search, and weight can be changed |
| summary | Product description. Available in search by default with the weight of 50 | string | Only title, text_search, and weight can be changed |
| link | Link to product | string (valid_url) | Only the title can be changed |
| price | Product price | float | Only the title can be changed and a filter of the range or slider type can be created |
| list_price | Product price with a discount. If not specified or equals 0, this value is ignored | float | Only the title can be changed and a filter of the range or slider type can be created |
| quantity | Product in-stock quantity | int | Only the title can be changed and a filter of the range or slider type can be created |
| product_code | Product SKU. Available in search by default with the weight of 100 | string | Only title, text_search, and weight can be changed |
| image_link | Link to the product image | string (valid url) | Only the title can be changed |
Parameters for the object with attribute and filter settings (schema)
| Parameter | Description | Value type | Default value |
|---|---|---|---|
| name | Required parameter, unique name of an attribute | Must satisfy the regular expression ^[a-zA-Z_][0-9a-zA-Z_]+$ | |
| title | Attribute title | string | Matches name |
| type | Attribute value type | string (text, int, float) | text |
| text_search | Determines whether to take into account the text search. Can be defined only for the attributes with type=text | string (‘Y’, ‘N’) | N |
| sorting | Determines whether sorting by this parameter is necessary | string (‘Y’, ‘N’) | For type=int of float – Y. For type=text – N |
| weight | Weight in search | int | 0 |
| facet | Object with the filter settings (see below) | object |
Parameters for the objects with filter settings (facet)
| Parameter | Description | Value type | Default value |
|---|---|---|---|
| title | Filter title | string | Attribute title |
| position | Filter position in the results | int | 10 + “current max position” |
| type | Filter type (see below) | string (‘select’, ‘slider’, ‘range’) | For the filer type = init, float – range. For the filter type=text – select |
| ranges | Object with the range of value for the filter of the range type (see below) | object |
Filter with the “type” type defines the way the filter is formed:
- select – Normal filter, “Variant” ⇒ “Number of products” list
- slider – Filter slider, the example can be seen at https://searchanise-demo.myshopify.com/pages/search-results-page?q=a
- range – A filter for numbers, the range limits are specified and the number of products that fit within the range is counted.
Parameters for the object with range settings for the filter of the range type (ranges)
| Parameter | Description | Value type | Default value |
|---|---|---|---|
| title | Range name | string | |
| from | Upper limit of the range | int, float | 0.0 |
| to | Bottom limit of the range | int, float | 0.0 |
| position | Position in the results | int | 10 * position number in the ranges array |
Parameters for the object with product data (items)
An array with product data consists of standard attributes (see above) and additional attributes.
Parameters for objects with product data (categories)
An array with category data:
| Parameter | Description | Value type |
|---|---|---|
| id | Required parameter, category id | bigint |
| parent_id | Parent category id. If not specified, 0 value is used. | bigint |
| link | Link to category | string (valid url) |
| title | Category title | string |
| summary | Category description | string |
| image_link | Link to category image | string (valid url) |
Parameters for objects with page data (pages)
An array with page data:
| Parameter | Description | Value type |
|---|---|---|
| id | Required parameter, page id | bigint |
| link | Link to the page | string (valid url) |
| title | Page title | string |
| summary | Page description | string |
| image_link | Link to the page image | string (valid url) |
An example of data
Array
(
[schema] => Array
(
[0] => Array
(
[name] => title
[title] => Product name
)
[1] => Array
(
[name] => price
[title] => Product Price
[facet] => Array
(
[title] => Price
[type] => range
[ranges] => Array
(
[0] => Array
(
[title] => from 0 to 150
[from] => 0
[to] => 150
)
[1] => Array
(
[title] => from 150 to 800
[from] => 150
[to] => 800
)
)
)
)
[2] => Array
(
[name] => categories
[title] => Product Categories
[type] => text
[facet] => Array
(
[title] => Categories
[type] => select
)
)
)
[items] => Array
(
[0] => Array
(
[id] => 1
[title] => Test product 1
[summary] => Test description
[product_code] => product1
[link] => https://example.com/products/product1
[image_link] => https://example.com/images/product1.jpg
[price] => 12
[categories] => Category1
[status] => active
)
[1] => Array
(
[id] => 2
[title] => Test product 2
[summary] => Test summary
[product_code] => product2
[link] => https://example.com/products/product2
[image_link] => https://example.com/images/product2.jpg
[price] => 168
[categories] => Category2
[status] => active
)
)
[categories] => Array
(
[0] => Array
(
[id] => 1
[parent_id] => 0
[title] => Category1 title
[summary] => Category1 test description
[link] => https://example.com/categories/category1
[image_link] => https://example.com/images/category1.jpg
)
)
[pages] => Array
(
[0] => Array
(
[id] => 1
[parent_id] => 0
[title] => Page1 title
[summary] => Page1 test description
[link] => https://example.com/pages/page1
[image_link] => https://example.com/images/page1.jpg
)
)
)An example of the request
curl -X POST "https://searchserverapi.com/api/items/update/json" -d 'private_key=XXXXXXXXXXXXXXXXXXXX&data={"schema":[{"name":"title","title":"Product name"},{"name":"price","title":"Product Price","facet":{"title":"Price","type":"range","ranges":[{"title":"from 0 to 150","from":"0","to":"150"},{"title":"from 150 to 800","from":"150","to":"800"}]}},{"name":"categories","title":"Product Categories","type":"text","facet":{"title":"Categories","type":"select"}}],"items":[{"id":1,"title":"Test product 1","summary":"Test description","product_code":"product1","link":"https:\/\/example.com\/products\/product1","image_link":"https:\/\/example.com\/images\/product1.jpg","price":12,"categories":"Category1","status":"active"},{"id":2,"title":"Test product 2","summary":"Test summary","product_code":"product2","link":"https:\/\/example.com\/products\/product2","image_link":"https:\/\/example.com\/images\/product2.jpg","price":168,"categories":"Category2","status":"active"}],"categories":[{"id":1,"parent_id":0,"title":"Category1 title","summary":"Category1 test description","link":"https:\/\/example.com\/categories\/category1","image_link":"https:\/\/example.com\/images\/category1.jpg"}],"pages":[{"id":1,"parent_id":0,"title":"Page1 title","summary":"Page1 test description","link":"https:\/\/example.com\/pages\/page1","image_link":"https:\/\/example.com\/images\/page1.jpg"}]}'
> "ok"Request for deleting product data
Request for deleting product data is a POST request sent to https://searchserverapi.com/api/items/delete/json with the following parameters:
| Parameter | Description | Value type |
|---|---|---|
| private_key | Private key | string (private key) |
| id | Id of a product that is being deleted | bigint |
An example of the request
curl -X POST "https://searchserverapi.com/api/items/delete/json" -d 'private_key=XXXXXXXXXXXXXXXXXXXX&id=2'
> "ok"Request for deleting category data
Request for deleting category data is a POST request sent to https://searchserverapi.com/api/categories/delete/json with the following parameters:
| Parameter | Description | Value type |
|---|---|---|
| private_key | Private key | string (private key) |
| id | Id of a category that is being deleted | bigint |
An example of the request
curl -X POST "https://searchserverapi.com/api/categories/delete/json" -d 'private_key=XXXXXXXXXXXXXXXXXXXX&id=1'
> "ok"Request for deleting page data
Request for deleting page data is a POST request sent to https://searchserverapi.com/api/pages/delete/json with the following parameters:
| Parameter | Description | Value type |
|---|---|---|
| private_key | Private key | string (private key) |
| id | Id of a page that is being deleted | bigint |
An example of the request
curl -X POST "https://searchserverapi.com/api/pages/delete/json" -d 'private_key=XXXXXXXXXXXXXXXXXXXX&id=1'
> "ok"Possible errors
Update API requests are processed asynchronously, therefore it is impossible to know about errors when processing incorrectly formed data. Also if five or more requests with incorrectly formed data are received within an hour, the API keys will be blocked.
It makes the integration process with Update API inflexible, therefore we recommend purchasing the Enterprise subscription and closely cooperating with the Searchanise team.
Errors when sending data
- {“errors”:{“error”:”error_invalid_private_key”}} – Private API key is incorrect
- {“errors”:{“error”:”error_empty_request”}} – Data or id array is empty {“errors”:{“error”:”inactive_private_key”}} – API keys are disabled
- {“errors”:{“error”:”error_internal_error”}} – Internal error. Please contact the Searchanise team.
- CLOSED; – SIGNUP API and UPDATE API are unavailable at the moment. In this case, please, repeat the request again later.
