Text Search

Quickstart Articles & Guides Test in App Public Demo

To access the Ximilar API, first register at Ximilar App to get your API token. The API follows the general rules as described in the First Steps.

The Text Search API allows you to find images in your collection using natural language queries.

How It Works

To use the API:

Create a collection in Ximilar App, select a collection type based on your use case. You’ll get a unique collection ID to include in all requests.
Upload images — add records (image + metadata + _id). Processing and indexing run automatically. You can upload images via URL or _base64 data. We recommend to use URL because you will be able to visualize the results.
Search with text – Once set up, you can search your collection with text queries in any language — no additional metadata required.

Endpoints

Choose the endpoint based on collection type:

https://api.ximilar.com/similarity/text/photo/v2/text                 (Photo Similarity) 
https://api.ximilar.com/similarity/text/products/v2/text              (Product Similarity)
https://api.ximilar.com/similarity/text/fashion/v2/text               (Fashion Search)
https://api.ximilar.com/similarity/text/homedecor/v2/text             (Home Decor Search)

POST/v2/text

Text Search

Find images matching a given text query from your collection.

Required attributes

Name
collection-id
Type
string
Description
Your collection ID in the header.
Name
Authorization
Type
string
Description
Your API token in the format: Token YOUR_API_TOKEN.

Request parameters

Name
query_record
Type
object
Description
Record containing the text query to search by.
Name
query_record._text_data
Type
string
Description
The text query to search for images.
Name
k
Type
number
Default
Default:30
Description
Number of records to be returned, default: 30.
Name
from
Type
number
Default
Default:0
Description
Number of records to be skipped, default: 0.
Name
fields_to_return
Type
array
Description
Fields to be returned in every record, defaults to ["_id"].
Name
filter
Type
object
Description
Search will be applied only to records satisfying this filter.

Response fields

Name
query_records
Type
array
Description
The query record(s) copied from the request.
Name
answer_records
Type
array
Description
Records found matching the text query.
Name
answer_count
Type
number
Description
Number of returned records.
Name
answer_distances
Type
array
Description
Distances between query and individual records in answer_records.

Request

POST

/v2/text

curl 'https://api.ximilar.com/similarity/text/fashion/v2/text' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'collection-id: __COLLECTION_ID__' \
    -H 'Authorization: Token __API_TOKEN__' \
    -d '{
  "from": 0,
  "k": 10,
  "query_record": {
    "_text_data": "a yellow nike footwear"
  },
  "fields_to_return": ["_id", "_url"]
}'

Response

{
  "status": {
    "code": 200,
    "text": "OK"
  },
  "statistics": {
    "OperationTime": 150
  },
  "answer_records": [
    {
      "_id": "1",
      "_url": "https://example.com/image1.jpg"
    },
    {
      "_id": "2",
      "_url": "https://example.com/image2.jpg"
    }
  ],
  "answer_distances": [0.45, 0.52],
  "query_records": [
    {
      "_text_data": "a modern living room with white furniture and large windows"
    }
  ],
  "answer_count": 2
}