Visual Search – Overview & Basics

Quickstart Blog Test in App Public Demo

To access the Ximilar Visual Search API, first register at Ximilar App to get your API token. To browse and test available solutions, select "Visual Search" in the app. A limited public demo is also available.

This page describes the Visual Search API, which allows you to find visually similar images within your collection using AI-powered vector search technology. The API follows the general rules of Ximilar API as described in the First Steps section.

How It Works

The Visual Search service follows this process:

Create a collection: Start by creating a collection (your image database) in Ximilar App. Different collection types support different use cases.
Upload images: Add (insert) images to your collection using the API via URL or Base64. Tip: URLs are preferred for easier result visualization.
Search similar images: Once your collection is populated, use the Visual Search API to find visually similar images.

The system uses advanced AI to:

Extract visual descriptors (embeddings) from your images using neural networks
Index these descriptors for high-speed retrieval
Perform fast similarity search across millions of images
Support metadata-based filtering to refine the results

Once images are uploaded, the system handles processing and indexing automatically — your only task is to keep the collection updated.

The service is highly customizable and can be extended with:

Custom tags and metadata
Additional image recognition models
Advanced filtering capabilities
Integration with your existing systems

The service supports batch operations, allowing up to 10 records per request when inserting images. For optimal performance and ease of use, we recommend using our Python client library, available on GitLab and PyPI.

Endpoints

Each service has a different API endpoint, depending on the collection type or use case:

https://api.ximilar.com/similarity/photos/v2/[method]             (Photo Similarity)
https://api.ximilar.com/image_matching/v2/[method]                (Image Matching)
https://api.ximilar.com/similarity/products-new/v2/[method]       (Product Similarity)
https://api.ximilar.com/similarity/custom/v2/[method]             (Custom Similarity)
https://api.ximilar.com/similarity/fashion-new/v2/[method]        (Fashion Search)
https://api.ximilar.com/similarity/colors/v2/[method]             (Dominant Colors Similarity)
https://api.ximilar.com/similarity/homedeco-newr/v2/[method]      (Furniture & Home Decor Search)

For example, if you created a Fashion Search collection via app.ximilar.com, you should use the following endpoint to insert images:

https://api.ximilar.com/similarity/fashion-new/v2/insert

These old endpoints are deprecated and will be removed in the future:

https://api.ximilar.com/photo/search/v2/[method]                  (Photo Similarity – Old)
https://api.ximilar.com/similarity/products/v2/[method]           (Product Similarity – Old)
https://api.ximilar.com/similarity/fashion/v2/[method]            (Fashion Search – Old)
https://api.ximilar.com/similarity/homedecor/v2/[method]          (Furniture & Home Decor Search – Old)

API Methods Overview

All operations are performed on your image collection, identified by the collection-id header in each API call. Your collections must be created by Ximilar administrators before use.

All API methods use the POST method, require a JSON object in the request body (JSON map), and return another JSON record as a response. Here’s an example of a typical API request:

Example Request

curl https://api.ximilar.com/photo/search/v2/visualKNN \
-H 'Authorization: Token YOUR_API_TOKEN' \
-H 'collection-id: YOUR-COLLECTION-ID' \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{
   "query_record": { "_id": "11959" },
   "k": 3,
   "filter": { "artist": { "$ne": "david_27" } }
}'

Available Methods

The following methods are currently available:

Basic Operations

/v2/ping – get basic information about the running index
/v2/insert – insert a new batch of records into the index
/v2/delete – delete records by their IDs from the index
/v2/get – retrieve a full list of records by their IDs
/v2/find – search for records matching a given filter
/v2/update – update attributes (additional fields) of records by their IDs
/v2/nearDupsInsert – insert records while checking for near-duplicate images

Search Operations

/v2/visualKNN – find visually similar images from the collection to a given image
/v2/visualTagsKNN – find images similar by visual features and tags
/v2/visualKNNMulti – find images visually similar to a given list of images
/v2/visualTagsKNNMulti – find images similar to a list using visual and tag data

Ranking Operations

/v2/visualRankRecords – ranks a list of records by visual similarity to a query image
/v2/visualTagsRankRecords - ranks records by combined visual and tag similarity

Collection Management

/v2/random – returns a specified number of random records from the collection
/v2/getRecordCount – returns the total number of records in the collection
/v2/allRecords – retrieves all records (or just their IDs) from the collection
/v2/deleteByFilter – deletes records matching a given filter condition

Advanced Operations

/v2/range – finds images visually similar to a query image within a specified radius
/v2/nearDuplicates – detects images that are exact or near duplicates of the query image
/v2/allNearDupPairs – finds all mutually similar or duplicate image pairs in the collection

Data Record Format

The Ximilar Search API works with JSON records. Each record (JSON object) represents one image and its metadata, and includes the following fields:

Name
_id
Type
string
Description
Unique identifier of the record within the collection.
Name
_file
Type
string
Description
Name of a PNG, JPG, or TIFF file on local storage.
Name
_url
Type
string
Description
URL to a PNG, JPG, or TIFF image file.
Name
_base64
Type
string
Description
Base64-encoded content of a PNG, JPG or TIFF image file.
Name
tags
Type
array
Description
JSON array (list) of string keywords (tags) describing the image.
Name
_attribute_
Type
any
Description
Custom attributes in JSON format; used for filtering and metadata storage.

