Fashion Search

QuickstartTaxonomyBlogTest in AppPublic Demo

To access the Ximilar API, first register at Ximilar App to get your API token. This API follows the general rules of Ximilar API as described in Section First steps.

With Fashion Search API, customers can upload images to retrieve visually similar fashion products from your catalog. The service combines visual search with Fashion Tagging and Dominant Colors.

It works with real-life photos, social media images, and screenshots, and supports both image-based and multilingual text-based search.

How It Works

To use the API:

  1. Create a collection in Ximilar App — you’ll get a unique collection ID to include in all requests.
  2. Insert products — add records (image + metadata + _id). Processing and indexing run automatically.
  3. 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 fashion apparel: 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/fashion-new/v2/insert        (insert images and metadata into collection)
https://api.ximilar.com/similarity/fashion-new/v2/visual_search (perform image-based search)
https://api.ximilar.com/similarity/text/fashion/v2/text         (perform text-based search)
POST/v2/insert

Synchronization

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

  1. Detect fashion items in the photo.
  2. Optionally analyze product colors and assign tags.
  3. Extract visual features (embedding) from the largest detected item.
  4. Store the embedding together with your metadata in the collection.

Your images are processed once and then discarded. Only the extracted features and metadata are stored for search.

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 Fashion Taxonomy.

  • Name
    records[].Category
    Type
    string
    Description

    Category according to Ximilar Fashion 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 Fashion 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/fashion-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": "Clothing",
      "Category": "Clothing/Pants",
      "extract_colors": true,
      "extract_tags": true,
      "_tags_simple": ["yellow", "stilleto", "women"]
    }
  ]
}'

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
Public Demo

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

  1. Detect all fashion items in the query photo
  2. 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 fashion 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/fashion-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": "Clothing",
          "Category": "Clothing/Jackets and Coats",
          "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/fashion/Clothing/Pullover/Knit sweater/v70kjnwe53sz4may/v70kjnwe53sz4may_1.jpg"
    }
  ],
  "answer_distances": [0.64635134],
  "answer_count": 1,
  "status": {
    "code": 200,
    "text": "OK"
  }
}
POST/v2/text

Text Search

How it works?

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/fashion/v2/text \
  --header 'authorization: Token __API_TOKEN__' \
  --header 'collection-id: __COLLECTION_ID__' \
  --header 'content-type: application/json' \
  --data '{
  "query_record": {
    "_text_data": "a blue pullover with white stripes pattern"
  },
  "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 Fashion 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 fashion item and use the Fashion 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": "Clothing",
      "Category": "Clothing/Pants"
    }
  ]
}

Search with Category Filtering

curl --location 'https://api.ximilar.com/similarity/fashion-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/footwearx.jpg",
    "Top Categories": ["Footwear", "Clothing"],
    "Categories": ["Clothing/Jackets and Coats", "Footwear/Pumps"],
    "Top Category": "Footwear"
  },
  "fields_to_return": [
    "_id",
    "_url"
  ],
  "k": 10,
  "cand_set_size": 5000
}'

Search With 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 fashion items and you want to focus on a specific one.

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

Workflow with Fashion Detection

You can combine the Fashion Detection and the visual search as follows:

  1. Call the Fashion Detection method to detect all fashion items in the photo (without immediately retrieving similar products).
  2. Let the user select the item they are interested in.
  3. Use the selected object’s JSON record in a subsequent visual search query.

Mobile App Integration

If you want to integrate fashion 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/fashion-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": "Clothing",
        "Category": "Clothing/Pants",
        "bound_box": [349, 23, 646, 378]
      }
    ]
  },
  "fields_to_return": ["_id", "_url", "product_id"]
}'

Python Example

from ximilar.client.search import SimilarityFashionClient

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

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

Mobile App Example

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

Was this page helpful?