Skip to content

Image Matching

The Image Matching service can identify duplicate or near-duplicate images. It calculates so called "visual hash" that should be the same or nearly the same for images that are only slightly modified: shift of colors (B/W), re-compression, change of resolution, noise etc.

The API follows the general rules of Ximilar API as described in Section First steps.

The 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/image_matching/v2/<method>

Overview of API Methods

  • /v2/ping -- test the service and get basic info about it

  • /v2/visual_hash -- get visual hash(es) for given image or images

  • /v2/remove_duplicates -- get a set of images and merge the ones that are duplicates or near-duplicates (TODO)
  • /v2/rank_images -- get one "query" image and a set of "data" images rank the data images by hash-based similarity to the query image (TODO)

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:

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

Return Values

All API methods return:

  • HTTP error code 2XX, if the method was OK and other HTTP error code, if the method failed
  • JSON-formatted body with the status, answer and statistics

Answer fields common for all types of answers:

  • statistics -- a map of various statistics about the processing. The only statistic included every time is
    • processing time -- time of actual processing of the query (in seconds)
  • status -- a JSON map with a status of the method processing. It contains these subfields:
    • code -- a numeric code of the operation status; it follows the concept of HTTP status codes (2XX, 4XX). Specific codes are described for each type of answer (or operation) (see below).
    • text -- a text describing the status code
    • error_description -- in case of the processing ended with error (codes 4XX), this field contains a detailed description of the error; this might include Java stack traces.

Generic statuses that can be returned by any operation:

  • "status": {"code": 200, "text": "OK"}
  • "status": {"code": 402, "text": "aborted by error", error_description="..."}
  • "status": {"code": 500, "text": "unknown error", "error_description": "..."}

Detailed Descriptions of API Methods

/v2/ping

Description: returns a basic information about the index

Example:

curl --request POST \
  --url https://api.ximilar.com/image_matching/v2/ping \
  --header 'authorization: Token {__API_TOKEN__}'

Returns:

{
  "status": {
    "code": 200,
    "text": "OK"
  },
  "_service_info": {
    "_name": "Image matching service",
    "_info": "Get visual hashes, find (near-)duplicate images and rank them"
  }
}

/v2/visual_hash

Description: get a visual hash (or several different types of hashes) for given image(s)

Parameters:

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

Example:

curl --request POST \
  --url https://api.ximilar.com/image_matching/v2/visual_hash \
  --header 'authorization: Token {__API_TOKEN__}' \
  --header 'content-type: application/json' \
  --data '{
    "records": [
        {"_url": "https://images.ximilar.com/examples/fashion_products/10073009-HERO.jpeg"}
    ]
}'

Returns:

{
  "records": [
    {
      "_url": "https://images.ximilar.com/examples/fashion_products/10073009-HERO.jpeg",
      "_width": 400,
      "_height": 400,
      "bmh1": "11111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111001111111111111111111111111111110000111111111111111101111111111110001111111101111111000000001111110011111111001111110000000011111110111111110001111100000000111111111111111100001111000000001111111111111111000001111000000011111111111111110000001110000000111111111111111100000001100000001111111101111111000000001000000011111111001111110000000010000000111111110001111100000000100000001111111100001111000000001100000011111111000001110000000000000000111111110000001100000000000000001100000000000001000000000000000011000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001001100000000000001110000000000011111111000000000111111110000000001",
      "phash": "1111110000001011010000111110110010111001000101100010010110001010"
    }
  ],
  "statistics": {
    "processing time": 0.13515067100524902
  },
  "status": {
    "code": 200,
    "text": "OK",
  }
}