You can include extra fields in your records to help with filtering or retrieving data later. These fields can be used in the filter parameter during search operations.

{
  "_id": "321",
  "_url": "https://yourdomain.com/images/product_image_321.jpg",
  "category": "apparel",
  "tags": ["dresses", "short", "polka dot"],
  "seller": "shop_543",
  "price": 35.5,
  "active": true
}

API Methods

Common Parameters

Name
query_record
Type
object
Description
One data record used for querying, e.g., {"_id": "54321"} or {"_url": "http://example.com/myqueryimage.png"}.
Name
k
Type
integer
Default
Default:20
Description
Number of similar records to be returned.
Name
from
Type
integer
Default
Default:0
Description
Number of records to skip from the beginning of results.
Name
records
Type
array
Description
JSON array of data records.
Name
fields_to_return
Type
array
Description
List of data record fields to be returned by the operation.
Name
filter
Type
object
Description
Search condition using MongoDB-style query syntax.

The radius and approx_param parameters are advanced options. Use them only if you fully understand their function.

Response Format

All methods return:

HTTP status code (2XX for success, other codes for errors)
JSON-formatted response body containing:
- status object with code and text
- statistics object with OperationTime (processing time in milliseconds)
- Operation-specific response data

For detailed information on each endpoint, including request and response examples as well as specific parameters, see their respective documentation sections.

GET/v2/ping

Ping

Returns basic information about the index.

Returns

HTTP status code 2XX if the request was successful; otherwise, an appropriate HTTP error code. The response body is a JSON object (map) with the following field:

Name
status
Type
dict
Description
A JSON object containing the processing status, with these subfields: code (numeric status code, aligned with HTTP status codes) and text (a descriptive message explaining the status code).
Name
statistics
Type
dict
Description
A map of various statistics about the processing, including OperationTime (time of actual processing in milliseconds).
Name
info
Type
string
Description
A description of the index type and purpose.

Request

GET

/v2/ping

curl 'https://api.ximilar.com/photo/search/v2/ping' -i -X GET

Response

{
  "status": {
    "code": 200,
    "text": "OK"
  },
  "statistics": {
    "OperationTime": 0
  },
  "info": "Java index for clothing objects in Smart Product Search"
}

POST/v2/insert

Insert

Insert a given list of records (images + metadata) into the index (max 10 records per request).

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
records
Type
array
Max
Maximum:10
Description
Records to be inserted, maximum 10 records per request.
Name
fields_to_return
Type
array
Description
List of strings, these fields are returned, defaults to ["_id"].
Name
records[]._url
Type
string
Description
Image specified by URL.
Name
records[]._base64
Type
string
Description
Image encoded as base64.
Name
records[].any_field
Type
string
Description
The image records can contain any additional fields that can be used to filter search results.
Name
records[].tags
Type
array
Description
Records can contain field with any string tags (labels); can be used for filtering and see method /v2/visualTagsKNN.

Response fields

Name
status
Type
object
Description
Status description.
Name
skipped_records
Type
array
Description
Records that were skipped, usually because of duplicate _id.
Name
answer_records
Type
array
Description
Successfully inserted records.

Possible status values

Name
210
Type
object
Description
All records inserted: "status": {"code": 210, "text": "records inserted"}.
Name
211
Type
object
Description
Some records inserted: "status": {"code": 211, "text": "some records inserted"} – Indicates that some records were inserted successfully while others were rejected, typically because a record with the same _id already exists. The response field answer_records contains the list of records that were successfully inserted, while skipped_records contains records not inserted.
Name
411
Type
object
Description
All records refused: "status": {"code": 411, "text": "record duplicate"} – all records refused because of _id duplicity.
Name
412
Type
object
Description
Capacity exceeded: "status": {"code": 412, "text": "hard capacity exceeded"} – records refused because of storage capacity exceeded.

Request

POST

/v2/insert

curl 'https://api.ximilar.com/photo/search/v2/insert' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'collection-id: __COLLECTION_ID__' \
    -H 'Authorization: Token __API_TOKEN__' \
    -d '{
  "fields_to_return": ["_id"],
  "records": [
    {
      "_id": "1",
      "_url": "http://mydomain.com/img.png"
    },
    {
      "_base64": "data:image/png;base64,ABC...",
      "_id": "2",
      "tags": ["label1", "label2", "label3"]
    },
    {
      "_id": "3",
      "_url": "http://mydomain.com/another_image.jpg",
      "any_field": "for filtering",
      "price": 300
    }
  ]
}'

Response

{
  "status": {
    "code": 211,
    "text": "record(s) duplicate"
  },
  "statistics": {
    "OperationTime": 4
  },
  "answer_records": [
    {
      "_id": "1"
    },
    {
      "_id": "2"
    }
  ],
  "skipped_records": [
    {
      "_id": "3",
      "_reason": {
        "status": {
          "code": 211,
          "text": "record(s) duplicate"
        }
      }
    }
  ],
  "answer_count": 2
}

