Skip to content

Furniture & Home-Decor Tagging

PRICING TAXONOMY

The Furniture & Home-Decor service provides categories, sub-categories and various tags for furniture & home-decor product images.

Please, see page API Calls and Credits for exact prices for individual API calls. The Tagging uses a flow of complex recognition models to tag each image, that's why the cost is higher than a simple image classification.

See it in action ...

  • We provide taxonomy (top categories, categories, features and tags)
  • We are constantly improving this service. We are open to add more features/tags on you request! (depends on your budget)
  • Our furniture & home-decor tagging is easily customizable (rename the tags for your needs, creating new tags from other, ...) through your custom profile (contact us at sales@ximilar.com)

Taxonomy

Here we provide our Home-Decor taxonomy pdf document with example images and full taxonomy tree with all possible tags.

FURNITURE & HOME-DECOR TAXONOMY

API reference

The API follows the general rules of Ximilar API as described in Section First steps.

List of Top Categories and Categories: /v2/top_categories

https://api.ximilar.com/tagging/homedecor/v2/top_categories

curl --request GET \
  --url https://api.ximilar.com/tagging/homedecor/v2/top_categories \
  --header 'content-type: application/json'

CLICK TO SHOW JSON RESULT

{
  "Furniture": [
    "Furniture/Furniture Set",
    "Furniture/Beds",
    "Furniture/Relax",
    "Furniture/Sitting",
    "Furniture/Storage",
    "Furniture/Tables"
  ],
  "Accessories": [
    "Accessories/Bathroom",
    "Accessories/Decorative",
    "Accessories/Dining & Cookware",
    "Accessories/Lighting",
    "Accessories/Mirrors",
    "Accessories/Storage",
    "Accessories/Textile"
  ]
}

Home-Decor detection and tags endpoint: /v2/detect_tags

https://api.ximilar.com/tagging/homedecor/v2/detect_tags

Given a list of image records, this method returns detected objects on image with all the possible tags (similar to /tags endpoint) for largest object or picked one.

Things to note

  • Please, note that the "_base64" data is not returned. Use "_id" or any other field to identify your image.
  • Each of the tag contains probability of tag present on the image. All the tags are based on the main product type which is present in "Top category" and "Category" field. If you know these two fields, please specify it in each of the record.
  • All the tags are stored in field "_tags", only tags with probability > 30 % are returned
  • The field "_tags_simple" contains just list of strings (tag names) and is simpler than "_tags"
  • The field "_tags" and "_tags_simple" are stored in the first detected object
  • Maximum number of records/images that can be send to API in one request is 10.

Parameters:

  • records: list of photos to predict the tags for

    • must contain either of _url or _base64 field - see section image data for details
    • each record can contain Top Category and Category field which defines the main-category and sub-category of the product on the photo; for some images, it's not clear what object is the main (e.g. a model with a t-shirt and pants) and thus it's recommended to send over this information about Top category and Category (if known). For example: t-shirt "Top Category": "Clothing" and "Category": "Clothing/Upper"
    • if you want to get tags for specific object, then send the request with _objects field (list) with only this object
  • aggregate_labels: (optional) aggregate tags for the whole batch

    • true or false (default false)
    • if true, the records is considered as a batch of several photos of one object and after tagging the images separately, the tagger aggregates their tags into one output list of tags for the whole batch. Tags of individual images are not modified by this aggregation.
  • profile: (optional) if you know the id of your custom tagging profile, then this profile will apply on the _tags and transform it (rename tags/features, add tags, remove tags, ...)

$ curl https://api.ximilar.com/tagging/homedecor/v2/detect_tags -H "Content-Type: application/json" -H "Authorization: Token __API_TOKEN__" -d '{
    "records": [
        { "_url": "https://images.ximilar.com/examples/homedecor_real/5_Unsplash.jpg" }
    ]
}'

Returns:

  • HTTP error code 2XX, if the method was OK and other HTTP error code, if the method failed.
  • Body of the response is a JSON object (map) with the following fields:
    • status - a JSON map with a status of the method processing. It contains these subfields:
      • code - a numeric code of the operation status; it follows the concept of HTTP status codes (2XX, 4XX). Specific codes are described for each type of answer (or operation) (see below).
      • text - a text describing the status code
    • records - JSON array with the input records, each record enriched by field "_objects", this endpoint always return at least one object (if none was detected then it is created artificially with size of whole image).
CLICK TO SHOW JSON RESULT

