Lens: search by image

Searches for similar items within the dataset based on an image provided that is not within the dataset. The results are ordered by how similar they are to the image. The number of results can optionally be specified by the limit parameter.

Results can be filtered using the metadata supplied when the content was created. Filtering syntax is described in the querying section.

Input

Endpoint

POST /orgs/:organisation/datasets/:dataset/search

Field	Type	Required	Value Description
organisation	String	yes	The organisation name
dataset	String	yes	The dataset name
limit	Number	no	The number of items to return. Suggestion of at least 5, the minimum limit is 2, the maximum limit is 50, the default limit is 10.
			If you wish to check the existence of content or get metadata, use Content Details
q	String	no	The filter criteria based on the associated metadata attribute. See Querying for more details.
fields	String	no	A comma separated list of associated item metadata fields to be added to the response (i.e fields=category,colour).
			Request all metadata using fields=*. Additional fields generated when processed by Visii include image_width, image_height and image_url.
v	String		The vars querystring containing key-value pairs (key:value comma separated) of action information, support both specific (such as page_view_id and other custom parameters.
			Details of Vars Querystring. E.g.: v=a:exit,id:abc-123,user_id:abc,page_view_id:12345

Body

Field	Type	Required	Value Description
image	String	yes	The image data URI (opens new window) representation. The body length is limited to 500KB.
			Supported image formats are jpeg, jpg, png. Details on suggested image resolutions and formats in Content Create

Request

Note

my-dataset-api-token is a dataset token, not an organisation token.

curl -X POST \
     -H "Authorization: token my-dataset-api-token" \
     -H "Accept: application/vnd.visii.v2+json" \
     -d '{"image":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAQQAAAEsCAYAAAAl981RAAAgA"}' \
     "https://api.visii.com/orgs/my-org/datasets/my-dataset/search?fields=category,price&q=price:10:&limit=2"

Response

Field	Type	Value Description
status	String	The status of the response
results	Object	The list of results to be shown for this step of the journey
results.$.id	String	The id of the item
results.$.explore_url	String	The URL to obtain the next set of results if this item is selected
results.$.metadata	Object	A selection of metadata fields for the item

HTTP/1.1 200 OK
{
  "results": [
    {
      "id": "123",
      "explore_url": "https://api.visii.com/orgs/my-org/datasets/my-dataset/explore?id=123&fields=category,price&q=category:cats&limit=2&j=sid1",
      "metadata": {
        "category": "boots",
        "price": 99.99
      }
    },
    {
      "id": "456",
      "explore_url": "https://api.visii.com/orgs/my-org/datasets/my-dataset/explore?id=456&fields=category,price&q=category:cats&limit=2&j=sid1",
      "metadata": {
        "category": "heels",
        "price": 10.49
      }
    }
  ],
  "status": "ok"
}