Visual Search – Overview & Basics
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
Contact us to discuss how we can tailor the solution to your needs.
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 withcode
andtext
statistics
object withOperationTime
(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.
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) andtext
(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
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"
}
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 fieldanswer_records
contains the list of records that were successfully inserted, whileskipped_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
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
}
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. Fieldanswer_records
contains list of records actually deleted, andskipped_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
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
}
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
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
}
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
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
}
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 removefield
.
- 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
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
}
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
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
}
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
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
}
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
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
}
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
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
}
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
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
}
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
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
}
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
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
}
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
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 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
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
}
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
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
}
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
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
}
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
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
}
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
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
}