POST/v2/delete

Delete

Deletes a given list of records (identified by _id) from the index.

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
records
Type
array
Description
Records to be deleted by their _id.

Response fields

Name
answer_records
Type
array
Description
Successfully deleted records.
Name
skipped_records
Type
array
Description
Records that couldn't be deleted.
Name
answer_count
Type
number
Description
Number of deleted records.

Possible status values

Name
220
Type
object
Description
All records deleted: "status": {"code": 220, "text": "records deleted"}.
Name
206
Type
object
Description
Some records not found: "status": {"code": 206, "text": "some of the records not found"} – some of the records were not deleted. Field answer_records contains list of records actually deleted, and skipped_records contains the list of records not found.
Name
404
Type
object
Description
No records found: "status": {"code": 404, "text": "records not found"} – none of the requested records were found and deleted.

Request

POST

/v2/delete

curl 'https://api.ximilar.com/photo/search/v2/delete' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'collection-id: __COLLECTION_ID__' \
    -H 'Authorization: Token __API_TOKEN__' \
    -d '{
  "records" : [ {
    "_id" : "1"
  }, {
    "_id" : "2"
  }, {
    "_id" : "3"
  } ]
}'

Response

{
  "status": {
    "code": 213,
    "text": "some of the records not found"
  },
  "statistics": {
    "OperationTime": 2
  },
  "answer_records": [
    {
      "_id": "1"
    },
    {
      "_id": "2"
    }
  ],
  "skipped_records": [
    {
      "_id": "3",
      "_reason": {
        "status": {
          "code": 404,
          "text": "records not found"
        }
      }
    }
  ],
  "answer_count": 2
}

POST/v2/get

Get

Finds and returns a given list of records (identified by _id) from the index.

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
records
Type
array
Description
Records to be returned, identified by their _id.
Name
fields_to_return
Type
array
Description
Fields to be returned in every record, defaults to ["*"].

Response fields

Name
answer_records
Type
array
Description
Records found.
Name
skipped_records
Type
array
Description
Records that couldn't be returned.
Name
answer_count
Type
number
Description
Number of records found.

Possible status values

Name
205
Type
object
Description
All records found: "status": {"code": 205, "text": "records found"} – all records found and returned.
Name
206
Type
object
Description
Some records not found: "status": {"code": 206, "text": "some of the records not found"} – some of the records are returned, the rest has not been found.
Name
404
Type
object
Description
No records found: "status": {"code": 404, "text": "records not found"} – none of the requested records were found and empty answer is returned.

Request

POST

/v2/get

curl 'https://api.ximilar.com/photo/search/v2/get' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'collection-id: __COLLECTION_ID__' \
    -H 'Authorization: Token __API_TOKEN__' \
    -d '{
  "fields_to_return" : [ "*" ],
  "records" : [ {
    "_id" : "1"
  }, {
    "_id" : "2"
  }, {
    "_id" : "3"
  } ]
}'

Response

{
  "status": {
    "code": 213,
    "text": "some of the records not found"
  },
  "statistics": {
    "OperationTime": 10
  },
  "answer_records": [
    {
      "_id": "1",
      "_url": "http://mydomain.com/img.png"
    },
    {
      "_file": "/path/to/img.png",
      "_id": "2"
    }
  ],
  "skipped_records": [
    {
      "_id": "3",
      "_reason": {
        "status": {
          "code": 404,
          "text": "records not found"
        }
      }
    }
  ],
  "answer_count": 2
}

POST/v2/find

Find

Searches and returns all records that match the specified filter criteria.

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
filter
Type
object
Description
Search will be applied only to records satisfying this filter.
Name
limit
Type
number
Default
Default:10
Description
Number of records to be returned. 10 by default.
Name
fields_to_return
Type
array
Description
Fields to be returned in every record, defaults to ["*"].

Response fields

Name
answer_records
Type
array
Description
Updated records.
Name
answer_count
Type
number
Description
Number of returned records.

Request

POST

/v2/find

curl 'https://api.ximilar.com/photo/search/v2/find' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'collection-id: __COLLECTION_ID__' \
    -H 'Authorization: Token __API_TOKEN__' \
    -d '{
  "fields_to_return" : [ "_id", "_url" ],
  "filter" : {
    "$gte" : {
      "price" : 200
    }
  },
  "limit" : 3
}'

Response

{
  "status": {
    "code": 200,
    "text": "OK"
  },
  "statistics": {
    "OperationTime": 13
  },
  "answer_records": [
    {
      "_id": "1",
      "_url": "http://my-website.com/1.png"
    },
    {
      "_id": "2",
      "_url": "http://my-website.com/2.png"
    },
    {
      "_id": "3",
      "_url": "http://my-website.com/3.png"
    }
  ],
  "answer_count": 3
}

POST/v2/update

Update

Updates the attributes of existing records in the index, identified by their _id. To remove a field (attribute), set its value to null, e.g. "field": null.

You can only update additional metadata fields used for filtering (including tags) — not the image itself. To modify the image, delete the record and insert it again.

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
records
Type
array
Description
Records to be updated, identified by their _id + fields to be updated; use "field": null if you want to remove field.
Name
fields_to_return
Type
array
Description
Fields to be returned in every record, defaults to ["*"].

