Home Decor Search

PRICING TAXONOMY

With Home decor Search, your customers can take real-life pictures & find visually similar products in your Furniture/Home decor e-commerce (we call it "visual search"). Moreover, the Home decor Search service integrates three services that are often requested by our customers - Tagging, Similarity and Dominant Colors.

How it works

Your database is synchronized with a collection in Ximilar cloud (see below).
You can get tags for each product in your database (see below).
You can get similar items to display alternative products to your customers (see below).
You can send a real-life photo (e.g. from a cell phone), let the system detect apparel items on the photo and get the closest matching items from your collection (see below).

The API is on the following URL:

https://api.ximilar.com/similarity/homedecor/v2/<method>

and it contains all methods from Photo & Product Similarity.

Things to note

For insert (/v2/insert) you can specify maximum of 10 records per request/batch size in "records" field
Search (/v2/visualTagsKNN) is only possible with one record (photo) in field "query_record"

Synchronize your databaseSpecifying item category

You store your product image database into a collection in Ximilar cloud in the same way you do with in Photo & Product Similarity. When a product photo is inserted into the collection, Ximilar process the image like this:

Detect furniture/home decor items on the photo
Runa Home Decor Tagging on the largest detected item
Extract the visual information from this largest detected item
Insert the image with the tags to the collection

Ximilar can do the synchronization

You can keep the collection synchronized yourself via the insert and delete API methods. The other option is let Ximilar do this for you - run a regular process (e.g. nightly) that:

Downloads your current database export (in any format agreed on) from a given URL,
Calculates the difference between the export and your collection
Inserts new products to the collection
Removes stale products from the collection.

Ximilar must know the format of your data and we can together define a mapping between your categories and Ximilar taxonomy and thus specify the Top Category (and Category) of the main item during the insert operation (see above). We usually charge a small fee for implementation of the synchronization script (depending on complexity and format of the export).

Contact us at tech@ximilar.com and we will arrange this regular sync for you.

Sometimes it is difficult to correctly estimate the main item on the product image and its category by AI. You can help Ximilar with this by sending over the information about the Top Category (and Category) of the product. You must use the categories according to Ximilar Home Decor Taxonomy and put the information into each inserted image record, e.g.

{
  "records": 
  [
    {
      "product_id": "ABC",
      "_id": "ABC_1",
      "_url": "https://example.com/product/image/url.png",
      "Top Category": "Furniture",
      "Category": "Furniture/Relax"        
    }
  ] 
}

If you do this, the insert operation will not necessarily select the largest object detected but the largest object with the matching Top Category (and Category). In case there is no such object detected in the image, Ximilar considers the whole image as home decor item and uses Home Decor Tagging method to determine its categories and tags.

Get tags /v2/get

As mentioned above, each product photo that is inserted into your search collection, is processed by the Home Decor Tagging method. The response from this method is stored in your Ximilar collection. There are two ways to get to this output:

When you call the insert API operation, the response from this operation contains also the JSON response from the Apparel Detection & Tags method.
You can use method /v2/get to get the tags stored in individual records. See example of such response below.

Visual search by photo /v2/visualTagsKNN

After you create and insert all the data to your collection you can perfom a search operations. You can get similar item recommendations in the same way as you would with image similarity using method

https://api.ximilar.com/similarity/homedecor/v2/visualTagsKNN

The method combines the visual similarity with the similarity of tags from the tagging (it is stored in field _tags_simple). Internally, the system also uses a default filter that is automatically internally added to the filter parameter specified in the API methods. Currently this default filter is:

Json

{ "filter": { "Top Category": "{TAKE_FROM_QUERY}", "Category": "{TAKE_FROM_QUERY}" } }

This default filter might change in future but it does not influence the overall behaviour of the search.

This method returns:

all Furniture/Home Decor items detected in the query photo - it is in field query_records[0]._objects,
and products from your collection that are similar to the largest item detected - standard fields answer_records and distances.

CLICK TO SHOW CURL REQUEST

Bash

$ curl --url https://api.ximilar.com/similarity/homedecor/v2/visualTagsKNN \
    --request POST \ 
    --header "Content-Type: application/json" \
    --header "Authorization: Token __API_TOKEN__" \
    --header "collection-id: __COLLECTION_ID__" \
    --data '{ 
      "from": 0,
      "k": 10,
      "query_record": { "_url": "__IMG_URL__" },
      "fields_to_return": [ "_id", "_url", "_width", "_height", "_objects" ]
  }'

CLICK TO SHOW JSON RESPONSE

Json

{
  "status": {
    "code": 200,
    "text": "OK"
  },
  "statistics": {
    "OperationTime": 2393
  },
  "answer_records": [
    {
      "_id": "2028620b-5a83-47a9-b3ed-fb7934b987b7",
      "_url": "__IMAGE_URL__",
      "_width": 1024,
      "_height": 682,
      "_objects": [...]
    },
    {
      "_id": "364c7fba-b382-27c3-b568-514017f9005e",
      "_url": "__IMAGE_URL__",
      "_width": 1024,
      "_height": 525,
      "_objects": [...]
    },
    {
      "_id": "a5920ccd-3ecb-480d-8a9c-efdc3131c7a5",
      "_url": "__IMAGE_URL__",
      "_width": 1024,
      "_height": 712,
      "_objects": [...]
    }
  ],
  "answer_distances": [
    0.11088934,
    0.18249066,
    0.19146316
  ],
  "query_records": [
    {
      "_status_extraction": "standard",
      "_id": "179656d8-514c-4edb-a4a4-24d295fe6a19",
      "_url": "__IMAGE_URL__",
      "_width": 1024,
      "_height": 682,
      "_objects": [...]
    }
  ],
  "answer_count": 10
}

If you want to get products similar to any other object than the main (largest) one, you can do it by simply passing the query object with the field _objects pre-filled with the secondary object. The query might then look like this:

Bash

$ curl --request POST \
    --url https://api.ximilar.com/similarity/homedecor/v2/visualTagsKNN \
    --header 'authorization: Token __API_TOKEN__' \
    --header 'collection-id: __COLLECTION_ID__' \
    --header 'content-type: application/json' \
    --data '{
    "query_record":
    {
      "_url": "https://example.com/image.png",
      "_objects": [
        {
          "prob": 0.67579657,
          "Category": "Accessories/Lighting",
          "Top Category": "Accessories",
          "bound_box": [
            208,
            19,
            303,
            217
          ]
        }
      ]
    },
    "fields_to_return": [ "_id", "_url", "product_id" ]
  }'

Just make sure that you copy the whole JSON record of the object (all fields) from the API response.

You can combine the Home Decor Tagging method and the visual search like this:

call the Home Decor Detection method to get all objects/products items in the photo (without directly getting similar products),
let your user select the item they are interested in
use the object JSON record in the subsequent visual search query (/v2/visualTagsKNN).

Customization and special features

Following examples are for /v2/insert endpoint. If you want to use this in search (/v2/visualTagsKNN) please use "query_record" dictionary instead of "records" list.

Use custom profile

Would you like to rename some of our tags or do some other modifications? For example if our tagging system says that the product is 'table', 'black' we can generate 'black table' tag. This is done by creating custom profile for you. Just write us and we will discuss the usage with you.

Draw a bounding box in mobile app?

Do you want to use Home decor Search in your mobile app and let user to draw the object? Just specify it in following way. The format of bounding box is [xmin, ymin, xmax, ymax].

Json

{
    "query_record": {
        "_url": "__URL_IMAGE__",
        "_objects": [
            {
                "bound_box": [
                    701,
                    1760,
                    1155,
                    1952
                ]
            }
        ]
    }
}