Home Decor Search

Quickstart Blog Test in APP Public Demo

With Home Decor Search, your customers can take real-life pictures and find visually similar products in your home decor e-commerce (we call it "visual search"). It also supports multimodal & multilingual text to image search on your product database. Moreover, the Home Decor Search service integrates services that are often requested by our home decor customers - Home Decor Tagging (Categorization), Product Similarity and Dominant Colors.

The API follows the general rules of Ximilar API as described in the First Steps section.

How It Works

Before searching you will need to create a search collection via Ximilar platform. For this you will need to have at least a business plan activated. This will give you unique identifier of the collection that you need to use in your requests. After that you will need to first insert some images (records with metadata and id) into the collection.

The service works through the following process:

Synchronization: Your product database is synchronized with a search collection in Ximilar cloud.
Similar Items: You can get similar items to display alternative products to your customers.
Visual Search: You can send a real-life photo (e.g. from a cell phone), let the system detect home decor items on the photo and get the closest matching items from your collection.
Text Search: You can search products from your search collection via text query in any language.

Endpoints

The base URLs for this service are:

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

POST/v2/insert

Synchronization

Insert images into your search collection. When a product photo is inserted, Ximilar processes the image like this:

Detect home decor items on the photo
Optionally analyze colors of the product and get tags
Extract the visual information (embedding) from this largest detected item
Insert the embedding and meta-data for image to the collection

Required attributes

Name
Authorization
Type
string
Description
Your API token in the format: Token YOUR_API_TOKEN
Name
Collection-Id
Type
string
Description
Your collection ID

Request parameters

Name
records
Type
array
Description
List of records to insert (max 10 per request)
Name
records[]._id
Type
string
Description
Unique identifier for the record
Name
records[]._url
Type
string
Description
URL with a PNG, JPG, or TIFF image file
Name
records[]._base64
Type
string
Description
Base64-encoded content of a PNG, JPG or TIFF image file
Name
records[].Top Category
Type
string
Description
Top category according to Ximilar Home Decor Taxonomy
Name
records[].Category
Type
string
Description
Category according to Ximilar Home Decor Taxonomy
Name
records[].extract_colors
Type
boolean
Description
Whether to extract dominant colors (additional billing)
Name
records[].extract_tags
Type
boolean
Description
Whether to extract tags (additional billing)
Name
records[]._tags_simple
Type
array
Description
Custom tags for the record

Request

POST

/v2/insert

curl --request POST \
  --url https://api.ximilar.com/similarity/homedecor-new/v2/insert \
  --header 'authorization: Token __API_TOKEN__' \
  --header 'collection-id: __COLLECTION_ID__' \
  --header 'content-type: application/json' \
  --data '{
  "records": [
    {
      "_id": "ABC_1",
      "_url": "https://example.com/product/image/url.png",
      "Top Category": "Furniture",
      "Category": "Furniture/Sofas",
      "extract_colors": true,
      "extract_tags": true,
      "_tags_simple": ["modern", "leather", "living-room"]
    }
  ]
}'

Response

{
  "status": {
    "code": 200,
    "text": "OK"
  },
  "records": [
    {
      "_id": "ABC_1",
      "_url": "https://example.com/product/image/url.png",
      "_status": {
        "code": 200,
        "text": "OK"
      }
    }
  ]
}

POST/v2/visualKNN

Visual Search

Search for similar home decor products using a photo. The system will:

Detect all home decor items in the query photo
Return products similar to the largest detected item

Required attributes

Name
Authorization
Type
string
Description
Your API token in the format: Token YOUR_API_TOKEN
Name
Collection-Id
Type
string
Description
Your collection ID

Request parameters

Name
query_record
Type
object
Description
Record containing the image to search with
Name
query_record._url
Type
string
Description
URL with a PNG, JPG, or TIFF image file
Name
query_record._base64
Type
string
Description
Base64-encoded content of a PNG, JPG or TIFF image file
Name
fields_to_return
Type
array
Description
List of fields to return in results
Name
filter
Type
object
Description
MongoDB-style filter for results
Name
k
Type
integer
Description
Number of results to return

Response fields

Name
query_records
Type
array
Description
The query record with detected objects
Name
query_records[]._objects
Type
array
Description
Array of detected home decor items
Name
answer_records
Type
array
Description
Array of similar products
Name
answer_distances
Type
array
Description
Array of similarity scores

Request

POST

/v2/visualKNN

curl --request POST \
  --url https://api.ximilar.com/similarity/homedecor-new/v2/visualKNN \
  --header 'authorization: Token __API_TOKEN__' \
  --header 'collection-id: __COLLECTION_ID__' \
  --header 'content-type: application/json' \
  --data '{
  "query_record": {
    "_url": "https://example.com/image.png"
  },
  "fields_to_return": ["_id", "_url", "product_id"],
  "k": 5
}'

Response

{
  "query_records": [
    {
      "_id": "49831",
      "_url": "https://example.com/image.png",
      "_objects": [
        {
          "area": 0.696093738079071,
          "prob": 0.9520546793937683,
          "Top Category": "Furniture",
          "Category": "Furniture/Sofas",
          "bound_box": [49, 3, 346, 378],
          "_tags": {
            "detailed tag list": true
          },
          "_tags_simple": ["simple tag list"]
        }
      ]
    }
  ],
  "answer_records": [
    {
      "_id": "294215",
      "_url": "https://images.ximilar.com/homedecor/Furniture/Sofas/Modern/v70kjnwe53sz4may/v70kjnwe53sz4may_1.jpg"
    }
  ],
  "answer_distances": [0.64635134],
  "answer_count": 1,
  "status": {
    "code": 200,
    "text": "OK"
  }
}