Response fields

Name
answer_records
Type
array
Description
Updated records.
Name
skipped_records
Type
array
Description
Records that couldn't be updated.
Name
answer_count
Type
number
Description
Number of records updated.

Possible status values

Name
205
Type
object
Description
All records found: "status": {"code": 205, "text": "records found"} – all records found and returned.
Name
206
Type
object
Description
Some records not found: "status": {"code": 206, "text": "some of the records not found"} – some of the records are returned, the rest has not been found.
Name
404
Type
object
Description
No records found: "status": {"code": 404, "text": "records not found"} – none of the requested records were found and empty answer is returned.

Request

POST

/v2/update

curl 'https://api.ximilar.com/photo/search/v2/update' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'collection-id: __COLLECTION_ID__' \
    -H 'Authorization: Token __API_TOKEN__' \
    -d '{
  "fields_to_return" : [ "*" ],
  "records" : [ {
    "_id" : "1",
    "day" : "monday"
  }, {
    "_id" : "2",
    "day" : "tuesday"
  }, {
    "_id" : "3",
    "day" : "wednesday"
  } ]
}'

Response

{
  "status": {
    "code": 213,
    "text": "some of the records not found"
  },
  "statistics": {
    "OperationTime": 2
  },
  "answer_records": [
    {
      "another-field": "another-value",
      "day": "monday",
      "_id": "1"
    },
    {
      "_id": "2",
      "day": "tuesday"
    }
  ],
  "skipped_records": [
    {
      "_id": "3",
      "_reason": {
        "status": {
          "code": 404,
          "text": "records not found"
        }
      }
    }
  ],
  "answer_count": 2
}

POST/v2/nearDupsInsert

Near Duplicates Insert

Inserts a list of records (images + metadata) into the index only if they are not near-duplicates of existing records. Uses the same duplicate-checking logic as the /v2/nearDuplicates method. If a record is skipped due to a detected near-duplicate, it will appear in skipped_records with a status explanation similar to the one returned by /v2/nearDuplicates. Returns a standard data processing response, same as /v2/insert.

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
records
Type
array
Description
Records to be updated, identified by their _id.
Name
fields_to_return
Type
array
Description
Fields to be returned in every record, defaults to ["*"].
Name
radius
Type
number
Default
Default:5.0
Description
Maximum distance for records to be considered near duplicates. Defaults to 5.0.
Name
cand_set_size
Type
number
Description
Internal parameter (please do not modify). It can affect the operation's response time: lower values may be faster but could reduce accuracy. Each collection has its own default value.

Response fields

Name
answer_records
Type
array
Description
Updated records.
Name
skipped_records
Type
array
Description
Records that couldn't be updated.
Name
skipped_records[]._reason.answer_records
Type
array
Description
In case the method 'nearDupsInsert' was used, this is the list of near-duplicate records.
Name
skipped_records[]._reason.answer_distances
Type
array
Description
In case method 'nearDupsInsert' was used, this is list of distances to near-duplicates.
Name
answer_count
Type
number
Description
Number of records updated.

Request

POST

/v2/nearDupsInsert

curl 'https://api.ximilar.com/photo/search/v2/nearDupsInsert' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'collection-id: __COLLECTION_ID__' \
    -H 'Authorization: Token __API_TOKEN__' \
    -d '{
  "cand_set_size" : 1000,
  "fields_to_return" : [ "_id" ],
  "radius" : 5.0,
  "records" : [ {
    "_id" : "1",
    "_url" : "http://mydomain.com/img.png"
  }, {
    "_base64" : "data:image/png;base64,ABC...",
    "_id" : "2"
  }, {
    "_id" : "3",
    "_url" : "http://mydomain.com/another_image.jpg"
  } ]
}'

Response

{
  "status": {
    "code": 211,
    "text": "record(s) duplicate"
  },
  "statistics": {
    "OperationTime": 4
  },
  "answer_records": [
    {
      "_id": "1"
    }
  ],
  "skipped_records": [
    {
      "_id": "3",
      "_reason": {
        "status": {
          "code": 211,
          "text": "record(s) duplicate"
        },
        "answer_records": [
          {
            "_id": "10"
          }
        ],
        "answer_distances": [3.0]
      }
    },
    {
      "_id": "2",
      "_reason": {
        "status": {
          "code": 211,
          "text": "record(s) duplicate"
        }
      }
    }
  ],
  "answer_count": 1
}

POST/v2/visualKNN

Visual KNN

Use this endpoint to find visually similar images to a given image from the 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 to search by.
Name
k
Type
number
Default
Default:30
Description
Number of records to be returned, default: 30.
Name
from
Type
number
Default
Default:0
Description
The number of records to be skipped, defaults to 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. The filter is written in MongoDB syntax: see documentation.
Name
product_field
Type
string
Description
If set, each record in the response will be different product. Every collection has its own by default.
Name
cand_set_size
Type
number
Description
Internal parameter (please do not modify). It can affect the operation's response time: lower values may be faster but could reduce accuracy. Each collection has its own default value.

Response fields

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

Request

POST

/v2/visualKNN

