# Content fields: inspect metadata values

This endpoint can be used to return details about existing metadata values. It is useful when you need to know if filtering by a metadata value would return any results without actually performing a Explore or Similar request.

See below details about the endpoint then check the Scenarios section to more specific use cases.

# Input

Endpoint

GET /orgs/:organisation/datasets/:dataset/content/fields

Field Type Required Value Description
organisation String yes The organisation name
dataset String yes The dataset name
fields String yes 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.
q String no The filter criteria based on the associated metadata attribute. See Querying for more details.

# Request

Note

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

curl -X GET \
     -H "Authorization: token <my-dataset-token>" \
     -H "Accept: application/vnd.visii.v2+json" \
     "https://api.visii.com/orgs/my-org/datasets/my-dataset/content/fields?fields=category,price"

# Response

Field Type Value Description
status String The status of the response
fields Object The list of available fields (when fields=*) or a dictionary of field names with possible values and number of items matching the values

# Response when requesting all fields

HTTP/1.1 200 OK
{
  "fields": [
    "category",
    "price",
    "image_url",
    "image_width",
    "image_height",
    "visii_created_at",
    "visii_updated_at"
  ],
  "status": "ok"
}

# Response when requesting values for some fields

HTTP/1.1 200 OK
{
  "fields": {
    "category": {
      "boots": 10,
      "heels": 14
    },
    "price": {
      "99.99": 20,
      "10.49": 4
    }
  },
  "status": "ok"
}

# Scenarios

# Get the list of all available fields

Before starting narrowing down on available metadata values you may want to know what are the available fields. For this use fields=*. That will return a list of available metadata fields. Alongside fields you pushed when adding content in a dataset you will see Visii generated fields:

Field Name Description
image_url The image url
image_width The image width
image_height The image height
visii_created_at Timestamp generated when the item was first added into the dataset
visii_updated_at Timestamp updated every time the item get a URL or metadata update

Visii fields naming convention

Moving forward all additional fields provided by Visii will be prefixed by visii_. The image_<name> fields mentioned above are using the old format for backwards compatibility.

# Get the list of values for a field

Pass in the fields parameter a comma separated list of fields and get back a list of values and a counter of how many items match that value.

# Get the list of values with additional filters

Consider the following scenario: you have a marketplace with products that are placed in multiple categories and are sold by different vendors. You want to offer your users the option to see recommendations in the "Handmade" category made by "LoremIpsum" vendor.

To get the list of all vendors selling handmade products, you can use this endpoint like this: /content/fields?fields=vendor&q=category:Handmade.

A problem arises when you have too many possible vendors for the "Handmade" category to display in the UI. For that you can further narrow it down by doing partial string matching on the vendor name like this: /content/fields?fields=vendor&q=category:Handmade,vendor:*lorem*. This will return a smaller list of vendor names that can be displayed in its entirety or further filtering can follow.

See Querying for more details on substring filtering.

Last Updated: 7/12/2022, 5:20:12 PM