Home Decor Tagging

Quickstart Taxonomy Blog Test in APP Public Demo

The Home Decor Tagging service provides categories, sub-categories and various tags for Home Decor product images.

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 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)

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. * 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" * Maximum number of records/images that can be send to API in one request is 10. * This service can return results (tags) translated in your language if needed, simply contact us at care@ximilar.com for more information and available translations. If some translation is not available than our team can build it for you.

Taxonomy

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

HOME DECOR TAXONOMY TREE

Endpoints

This service API has several endpoints running at URLs:

https://api.ximilar.com/tagging/homedecor/v2/top_categories  (for getting list of top categories)
https://api.ximilar.com/tagging/homedecor/v2/detect_tags     (for detecting objects and their tags)
https://api.ximilar.com/tagging/homedecor/v2/detect_tags_all (for detecting all objects and their tags)
https://api.ximilar.com/tagging/homedecor/v2/tags            (for basic tagging)
https://api.ximilar.com/tagging/homedecor/v2/detect          (for object detection)
https://api.ximilar.com/tagging/homedecor/v2/feedback        (for sending feedback)

GET/v2/top_categories

List of Top Categories and Categories

Quickstart

Returns list of top categories and their subcategories.

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:

Name
status
Type
dict
Description
A JSON map/dictionary with a status of the method processing. It contains these subfields: code (numeric code of the operation status; it follows the concept of HTTP status codes) and text (text describing the status code).

Request

GET

/v2/top_categories

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

Response

{
  "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"
  ]
}

POST/v2/detect_tags

Home Decor Detection and Tags

Quickstart

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.

The field "_tags" and "_tags_simple" are stored in the first detected object
If you know the Top Category and Category, please specify them in each of the record to improve accuracy

Required attributes

Name
records
Type
dict
Description
A batch of json records (max 10), one record is representation of an image and it's defined by _url or _base64.

Optional attributes

Name
aggregate_labels
Type
boolean
Default
Default:false
Description
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.
Name
profile
Type
string
Description
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, ...)
Name
language
Type
string
Description
Language code for tag translations. For more info please contact us at care@ximilar.com

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:

Name
records
Type
dict
Description
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).
Name
status
Type
dict
Description
A JSON map/dictionary with a status of the method processing. It contains these subfields: code (numeric code of the operation status; it follows the concept of HTTP status codes) and text (text describing the status code).

Request

POST

/v2/detect_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" }
  ]
}'

Response

{
  "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_map": {
            "Top Category": "Furniture",
            "Category": "Furniture/Furniture Set",
            "Subcategory": "Kitchen set"
          },
          "_tags_simple": [
            "Furniture",
            "Furniture/Furniture Set",
            "Kitchen set"
          ]
        }
      ]
    }
  ],
  "status": {
    "code": 200,
    "text": "OK",
    "request_id": "e5727342-d336-4da0-8a3f-312ecbeeee6a",
    "proc_id": "ae7ee797-e592-4d4b-bf88-58a1266fee3e"
  },
  "statistics": {
    "processing time": 2.421678066253662
  }
}

POST/v2/detect_tags_all

Detect All Objects and Tags

Quickstart

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

The field "_tags" and "_tags_simple" are stored in the first detected object
If you know the Top Category and Category, please specify them in each of the record to improve accuracy

Required attributes

Name
records
Type
dict
Description
A batch of json records (max 10), one record is representation of an image and it's defined by _url or _base64.

Optional attributes

Name
profile
Type
string
Description
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, ...)
Name
language
Type
string
Description
Language code for tag translations. For more info please contact us at care@ximilar.com

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:

Name
records
Type
dict
Description
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).
Name
status
Type
dict
Description
A JSON map/dictionary with a status of the method processing. It contains these subfields: code (numeric code of the operation status; it follows the concept of HTTP status codes) and text (text describing the status code).

Request

POST

/v2/detect_tags_all

curl https://api.ximilar.com/tagging/homedecor/v2/detect_tags_all -H "Content-Type: application/json" -H "Authorization: Token __API_TOKEN__" -d '{
  "records": [
    { "_url": "https://images.ximilar.com/examples/homedecor/2.jpeg" }
  ]
}'

Response