curl 'https://api.ximilar.com/photo/search/v2/visualKNN' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'collection-id: __COLLECTION_ID__' \
    -H 'Authorization: Token __API_TOKEN__' \
    -d '{
  "cand_set_size" : 1000,
  "fields_to_return" : [ "_id" ],
  "filter" : {
    "$gte" : {
      "price" : 200
    }
  },
  "from" : 0,
  "k" : 3,
  "product_field" : "product_id",
  "query_record" : {
    "_url" : "http://mydomain.com/my-image.png"
  }
}'

Response

{
  "status": {
    "code": 200,
    "text": "OK"
  },
  "statistics": {
    "OperationTime": 1
  },
  "answer_records": [
    {
      "_id": "1"
    },
    {
      "_id": "2"
    },
    {
      "_id": "3"
    }
  ],
  "answer_distances": [40.0, 50.0, 60.0],
  "query_records": [
    {
      "_url": "http://mydomain.com/my-image.png"
    }
  ],
  "answer_count": 3
}

POST/v2/visualTagsKNN

Visual Tags KNN

Finds images that are similar based on a combination of visual features and keyword similarity. The keywords must be stored in a specific JSON array field within each record, and in the query record. The field name depends on the similarity service:

– photo similarity (real-life and stock photos) – tags – product photo similarity (packshots) – _tags_simple – fashion similarity – _tags_simple (the field is generated automatically by the Fashion Tagging service) – custom similarity – _tags

All parameters and the answer are the same as for /v2/visualKNN.

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
The input record used for the search. It must include the appropriate tags field based on your similarity service (see above).
Name
k
Type
number
Default
Default:30
Description
Number of records to be returned, default: 30.
Name
from
Type
number
Default
Default:0
Description
The number of records to be skipped, defaults to 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. The filter is written in MongoDB syntax: see documentation.
Name
product_field
Type
string
Description
If set, each record in the response will be different product. Every collection has its own by default.
Name
cand_set_size
Type
number
Description
Internal parameter (please do not modify). It can affect the operation's response time: lower values may be faster but could reduce accuracy. Each collection has its own default value.

Response fields

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

Request

POST

/v2/visualTagsKNN

curl 'https://api.ximilar.com/photo/search/v2/visualTagsKNN' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'collection-id: __COLLECTION_ID__' \
    -H 'Authorization: Token __API_TOKEN__' \
    -d '{
  "cand_set_size" : 1000,
  "fields_to_return" : [ "_id" ],
  "filter" : {
    "$gte" : {
      "price" : 200
    }
  },
  "from" : 0,
  "k" : 3,
  "product_field" : "product_id",
  "query_record" : {
    "_url" : "http://mydomain.com/my-image.png",
    "tags" : ["summer", "beach", "sunset"]
  }
}'

Response

{
  "status": {
    "code": 200,
    "text": "OK"
  },
  "statistics": {
    "OperationTime": 1
  },
  "answer_records": [
    {
      "_id": "1"
    },
    {
      "_id": "2"
    },
    {
      "_id": "3"
    }
  ],
  "answer_distances": [40.0, 50.0, 60.0],
  "query_records": [
    {
      "_url": "http://mydomain.com/my-image.png",
      "tags": ["summer", "beach", "sunset"]
    }
  ],
  "answer_count": 3
}

POST/v2/visualKNNMulti

Visual KNN Multi

Find visually similar images from your collection to a given list of images (multi-query).

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_records
Type
array
Description
Records to search by.
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, defaults to 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.
Name
cand_set_size
Type
number
Description
Internal parameter (please do not modify). It can affect the operation's response time: lower values may be faster but could reduce accuracy. Each collection has its own default value.

Response fields

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

Request

POST

/v2/visualKNNMulti

curl 'https://api.ximilar.com/photo/search/v2/visualKNNMulti' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'collection-id: __COLLECTION_ID__' \
    -H 'Authorization: Token __API_TOKEN__' \
    -d '{
  "cand_set_size" : 1000,
  "fields_to_return" : [ "_id" ],
  "filter" : {
    "$gte" : {
      "price" : 200
    }
  },
  "from" : 0,
  "k" : 3,
  "query_records" : [ {
    "_id" : "10"
  }, {
    "_id" : "11"
  } ]
}'

Response

{
  "status": {
    "code": 200,
    "text": "OK"
  },
  "statistics": {
    "OperationTime": 5
  },
  "answer_records": [
    {
      "_id": "1"
    },
    {
      "_id": "2"
    },
    {
      "_id": "3"
    }
  ],
  "answer_distances": [40.0, 50.0, 60.0],
  "query_records": [
    {
      "_id": "10"
    },
    {
      "_id": "11"
    }
  ],
  "answer_count": 3
}

POST/v2/visualTagsKNNMulti

Visual Tags KNN Multi

Find images that are similar to a given list of images based on combination of visual and tags similarity.

The tag field name differs depending on similarity services:

– generic photo similarity – tags – product photo similarity – _tags_simple – fashion similarity – _tags_simple (the field is generated automatically by the Fashion Tagging service) – custom similarity – _tags

