# Inspect aggregated 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.

← Check content existence Queries & Filters →