POST/v2/text

Text Search

Perform multilingual text search (visual similarity/knn) on your collection of images via text query.

Required attributes

Name
Authorization
Type
string
Description
Your API token in the format: Token YOUR_API_TOKEN
Name
Collection-Id
Type
string
Description
Your collection ID

Request parameters

Name
query_record
Type
object
Description
Record containing the text query
Name
query_record._text_data
Type
string
Description
Text query in any language
Name
fields_to_return
Type
array
Description
List of fields to return in results
Name
filter
Type
object
Description
MongoDB-style filter for results
Name
k
Type
integer
Description
Number of results to return

Response fields

Name
answer_records
Type
array
Description
Array of matching products
Name
answer_distances
Type
array
Description
Array of similarity scores

Request

POST

/v2/text

curl --request POST \
  --url https://api.ximilar.com/similarity/text/homedecor/v2/text \
  --header 'authorization: Token __API_TOKEN__' \
  --header 'collection-id: __COLLECTION_ID__' \
  --header 'content-type: application/json' \
  --data '{
  "query_record": {
    "_text_data": "a modern leather sofa with wooden legs"
  },
  "fields_to_return": ["_id", "_url", "supplierid"],
  "filter": {
    "supplierid": {
      "$lte": 600
    }
  },
  "k": 3
}'

Response

{
  "status": {
    "code": 200,
    "text": "OK"
  },
  "answer_records": [
    {
      "_id": "65732555",
      "_url": "_URL_1_",
      "supplierid": 450
    }
  ],
  "answer_distances": [1.1622182],
  "answer_count": 1
}

Multiple Images per Product

If you want to insert multiple images per one product, specify the same product_id field for each record with the identification number of the product. You must also specify this product_id field in the collection settings via app.ximilar.com.

All records must have the product_id field present in your collection if you turn on this setting, otherwise the search responses will return an error.

Example Request

{
  "records": [
    {
      "_id": "__IMAGE_ID__",
      "_url": "__IMAGE_URL__",
      "product_id": "1"
    },
    {
      "_id": "__IMAGE_ID__",
      "_url": "__IMAGE_URL__",
      "product_id": "1"
    },
    {
      "_id": "__IMAGE_ID__",
      "_url": "__IMAGE_URL__",
      "product_id": "1"
    }
  ]
}

Top Category and Category

Sometimes it is difficult to correctly estimate the main item on the product image and its category. 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.

If you specify the Top Category and Category, 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 a home decor item and uses Home Decor Tagging method to determine its categories and tags.

Filtering with Categories

You can also use additional fields Top Categories and Categories to filter objects based on these lists. When doing a search request, you can specify multiple categories to filter the results. The system will:

Filter objects based on the provided Top Categories and Categories lists
Prioritize objects matching the specified Top Category field
Return results that match any of the specified categories

This is particularly useful when you want to search for items that could belong to multiple categories or when you want to prioritize certain categories in the results.

Example Request

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

Search with Category Filtering

curl --location 'https://api.ximilar.com/similarity/homedecor-new/v2/visualKNN' \
--header 'Authorization: Token APITOKEN' \
--header 'collection-id: COLLECTIONID' \
--header 'Content-Type: application/json' \
--data '{
  "query_record": {
    "_url": "https://images.ximilar.com/examples/fail/furniturex.jpg",
    "Top Categories": ["Furniture", "Lighting"],
    "Categories": ["Furniture/Sofas", "Lighting/Floor Lamps"],
    "Top Category": "Furniture"
  },
  "fields_to_return": [
    "_id",
    "_url"
  ],
  "k": 10,
  "cand_set_size": 5000
}'

Search on Specific Object

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. This is useful when you want to search for a specific item in a photo that contains multiple home decor items.

Make sure to copy the whole JSON record of the object (all fields) from the API response when specifying the object to search for.

Workflow with Home Decor Detection

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

Call the Home Decor Detection method to get all home decor 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

Mobile App Integration

If you want to use home decor search in your mobile app and let users draw the object, specify it in the following way. The format of the bounding box is [xmin, ymin, xmax, ymax].

Example Request

POST

/v2/visualKNN

curl --request POST \
  --url https://api.ximilar.com/similarity/homedecor-new/v2/visualKNN \
  --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": [
      {
        "area": 0.376093738079071,
        "prob": 0.9120546793937683,
        "Top Category": "Furniture",
        "Category": "Furniture/Sofas",
        "bound_box": [349, 23, 646, 378]
      }
    ]
  },
  "fields_to_return": ["_id", "_url", "product_id"]
}'

Python Example

from ximilar.client.search import SimilarityHomeDecorClient

client = SimilarityHomeDecorClient(token='__API_TOKEN__', collection='__COLLECTION_ID__')

result = client.search([{
    "_url": "__URL_PATH_TO_IMAGE__",
    "_objects": [
        {
            "area": 0.376093738079071,
            "prob": 0.9120546793937683,
            "Top Category": "Furniture",
            "Category": "Furniture/Sofas",
            "bound_box": [349, 23, 646, 378]
        }
    ]
}])

Mobile App Example

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