{
  "records": [
    {
      "_url": "https://images.ximilar.com/examples/homedecor/11.webp",
      "region": "generic",
      "_status": {
        "code": 200,
        "text": "OK",
        "request_id": "e5727342-d336-4da0-8a3f-312ecbeeee6a"
      },
      "_id": "f285cc24-076c-4dca-8bc6-1a33aaa24052",
      "_width": 1035,
      "_height": 1380,
      "_objects": [
        {
          "name": "Furniture Set",
          "id": "63b75a7f-af12-4996-9262-76b65e9efebb",
          "bound_box": [
            12,
            300,
            899,
            1196
          ],
          "prob": 0.39538151025772095,
          "area": 0.5564321221031996,
          "expand_by_bound_box": [
            0,
            211,
            987,
            1285
          ],
          "Top Category": "Furniture",
          "Category": "Furniture/Furniture Set",
          "_tags": {
            "Category": [
              {
                "name": "Furniture/Furniture Set",
                "prob": 1,
                "id": "3094d4da-3392-4c80-9e7d-fc6f8b59c0a4",
                "pre-filled": true
              }
            ],
            "Subcategory": [
              {
                "prob": 0.95088,
                "name": "Kitchen set",
                "id": "12143686-bdf8-44ad-8ca3-1808939a1c90"
              }
            ],
            "Top Category": [
              {
                "name": "Furniture",
                "prob": 1,
                "id": "ff06c568-dd14-4fb7-9eae-1a0d3c1da115",
                "pre-filled": true
              }
            ]
          },
          "_tags_simple": [
            "Furniture",
            "Furniture/Furniture Set",
            "Kitchen set"
          ]
        }
      ]
    }
  ],
  "version": "",
  "model_format": "",
  "status": {
    "code": 200,
    "text": "OK",
    "request_id": "e5727342-d336-4da0-8a3f-312ecbeeee6a",
    "proc_id": "ae7ee797-e592-4d4b-bf88-58a1266fee3e"
  },
  "statistics": {
    "processing time": 2.421678066253662
  }
}

Tagging endpoint: /v2/tags

https://api.ximilar.com/tagging/homedecor/v2/tags

Given a list of image records, this method returns tags as predicted by the Furniture & Home-Decor Tagging services, together with probabilities (the level of certainty) for each of these tags.

Things to note

  • Please, note that the "_base64" data is not returned. Use "_id" or any other field to identify your image.
  • Each of the tag contains probability of tag present on the image. All the tags are based on the main product type which is present in "Top Category" field.
  • All the tags are stored in field "_tags", only tags with probability > 30 % are returne
  • The field "_tags_simple" contains just list of strings (tag names) and is simpler than "_tags"
  • Maximum number of records/images that can be send to API in one request is 10.

Multiple images for one furniture & home-decor product'?

Do you have multiple images for one home-decor product?

  • You can send 'aggregate_labels': true in the request and the labels will be aggregated for entire batch! Your results is then based on several images and not only one and it is stored _aggregation_simple and _aggregation fields!

Parameters:

  • records: list of photos to predict the tags for

    • must contain either of _url or _base64 field - see section image data for details
    • each record can contain Top Category field which defines the main-category of the product on the photo; for some images, it's not clear what object is the main and thus it's recommended to send over this information about Category (if known).
  • aggregate_labels: (optional) aggregate tags for the whole batch

    • true or false (default false)
    • if true, the records is considered as a batch of several photos of one object and after tagging the images separately, the tagger aggregates their tags into one output list of tags for the whole batch. Tags of individual images are not modified by this aggregation.
  • profile: (optional) if you know the id of your custom tagging profile, then this profile will apply on the _tags and transform it (rename tags/features, add tags, remove tags, ...)

$ curl https://api.ximilar.com/tagging/homedecor/v2/tags -H "Content-Type: application/json" -H "Authorization: Token __API_TOKEN__" -d '{
    "records": [
        { "_url": "https://bit.ly/2IymQJv" },
        {"_base64": "/9j/4AAQSkZJR...", "_id": "image_id"}
    ]
}'

Returns:

  • HTTP error code 2XX, if the method was OK and other HTTP error code, if the method failed.
  • Body of the response is a JSON object (map) with the following fields:
    • status - a JSON map with a status of the method processing. It contains these subfields:
      • code - a numeric code of the operation status; it follows the concept of HTTP status codes (2XX, 4XX). Specific codes are described for each type of answer (or operation) (see below).
      • text - a text describing the status code
    • records - JSON array with the input records, each record enriched by field "_tags" and "category"
    • _aggregation and _aggregation_simple if aggregate_labels set to true in request
CLICK TO SHOW JSON RESULT

{
  "records": [
    {
      "_url": "https://vize-images.s3.amazonaws.com/image/773e2ab1-2a0c-4524-9593-7395994faae1/46e875e4-e90e-4afa-aa4d-23b320ec6d7c.jpg",
      "_status": {
        "code": 200,
        "text": "OK",
        "request_id": "a24bc3ee-bbe2-40ff-b8a0-edeeb7d720c3"
      },
      "_width": 1000,
      "_height": 1000,
      "Top Category": "Furniture",
      "Category": "Furniture/Sitting",
      "_tags": {
        "Category": [
          {
            "prob": 0.99709,
            "name": "Furniture/Sitting",
            "id": "c397d929-5e29-4722-a98a-13629ae65677"
          }
        ],
        "Subcategory": [
          {
            "prob": 0.96032,
            "name": "Dining chair",
            "id": "1ab17573-78c2-4ccf-840e-93df756a5193"
          }
        ],
        "Top Category": [
          {
            "prob": 0.99406,
            "name": "Furniture",
            "id": "ff06c568-dd14-4fb7-9eae-1a0d3c1da115"
          }
        ]
      },
      "_tags_simple": [
        "Furniture",
        "Dining chair",
        "Furniture/Sitting"
      ]
    }
  ],
  "status": {
    "code": 200,
    "text": "OK",
  },
  "statistics": {
    "processing time": 0.8858194351196289
  }
}