All parameters and the answer are the same as for /v2/visualKNNMulti.

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_records
Type
array
Description
Records to be search by, must contain the appropriate tags field for your service type
Name
k
Type
number
Description
Number of records to be returned, default: 30
Name
from
Type
number
Description
The number of records to be skipped, defaults to 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
Name
cand_set_size
Type
number
Description
Internal parameter (please do not modify). It can affect the operation's response time: lower values may be faster but could reduce accuracy. Each collection has its own default value.

Response fields

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

Request

POST

/v2/visualTagsKNNMulti

curl 'https://api.ximilar.com/photo/search/v2/visualTagsKNNMulti' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'collection-id: __COLLECTION_ID__' \
    -H 'Authorization: Token __API_TOKEN__' \
    -d '{
  "cand_set_size" : 1000,
  "fields_to_return" : [ "_id" ],
  "filter" : {
    "$gte" : {
      "price" : 200
    }
  },
  "from" : 0,
  "k" : 3,
  "query_records" : [ {
    "_id" : "10",
    "tags" : ["summer", "beach", "sunset"]
  }, {
    "_id" : "11",
    "tags" : ["winter", "snow", "mountain"]
  } ]
}'

Response

{
  "status": {
    "code": 200,
    "text": "OK"
  },
  "statistics": {
    "OperationTime": 5
  },
  "answer_records": [
    {
      "_id": "1"
    },
    {
      "_id": "2"
    },
    {
      "_id": "3"
    }
  ],
  "answer_distances": [40.0, 50.0, 60.0],
  "query_records": [
    {
      "_id": "10",
      "tags": ["summer", "beach", "sunset"]
    },
    {
      "_id": "11",
      "tags": ["winter", "snow", "mountain"]
    }
  ],
  "answer_count": 3
}

POST/v2/visualRankRecords

Visual Rank Records

Ranks given list of records by visual similarity to a given query image, returns the top-k results.

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 to be search by
Name
records
Type
array
Description
Records to be compared with the query record
Name
records[]._id
Type
string
Description
Image is in the collection specified by ID
Name
records[]._url
Type
string
Description
Image specified by URL
Name
records[]._base64
Type
string
Description
Image encoded as base64
Name
k
Type
number
Description
Number of records to be returned, default: UNLIMITED
Name
radius
Type
number
Description
Radius of the search - maximum distance between the query and answer records
Name
fields_to_return
Type
array
Description
Fields to be returned in every record, defaults to ["_id", "_url", "_file"]

Response fields

Name
query_records
Type
array
Description
The query record(s) copied from the request
Name
answer_records
Type
array
Description
Updated records
Name
answer_count
Type
number
Description
Number of returned records
Name
answer_distances
Type
array
Description
Distances between query record and individual records in answer_records
Name
skipped_records
Type
array
Description
Records that were not processed either because image is not found by ID or extraction failed

Request

POST

/v2/visualRankRecords

curl 'https://api.ximilar.com/photo/search/v2/visualRankRecords' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'collection-id: __COLLECTION_ID__' \
    -H 'Authorization: Token __API_TOKEN__' \
    -d '{
  "fields_to_return" : [ "_id" ],
  "k" : 3,
  "query_record" : {
    "_url" : "http://mydomain.com/my-image.png"
  },
  "radius" : 5.0,
  "records" : [ {
    "_url" : "http://mydomain.com/img.png"
  }, {
    "_base64" : "data:image/png;base64,ABC...",
    "_file" : "local_file_uri"
  }, {
    "_id" : "3"
  } ]
}'

Response

{
  "status": {
    "code": 213,
    "text": "some of the records not found"
  },
  "statistics": {
    "OperationTime": 3
  },
  "answer_records": [
    {
      "_id": "1"
    },
    {
      "_id": "2"
    },
    {
      "_id": "3"
    }
  ],
  "answer_distances": [40.0, 50.0, 60.0],
  "query_records": [
    {
      "_url": "http://mydomain.com/my-image.png"
    }
  ],
  "skipped_records": [
    {
      "_id": "3",
      "_reason": {
        "status": {
          "code": 404,
          "text": "records not found"
        }
      }
    }
  ],
  "answer_count": 3
}

POST/v2/visualTagsRankRecords

Visual Tags Rank Records

Ranks given list of records by combination of visual and tags similarity to a given query image, returns just the top-k results.

The tag field name differs for different similarity services:

generic photo similarity - field name: tags
product photo similarity - field name: _tags_simple
fashion similarity - field name: _tags_simple (the field is generated automatically by the Fashion Tagging service)
custom similarity - field name: _tags

All parameters and the answer are the same as for /v2/visualRankRecords.

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 to be search by, must contain the appropriate tags field for your service type.
Name
records
Type
array
Description
Records to be compared with the query record.
Name
records[]._id
Type
string
Description
Image is in the collection specified by ID.
Name
records[]._url
Type
string
Description
Image specified by URL.
Name
records[]._base64
Type
string
Description
Image encoded as base64.
Name
k
Type
number
Description
Number of records to be returned, default: UNLIMITED.
Name
radius
Type
number
Description
Radius of the search - maximum distance between the query and answer records.
Name
fields_to_return
Type
array
Description
Fields to be returned in every record, defaults to ["_id", "_url", "_file"].

