How to integrate Impresee Search API v2
This document describes how you can integrate Impresee visual search services into your online store.
Impresee’s image based search service is a
REST service that takes a text and/or a query image and searches inside one or more catalogs. The service can be called by sending a
POST request to the URL:
The body of this request is a
search_image_base64: Query image encoded in base64 format.
An example of this JSON can be seen below
Remember: To perform a visual search you DO NOT need to include the
search_text unless you really want to search using both image and text
In order to reduce the size of the request, clients can send a compressed message by following this steps:
- Add the
Content-Encoding: gzipheader to the request.
- Send a compressed
By doing these steps, the server will first decompress the message and then resolve the search. Please note that compressing the search message is critical for obtaining good upload times.
Once the server has finished performing the search process it will return a
JSON with the following fields:
impresee_version: API version
status: Exit status of the search process. 0 means that there were no errors, while 1 indicates that an error occurred.
error_message: Empty if status value is 0.
query_url: URL where the query can be found.
search_uid: Unique id of the search.
products: Array of products which images appear similar to the query. The array is ordered by the product’s similarity to the query, meaning that the first product is the most similar. Each product has five fields:
rank: Position in the result list. A value of 1 indicates that product is the most similar to the query.
product_url: URL of the product inside the e-commerce site.
product_image: URL of the main image of the product
product_texts: List of product texts objects. Each of them has two fields:
code: Code of the associated text
value: Value associated to the code, which is specific to the product itself
product_categories: List of categories which the product belongs to. Each category is an object with one field:
code: Category code.
texts_codes: A list of objects that map each text code to a readable string. Each object has two fields:
code: A text code
name: String associated to that text code
categories_codes: A list of objects that map each category code to a readable string. Each object has two fields:
code: A category code
name: String associated to that category code
Please note that the size of this
JSON can be around 50KB. In order to reduce the time it takes the client to download the response, Impresee servers support sending a compressed
JSON as a response. To ask the server to send a compressed response the following must be done:
- Ask the server to compress the search result by adding an
Accept-Encoding: gzipheader to the search request. Note that the server may decide not to compress the
JSONif it is too small.
- Receive the response from the server and check whether it contains the
Content-Encoding: gzipheader or not. If it does, the body has been compressed with the
- Decompress the body and parse the
Below you can find an example of a search result:
In order to obtain both good search results and good upload times, there are two considerations that need to be taken:
- Size and quality of the image: A large image with high quality is usually very big (we are talking about megabytes). Uploading images of these characteristics can take too long, without bringing any advantage in terms of the quality of the search results. We recommend resizing the image and changing its quality before encoding it to base64. The recommended values are:
- Longest side of 480 pixels.
- Quality of 75%.
This should result in a filesize close to
- The object in the query image should be centered: To obtain good search results the object that is being looked for must be in the center of the image.
Note that this means that images should be cropped before searching, so that they mostly consider the object of interest (unless you’re using our Snap the Look feature).