Home Decor Search

Quickstart Taxonomy Blog Test in App Public Demo

To access the Ximilar API, first register at Ximilar App to get your API token.

The Home Decor Search API lets your customers upload real-life or social media photos and instantly discover visually similar products in your home decor and furniture catalog.

It combines several features often requested by home decor clients:

Home Decor Tagging for automatic categorization
Product Similarity to suggest related and alternative items
Dominant Colors for color-based search and filtering

The API is powered by advanced visual search technology and deep learning models trained specifically on home decor items. Beyond image-based search, it also supports multimodal and multilingual text-to-image queries across your product database.

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

How It Works

To use the API:

Create a collection in Ximilar App — you’ll get a unique collection ID to include in all requests.
Insert products — add records (image + metadata + _id). Processing and indexing run automatically.
Keep it synced — schedule automatic synchronization runs at your chosen cadence (e.g., hourly/daily) to add, update, or remove items as your catalog changes. See Synchronization.

Once setup, you can:

Search home decor & furniture: Input a product or real-life image, and the system finds closest matches.
Recommend products: Suggest visually similar items to users based on their browsing or purchase history.
Use text search: Send queries in any language to find matching products in your collection.

This service is available in paid pricing plans. For more information, see Pricing page.

Endpoints

The URLs for this service are:

https://api.ximilar.com/similarity/homedecor-new/v2/insert  (insert images and metadata into collection)
https://api.ximilar.com/similarity/homedecor-new/v2/visualKNN  (perform image-based search)
https://api.ximilar.com/similarity/text/homedecor/v2/text  (perform text-based search)

POST/v2/insert

Synchronization

Add images (products) to your Home Decor Search collection. Each inserted record is processed as follows:

Detect home decor items or furniture in the photo.
Optionally analyze product colors and assign tags.
Extract visual features (embedding) from the largest detected item.
Store the embedding together with your metadata in 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
Max
Maximum:10
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
If set to true, the system will extract dominant colors for the item. This will consume additional API credits as per the Dominant Colors pricing.
Name
records[].extract_tags
Type
boolean
Description
If set to true, the system will extract relevant tags for the item. This will consume additional API credits as per the Home Decor Tagging pricing.
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 fashion products using a photo. The system will:

Detect all fashion items in the query photo
Return similar products 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
An array of detected home decor items.
Name
answer_records
Type
array
Description
An array of similar products.
Name
answer_distances
Type
array
Description
An 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
An array of matching products.
Name
answer_distances
Type
array
Description
An 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

To insert multiple images for the same product, specify the same product_id for each record with the identification number of the product. You must also specify this product_id field in the collection settings in Ximilar App.

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 identify the main item in a product image and its category. You can help Ximilar by providing the Top Category (and Category) of the product. These must follow the Ximilar Home Decor Taxonomy and be included in each inserted image record.

If you specify the Top Category and Category, the insert operation will not necessarily select the largest detected object, but rather the largest object matching the provided Top Category (and Category). If no such object is detected, Ximilar will treat the whole image as a home decor item and use the Home Decor Tagging method to determine its categories and tags.

Filtering with Categories

You can also filter search results using the Top Categories and Categories fields. In a search request, you may specify multiple categories, and the system will:

Filter objects by the provided Top Categories and Categories lists
Prioritize objects that match the specified Top Category
Return results that match any of the specified categories

This is particularly useful when searching 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 search for products similar to an object other than the main (largest) one, you can do this by passing the query object with the _objects field pre-filled with the secondary object. This is useful when a photo contains multiple home decor items and you want to focus on a specific one.

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 and furniture 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 integrate home decor search into a mobile app and allow users to draw/select the object, specify it using a bounding box. 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]
        }
      ]
    }
  ]
}