Response fields

Name
query_records
Type
array
Description
The query record(s) copied from the request
Name
answer_records
Type
array
Description
Updated records
Name
answer_count
Type
number
Description
Number of returned records
Name
answer_distances
Type
array
Description
Distances between query record and individual records in answer_records
Name
skipped_records
Type
array
Description
Records that were not processed either because image is not found by ID or extraction failed

Request

POST

/v2/visualTagsRankRecords

curl 'https://api.ximilar.com/photo/search/v2/visualTagsRankRecords' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'collection-id: __COLLECTION_ID__' \
    -H 'Authorization: Token __API_TOKEN__' \
    -d '{
  "fields_to_return" : [ "_id" ],
  "k" : 3,
  "query_record" : {
    "_url" : "http://mydomain.com/my-image.png",
    "tags" : ["summer", "beach", "sunset"]
  },
  "radius" : 5.0,
  "records" : [ {
    "_url" : "http://mydomain.com/img.png",
    "tags" : ["summer", "ocean", "sunset"]
  }, {
    "_base64" : "data:image/png;base64,ABC...",
    "_file" : "local_file_uri",
    "tags" : ["winter", "snow", "mountain"]
  }, {
    "_id" : "3",
    "tags" : ["summer", "beach", "day"]
  } ]
}'

Response

{
  "status": {
    "code": 213,
    "text": "some of the records not found"
  },
  "statistics": {
    "OperationTime": 3
  },
  "answer_records": [
    {
      "_id": "1"
    },
    {
      "_id": "2"
    },
    {
      "_id": "3"
    }
  ],
  "answer_distances": [40.0, 50.0, 60.0],
  "query_records": [
    {
      "_url": "http://mydomain.com/my-image.png",
      "tags": ["summer", "beach", "sunset"]
    }
  ],
  "skipped_records": [
    {
      "_id": "3",
      "_reason": {
        "status": {
          "code": 404,
          "text": "records not found"
        }
      }
    }
  ],
  "answer_count": 3
}

POST/v2/random

Random

Returns a given number of random records stored in the 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
count
Type
number
Description
Number of records to be returned, defaults to 1
Name
fields_to_return
Type
array
Description
Fields to be returned in every record, defaults to ["*"]
Name
filter
Type
object
Description
If the filter is set, not all records are returned but only those matching the filter

Response fields

Name
answer_records
Type
array
Description
Random records from the collection
Name
answer_count
Type
number
Description
Number of records returned

Request

POST

/v2/random

curl 'https://api.ximilar.com/photo/search/v2/random' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'collection-id: __COLLECTION_ID__' \
    -H 'Authorization: Token __API_TOKEN__' \
    -d '{
  "count" : 2,
  "fields_to_return" : [ "_id" ],
  "filter" : {
    "$gte" : {
      "price" : 200
    }
  }
}'

Response

{
  "status": {
    "code": 200,
    "text": "OK"
  },
  "statistics": {
    "OperationTime": 1
  },
  "answer_records": [
    {
      "_id": "1"
    },
    {
      "_id": "2"
    }
  ],
  "answer_count": 2
}

GET/v2/getRecordCount

Get Record Count

Gets the number of records stored in the index 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

Response fields

Name
answer_count
Type
number
Description
Number of records in the collection

Request

GET

/v2/getRecordCount

curl 'https://api.ximilar.com/photo/search/v2/getRecordCount' -i -X GET \
    -H 'collection-id: __COLLECTION_ID__' \
    -H 'Authorization: Token __API_TOKEN__'

Response

{
  "status": {
    "code": 200,
    "text": "OK"
  },
  "statistics": {
    "OperationTime": 0
  },
  "answer_count": 5
}

POST/v2/allRecords

All Records

Gets all records stored in the collection (or just their IDs). The answer is either returned as a standard answer, or stored into a file in the local file system, or both. The created file contains each record on a separate line (it can be directly used to bulk insert data into a new index).

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
fields_to_return
Type
array
Description
Fields to be returned in every record, defaults to ["_id"]
Name
size
Type
integer
Description
GET parameter: number of records to be returned on current page, defaults to Null which returns all records
Name
page
Type
integer
Description
GET parameter: page for paginated result (if size used)
Name
filter
Type
object
Description
If the filter is set, not all records are returned but only those matching the filter
Name
output_file_name
Type
string
Description
Name of the output (temporary) file, default: "all-records-[timestamp].json"; do not use this field
Name
delete_file_after
Type
boolean
Description
If true then the output file is deleted after the processing, default: true

Response fields

Name
answer_records
Type
array
Description
Data records - either all or of current 'page' (if size used)
Name
next
Type
string
Description
If size used and this is not the last page, this field contains link to the next page of results (if any)
Name
previous
Type
string
Description
If size used and this is not the last page, this field contains link to the previous page of results (if any)
Name
answer_count
Type
number
Description
OVERALL number of records in the collection (like returned by /v2/getRecordCount)
Name
output_file_name
Type
string
Description
Name of the file records were saved to

Request

POST

/v2/allRecords

