Update API

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:

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.
Updated on March 23, 2022

Was this article helpful?

Related Articles

Back to top