{
  "records": [
    {
      "_url": "https://images.ximilar.com/examples/homedecor/2.jpeg",
      "region": "generic",
      "_status": {
        "code": 200,
        "text": "OK",
        "request_id": "3ada7775-a2f7-4577-8109-8f3111140e2b"
      },
      "_id": "49b6cea9-7683-488d-acdf-14bc4ea9416a",
      "_width": 1024,
      "_height": 887,
      "_objects": [
        {
          "name": "Mirrors & Frames",
          "id": "433fd8c0-3ad4-4a47-bb63-07760fb5fc3b",
          "bound_box": [343, 3, 496, 154],
          "prob": 0.7158277630805969,
          "area": 0.025435764867531005,
          "expand_by_bound_box": [328, 0, 511, 169],
          "Top Category": "Accessories",
          "Category": "Accessories/Mirrors & Frames",
          "_tags": {
            "Category": [
              {
                "id": "27dd7b55-78c4-45a2-8721-22e93d69f1c3",
                "name": "Accessories/Mirrors & Frames",
                "prob": 1.0
              }
            ],
            "Subcategory": [
              {
                "prob": 0.72697,
                "name": "frame",
                "id": "4851d369-1d77-4d69-9f0d-f3ea107d9307"
              }
            ],
            "Material": [
              {
                "prob": 0.96967,
                "name": "Accessories/Textile",
                "id": "a3ae94de-ea36-4851-b558-76e80cb626b2"
              }
            ],
            "Shape": [
              {
                "prob": 0.91281,
                "name": "square",
                "id": "6d6d96c5-0dc1-4b69-b606-a62cb605d99c"
              }
            ],
            "Top Category": [
              {
                "id": "7c042069-8e9e-4905-82c2-90ca5882ecab",
                "name": "Accessories",
                "prob": 1.0
              }
            ]
          },
          "_tags_map": {
            "Top Category": "Accessories",
            "Category": "Accessories/Mirrors & Frames",
            "Subcategory": "frame",
            "Material": "Accessories/Textile",
            "Shape": "square"
          },
          "_tags_simple": [
            "Accessories",
            "square",
            "frame",
            "Accessories/Textile",
            "Accessories/Mirrors & Frames"
          ]
        }
      ]
    }
  ],
  "status": {
    "code": 200,
    "text": "OK",
    "request_id": "3ada7775-a2f7-4577-8109-8f3111140e2b",
    "proc_id": "f6b2b598-feb2-4c5b-8541-f90cef96069f"
  },
  "statistics": {
    "processing time": 0.8162112236022949
  }
}

POST/v2/tags

Tagging

Quickstart

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

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!

Required attributes

Name
records
Type
dict
Description
A batch of json records (max 10), one record is representation of an image and it's defined by _url or _base64.

Optional attributes

Name
aggregate_labels
Type
boolean
Default
Default:false
Description
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.
Name
profile
Type
string
Description
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, ...)
Name
language
Type
string
Description
Language code for tag translations. For more info please contact us at care@ximilar.com

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:

Name
records
Type
dict
Description
JSON array with the input records, each record enriched by field "_tags" and "category"
Name
status
Type
dict
Description
A JSON map/dictionary with a status of the method processing. It contains these subfields: code (numeric code of the operation status; it follows the concept of HTTP status codes) and text (text describing the status code).
Name
_aggregation
Type
dict
Description
Aggregated tags for the whole batch if aggregate_labels is set to true
Name
_aggregation_simple
Type
dict
Description
Simplified aggregated tags for the whole batch if aggregate_labels is set to true

Request

POST

/v2/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"}
  ]
}'

Response

{
  "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_map": {
        "Top Category": "Furniture",
        "Category": "Furniture/Sitting",
        "Subcategory": "Dining chair"
      },
      "_tags_simple": [
        "Furniture",
        "Dining chair",
        "Furniture/Sitting"
      ]
    }
  ],
  "status": {
    "code": 200,
    "text": "OK"
  },
  "statistics": {
    "processing time": 0.8858194351196289
  }
}

POST/v2/detect

Home Decor Detection

Quickstart

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

Required attributes

Name
records
Type
dict
Description
A batch of json records (max 10), one record is representation of an image and it's defined by _url or _base64.

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:

Name
records
Type
dict
Description
JSON array with the input records, each record enriched by field "_objects"
Name
status
Type
dict
Description
A JSON map/dictionary with a status of the method processing. It contains these subfields: code (numeric code of the operation status; it follows the concept of HTTP status codes) and text (text describing the status code).

Request

POST

/v2/detect

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"}
  ]
}'

Response

{
  "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"
        }
      ]
    }
  ],
  "status": {
    "code": 200,
    "text": "OK",
    "request_id": "86ca41c7-b760-48c1-84df-5f59a21cd5d6",
    "proc_id": "8b776662-7987-4b41-b0ca-4154bef2e842"
  },
  "statistics": {
    "processing time": 0.1509261131286621
  }
}