Photo Similarity & Text Search

This page describes API of the visual search (similarity) in generic or stock photos with images or text. The Photo Similarity & Text Search are two services that are complementary to each other. The API follows the general rules of Ximilar API as described in Section First steps.

The Search API is a set of HTTP REST services accepting JSON-formatted documents using POST and returning JSON documents. The base URL for this service is:

https://api.ximilar.com/photo/search/v2/<method>

and it contains all methods for Visual search and API.

There are two additional endpoints:

https://api.ximilar.com/photo/text/v2/text - for searching your collection with text query https://api.ximilar.com/photo/v2/descriptor - for extracting visual descriptor (embedding) for images

Business plan required

In order to get access to this service, please register at https://app.ximilar.com and order at least a business plan for Photo Similarity and professional plan for text search. For more information see our Pricing page.

Parameters of API methods

The Ximilar Search API works with data records that represent a single image. It has the same format in all operations and also in the responses. It is a JSON record (map) with the following fields:

• _url -- URL with a PNG, JPG, or TIFF image file
• _base64 -- base64-encoded content of a PNG, JPG or TIFF image file
• attribute -- a JSON representation of any attribute of the record; these attributes are returned by the method and can be used for identification of individual records within the answer. We typically use attribute _id as unique image ID.

Example of image records in field records which is used by all API methods:

Json

{
  "records": 
  [ 
    {
      "_id": "1",
      "_url": "https://yourdomain.com/images/product_image_321.jpg"
    },
    {
      "_id": "2",
      "_base64": "data:image/jpeg;base64,/9j/4A...."
    }
  ]
}

Detailed Descriptions of API Methods

/photo/text/v2/text

Description: Performs search (visual similarity/knn) on your collection of images (collection is specified in header) via text query, sometimes also called as neural text search or text-to-image.

Parameters:

• query_record: must contain a _text_data field with a sentence or word as text query, and optional _dominant_colors field with (luv_colors and percentages)
  • if using _dominant_colors, the results will be adjusted by weight based on the dominant colors of the images. The images with dominant colors that match the specified luv_colors within the given percentages range will be given a higher weight in the similarity calculation. More details on how to get luv colors is on this page.
• fields_to_return: list of fields (metadata) to return in results
• filter: mongodb filtering on fields (metadata) that was stored with the images/records
• k: number of results to return

Example:

Bash

curl --request POST \
  --url https://api.ximilar.com/photo/text/v2/text \
  --header 'authorization: Token __APITOKEN__' \
  --header 'collection-id: __YOURCOLLECTIONID__' \
  --header 'content-type: application/json' \
  --data '{
    "query_record": {
        "_text_data": "a landscape photo of mountains",
        "_dominant_colors": {
            "luv_colors": [
                [0, 0, 0],
                [100, 0, 0]
            ],
            "percentages": [0.6, 0.4]
        }
    },
    "filter": {
        "supplierid": {
            "$lte": 600
        }
    },
    "fields_to_return": [
        "_id",
        "_url",
        "supplierid"
    ],
    "k": 3
}'

Returns:

{
    "status": {
        "code": 200,
        "text": "OK",
        "proc_id": "d820b7a9-4b93-4a85-a4ed-d96731bc471e"
    },
    "statistics": {
        "OperationTime": 244,
        "processing time": 0.31435346603393555
    },
    "answer_records": [
        {
            "_id": "65732555",
            "_url": "_URL_1_",
            "supplierid": 450
        },
        {
            "_id": "88182211",
            "_url": "_URL_2_",
            "supplierid": 451
        },
        {
            "_id": "106629458",
            "_url": "_URL_3_"
            "supplierid": 200
        }
    ],
    "answer_distances": [
        1.1622182,
        1.165117,
        1.1667057
    ],
    "answer_count": 3
}

/photo/v2/descriptor

Description: returns a descriptors/embeddings for list of images

Parameters:

• records: list of photos to get hashes for
  • must contain either of _url or _base64 field - see section image data for details.
  • maximum batch of records is 10

Example:

Bash

curl --request POST \
  --url https://api.ximilar.com/photo/v2/descriptor \
  --header 'authorization: Token __API_TOKEN__' \
  --header 'content-type: application/json' \
  --data '{
    "records": [
        {"_url": "_URL_1_"},
        {"_url": "_URL_2_"}
    ]
}'

Returns:

{
  "records": [
    {
      "_url": "_URL_1_",
      "_width": 400,
      "_height": 400,
      "_descriptor": [0.12421, 0.3251, -3.3215, -1.2325, 1.2352, 0.3252, ...],
    },
    {
      "_url": "_URL_2_",
      "_width": 400,
      "_height": 400,
      "_descriptor": [0.3, 0.5, -3.1215, -2.2325, 1.352, 0.3452, ...],
    }
  ],
  "statistics": {
    "processing time": 0.13515067100524902
  },
  "status": {
    "code": 200,
    "text": "OK",
  }
}