# Visual discovery

# Intelligent visual search

Begins a conversational journey through a dataset, allowing a user to explore the content available. Each step in the journey requires the user to select a single item from a set of results in order to proceed. The platform can then determine a new set of results based on the previous selections.

If the first request doesn't contain an item ID the platform will randomly select a list of items from the dataset content. Depending on the scenario (your user just wants to explore and no other item were seen or some items were visited before), it's perfectly fine to have as many different starting points as you like, as long as the start item you send (using the id query string parameter) belongs to the dataset.

The response contains a list of the results. Each item in the results indicates the content it refers to in the id field. This is the ID specified when the content was added to the dataset and should allow you to determine what to show to your user. Each result also includes an explore_url parameter which is used to continue the journey. This is described in more detail below.

In order to retrieve subsequent results from the API, when the user selects an item from a set of results, you simply need to make a GET request to the corresponding explore_url for that item. The response to that request is in the same form as for the initial request. Thus a journey is undertaken by simply following the links at each step for the relevant item in the results.

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

# Getting results with metadata

In some cases you can avoid doing a lookup for the item details in your system by also requesting parts of the metadata associated with the item resources. This is achieved using the fields parameter which looks into metadata added when the content was added to the dataset and returns it in the item object. See examples below.

# Input

Endpoint

GET /orgs/:organisation/datasets/:dataset/explore

Field	Type	Required	Value Description
organisation	String	yes	The organisation name
dataset	String	yes	The dataset name
id	String	no	The id of the selected item
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`

# Request

Note

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

curl -X GET \
     -H "Authorization: token my-dataset-api-token" \
     -H "Accept: application/vnd.visii.v2+json" \
     "https://api.visii.com/orgs/my-org/datasets/my-dataset/explore?id=123&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"
}

Visually similar content →