curl 'https://api.ximilar.com/photo/search/v2/allRecords?size=2&page=3' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'collection-id: __COLLECTION_ID__' \
    -H 'Authorization: Token __API_TOKEN__' \
    -d '{
  "delete_file_after" : true,
  "fields_to_return" : [ "*" ],
  "filter" : {
    "$gte" : {
      "price" : 200
    }
  },
  "output_file_name" : "some-file.json"
}'

Response

{
  "status": {
    "code": 200,
    "text": "OK"
  },
  "statistics": {
    "OperationTime": 6
  },
  "answer_records": [
    {
      "_id": "1"
    },
    {
      "_id": "2"
    }
  ],
  "output_file_name": "some-file.json",
  "next": "https://api.ximilar.com/v2/allRecords?page=4&size=2",
  "previous": "https://api.ximilar.com/v2/allRecords?page=2&size=2",
  "answer_count": 7
}

POST/v2/deleteByFilter

Delete By Filter

Deletes all records matching given condition. This method is not available in all indexes.

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
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
answer_records
Type
array
Description
Records that were deleted
Name
answer_count
Type
number
Description
Number of records deleted

Request

POST

/v2/deleteByFilter

curl 'https://api.ximilar.com/photo/search/v2/deleteByFilter' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'collection-id: __COLLECTION_ID__' \
    -H 'Authorization: Token __API_TOKEN__' \
    -d '{
  "fields_to_return" : [ "_id" ],
  "filter" : {
    "$gte" : {
      "price" : 200
    }
  }
}'

Response

{
  "status": {
    "code": 200,
    "text": "OK"
  },
  "statistics": {
    "OperationTime": 4
  },
  "answer_records": [
    {
      "_id": "1"
    },
    {
      "_id": "2"
    }
  ],
  "answer_count": 2
}

POST/v2/range

Range

Find visually similar images to a given image from the collection up to a certain query radius. The search is approximate -- there might be false negatives, especially with larger radius. Do not use this method, if you are not sure.

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 to be search by
Name
radius
Type
number
Description
Radius of the search - maximum distance between the query and answer records
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
Name
product_field
Type
string
Description
If set, each record in the response will be different product. Every collection has it's own default
Name
cand_set_size
Type
number
Description
Internal parameter (please do not modify). It can affect the operation's response time: lower values may be faster but could reduce accuracy. Each collection has its own default value.

Response fields

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

Request

POST

/v2/range

curl 'https://api.ximilar.com/photo/search/v2/range' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'collection-id: __COLLECTION_ID__' \
    -H 'Authorization: Token __API_TOKEN__' \
    -d '{
  "cand_set_size" : 1000,
  "fields_to_return" : [ "_id" ],
  "filter" : {
    "$gte" : {
      "price" : 200
    }
  },
  "product_field" : "product_id",
  "query_record" : {
    "_url" : "http://mydomain.com/my-image.png"
  },
  "radius" : 100
}'

Response

{
  "status": {
    "code": 200,
    "text": "OK"
  },
  "statistics": {
    "OperationTime": 1
  },
  "answer_records": [
    {
      "_id": "1"
    },
    {
      "_id": "2"
    },
    {
      "_id": "3"
    }
  ],
  "answer_distances": [40.0, 50.0, 60.0],
  "query_records": [
    {
      "_url": "http://mydomain.com/my-image.png"
    }
  ],
  "answer_count": 3
}

POST/v2/nearDuplicates

Near Duplicates

Finds those images in the collection that are the same or very similar to the query image.

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 to search by.
Name
fields_to_return
Type
array
Description
Fields to be returned in every record, defaults to ["*"].
Name
radius
Type
number
Default
Default:5.0
Description
Maximum distance for records to be considered near duplicates, defaults to 5.0.
Name
filter
Type
object
Description
Search will be applied only to records satisfying this filter.
Name
cand_set_size
Type
number
Description
Internal parameter (please do not modify). It can affect the operation's response time: lower values may be faster but could reduce accuracy. Each collection has its own default value.

Response fields

Name
query_records
Type
array
Description
The query record(s) copied from the request
Name
answer_records
Type
array
Description
Records found that are near duplicates
Name
answer_count
Type
number
Description
Number of records found
Name
answer_distances
Type
array
Description
Distances between query record and individual records in answer_records

Request

POST

/v2/nearDuplicates

curl 'https://api.ximilar.com/photo/search/v2/nearDuplicates' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'collection-id: __COLLECTION_ID__' \
    -H 'Authorization: Token __API_TOKEN__' \
    -d '{
  "cand_set_size" : 1000,
  "fields_to_return" : [ "_id" ],
  "filter" : {
    "$gte" : {
      "price" : 200
    }
  },
  "query_record" : {
    "_url" : "http://mydomain.com/my-image.png"
  },
  "radius" : 5.0
}'

Response

{
  "status": {
    "code": 200,
    "text": "OK"
  },
  "statistics": {
    "OperationTime": 6
  },
  "answer_records": [
    {
      "_id": "1"
    },
    {
      "_id": "2"
    }
  ],
  "answer_distances": [10.0, 20.0],
  "query_records": [
    {
      "_url": "http://mydomain.com/my-image.png"
    }
  ],
  "answer_count": 2
}