Using Impresee object detection services

This document describes how you can integrate Impresee object detection services into your online store. For the time being these services are only available for apparel stores.

Previous Steps

• Obtain an Impresee application UUID this is a string with 36 characters. This code can be generated in the Impresee Console or you can ask us to generate one for you.

Detecting objects inside images

Request

In order to search products you must use the following REST service:

https://api.impresee.com/ImpreseeSearch/api/v2/detection/boxes/<your_impresee_application_UUID>

The body of this request is a JSON:

1. search_image_base64: Query image encoded in base64 format.

An example of this JSON can be seen below:

{
    "search_image_base64":
"/9j/4AAQSkZJRgABAQAAAwADAAD/4QCMRXhpZgAATU0AKgAAAAgABQESAAMAAAABAAEAAAEaAAUAAAABAAAASgEbAAUAAAABAAAAUgEoAAMAAAABAAIAAIdpAAQAAAABAAAAWgAAAAAAAAB/AAAAMgAAAH8AAAAyAAOgAQADAAAAAQABAACgAgAEAAAAAQAAAAGgAwAEAAAAAQAAAAEAAAAA/+0AOFBob3Rvc2hvcCAzLjAAOEJJTQQEAAAAAAAAOEJJTQQlAAAAAAAQ1B2M2Y8AsgTpgAmY7PhCfv/AABEIAAEAAQMBIgACEQEDEQH/xAAfAAABBQEBAQEBAQAAAAAAAAAAAQIDBAUGBwgJCgv/xAC1EAACAQMDAgQDBQUEBAAAAX0BAgMABBEFEiExQQYTUWEHInEUMoGRoQgjQrHBFVLR8CQzYnKCCQoWFxgZGiUmJygpKjQ1Njc4OTpDREVGR0hJSlNUVVZXWFlaY2RlZmdoaWpzdHV2d3h5eoOEhYaHiImKkpOUlZaXmJmaoqOkpaanqKmqsrO0tba3uLm6wsPExcbHyMnK0tPU1dbX2Nna4eLj5OXm5+jp6vHy8/T19vf4+fr/xAAfAQADAQEBAQEBAQEBAAAAAAAAAQIDBAUGBwgJCgv/xAC1EQACAQIEBAMEBwUEBAABAncAAQIDEQQFITEGEkFRB2FxEyIygQgUQpGhscEJIzNS8BVictEKFiQ04SXxFxgZGiYnKCkqNTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqCg4SFhoeIiYqSk5SVlpeYmZqio6Slpqeoqaqys7S1tre4ubrCw8TFxsfIycrS09TV1tfY2dri4+Tl5ufo6ery8/T19vf4+fr/2wBDABQODxIPDRQSEBIXFRQYHjIhHhwcHj0sLiQySUBMS0dARkVQWnNiUFVtVkVGZIhlbXd7gYKBTmCNl4x9lnN+gXz/2wBDARUXFx4aHjshITt8U0ZTfHx8fHx8fHx8fHx8fHx8fHx8fHx8fHx8fHx8fHx8fHx8fHx8fHx8fHx8fHx8fHx8fHz/3QAEAAH/2gAMAwEAAhEDEQA/AOMooooA/9k=" 
}

Response

The response of this service is a JSON with the following fields:

• impresee_version: API version
• status: Exit status of the detection process. 0 means that there were no errors, while 1 indicates that an error occurred.
• error_message: Only present if status = 1
• query_url: URL where the query thumbnail can be found.
• detection_uid: Unique id of the process.
• query_width: Width of the query thumbnail
• query_height: Height of the query thumbnail
• detections: Array of detected items. Each of the items is a JSON and includes these fields:
  • rank: Relevance of the detected item (1 means highest relevance). It is given by score, size and position inside the query.
  • score: Score of the detection.
  • top: Position of the top of the object with respect to the top of the query (for example a value of 0.14 means that the object top is located at 14% of the height of the query)
  • left: Position of the left side the object with respect to the left side the query
  • width: Width of the object with respect to the total width of the query
  • height: Height of the object with respect to the total height of the query

Searching products after detecting items

Request

By making use of the previous service, this one doesn’t require that you upload the query image again. It works by using the detection identifier to pick the correct query image. The service can be called by sending a POST request to the URL:

https://api.impresee.com/ImpreseeSearch/api/v2/search/products/[impresee-app-uuid]

Where [impresee-app-uuid] is the same from the object detection service. The body of this request is a JSON with three parameters:

• detection_uid: detection uid obtained from the detection service.
• box_id [Optional]: rank of the detection you want to use to search.
• box [Optional]: Used when searching an area of the images that was not detected. It is a JSON with four parameter:
  • top: A number between 0 and 1 indicating the position of the top of object of the object with respect to the query image
  • left: A number between 0 and 1 indicating the position of the object of left side the object with respect to the query image
  • width: A number between 0 and 1 indicating the relative width of the object with respect to the query image
  • height: A number between 0 and 1 indicating the relative height of the object with respect to the query image

Note that you must include either the box_id or the box parameters. The box_id parameter has precedence over the box one, this means that we will always try to use box_id FIRST

Response

In this case the resulting JSON includes all the information from both the detection and searching results:

• 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.
• detection_uid: Unique id of the detection process
• detections: Same structure as described on
• products: Same structure as described on (how to integrate Impresee Search API v2)
• text_codes: Same structure as described on (how to integrate Impresee Search API v2)
• categories_codes: Same structure as described on (how to integrate Impresee Search API v2)