Home-Decor detection endpoint: /v2/detect

https://api.ximilar.com/tagging/homedecor/v2/detect

Given a list of image records, this method returns detected homedecor objects on image with their category.

Things to note

  • For getting best results, use this endpoint if there are multiple homedecor items.
  • Please, note that the "_base64" data is not returned. Use "_id" or any other field to identify your image.
  • Homedecor objects, with exact location (bounding box) are stored in the '_objects' field.
  • Each of the tag and object contains probability of presence on the image.
  • All the tags are stored in field "_tags" within the first (largest) '_object', only tags with probability > 30 % are returned
  • The '_tags' field is returned only for the object with largest area, not probability!
  • The field "_tags_simple" contains just list of strings (tag names) and is simpler than "_tags"
  • Maximum number of records/images that can be send to API in one request is 10.
  • If you know the Top Category or Category, then please specify them in each of the record. This can improve the overall precision of returned results.
  • You can also send the object, simple create field '_objects' with one object (you will need to specify bound_box and Top Category)
  • This endpoint cannot aggregate results from multiple records.

Parameters:

  • records: list of photos to predict the tags for
    • must contain either of _url or _base64 field - see section image data for details

$ curl https://api.ximilar.com/tagging/homedecor/v2/detect -H "Content-Type: application/json" -H "Authorization: Token __API_TOKEN__" -d '{
    "records": [
        { "_url": "https://bit.ly/2IymQJv" },
        {"_base64": "/9j/4AAQSkZJR...", "_id": "image_id"}
    ]
}'

Returns:

  • HTTP error code 2XX, if the method was OK and other HTTP error code, if the method failed.
  • Body of the response is a JSON object (map) with the following fields:
    • status - a JSON map with a status of the method processing. It contains these subfields:
      • code - a numeric code of the operation status; it follows the concept of HTTP status codes (2XX, 4XX). Specific codes are described for each type of answer (or operation) (see below).
      • text - a text describing the status code
    • records - JSON array with the input records, each record enriched by field "_objects"
CLICK TO SHOW JSON RESULT

{
  "records": [
    {
      "_url": "https://images.ximilar.com/examples/homedecor/8.jpg",
      "_status": {
        "code": 200,
        "text": "OK",
        "request_id": "86ca41c7-b760-48c1-84df-5f59a21cd5d6"
      },
      "_id": "ee920142-edb5-4545-a9f4-41a3e0397932",
      "_width": 300,
      "_height": 300,
      "_objects": [
        {
          "name": "Textile accessories",
          "id": "02240abc-a136-4230-8fea-f0054ab8eac3",
          "bound_box": [
            0,
            67,
            283,
            287
          ],
          "prob": 0.5390826463699341,
          "area": 0.6917777777777778,
          "expand_by_bound_box": [
            0,
            45,
            299,
            299
          ],
          "Top Category": "Accessories",
          "Category": "Accessories/Textile"
        },
        {
          "name": "Relax",
          "id": "5bc71c4e-edc2-4216-a9d5-9a45ec00ea0a",
          "bound_box": [
            224,
            20,
            300,
            211
          ],
          "prob": 0.4882190525531769,
          "area": 0.1612888888888889,
          "expand_by_bound_box": [
            217,
            1,
            299,
            230
          ],
          "Top Category": "Furniture",
          "Category": "Furniture/Relax"
        }
      ]
    }
  ],
  "version": "2022-10-03 16:43:45.552643+00:00",
  "model_format": "",
  "status": {
    "code": 200,
    "text": "OK",
    "request_id": "86ca41c7-b760-48c1-84df-5f59a21cd5d6",
    "proc_id": "8b776662-7987-4b41-b0ca-4154bef2e842"
  },
  "statistics": {
    "processing time": 0.1509261131286621
  }
}

Feedback endpoint: /v2/feedback

https://api.ximilar.com/tagging/homedecor/v2/feedback

If you get some result from prediction endpoints (tags, ...) and you see some mistakes in assigned tags, feel free to send us an image via this endpoint. Please include in message field textual description what was wrong with analyzed result.

Parameters:

  • must contain either of url or base64 with url path of image or base64 data of image
  • message as textual description of what was wrongly analyzed

curl --request POST \
  --url https://api.ximilar.com/tagging/homedecor/v2/feedback \
  --header 'Authorization: Token __API_TOKEN__' \
  --header 'Content-Type: application/json' \
  --data '{
    "message": "__THE_MESSAGE__",
    "base64": "__BASE64_IMAGE__"
}'

Returns:

  • HTTP error code 200, if the method was OK and other HTTP error code, if the method failed.
  • Body of the response is a JSON object (map) with the following fields:
    • status - with message
CLICK TO SHOW JSON RESULT

{
    "status": "Your feedback has been submitted. Thank you!"
}