Results structure

Constructor.io's largely schema-less result format allows for a large variety of return values, with some light structure to facilitate common use cases.

{
  "request": {
    ...
  },
  "response": {
    "facets": [
      ...
    ],
    "groups": [
      ...
    ],
    "sort_options": [
      ...
    ],
    "results": [
      {
      "data": {
        "groups": [
          {
            "display_name": "dry food",
            "group_id": "dry-food",
            "path": "/pet-food/dog-food/"
          }
        ],
        "facets": {
          "Brand": "Natural Balance",
          "Price": 17.90,
          "Type": ["Dry Food", "Dog Food"]
        },
        "id": "123",
        "image_url": "https://www.constructor.io/images/doge.jpg",
        "url": "https://www.constructor.io/pages/dog",
        "variation_id": "4321",
        "variations": [
          {
            "data": {
              "facets": {
                "Color": "Black",
              },
              "id": "4321",
              "image_url": "https://www.constructor.io/images/black_doge.jpg",
              "url": "https://www.constructor.io/pages/dog_black",
            }
          },
          {
            "data": {
              "facets": {
                "Color": "Brown",
              },
              "id": "1234",
              "image_url": "https://www.constructor.io/images/brown_doge.jpg",
              "url": "https://www.constructor.io/pages/dog_brown",
            }
          }
        ]
      },
      "matched_terms": [
        "dog"
      ],
      "value": "Natural Balance Small Bites Potato & Duck Formula Dog Food"
      }
    ],
    "total_num_results": 1
  }
}

Default Data

We'll first review the data Constructor.io returns for all product search queries:

value The primary value for the item in question - typically item_name.
matched_terms All terms within the item matching the user's query (regardless of whether misspelled).

In addition to the data always returned, Constructor.io will display any data that's been uploaded for the products in question. We'll go over a typical subset below:

Additional Data (may not be present)

url The URL where the item can be viewed or purchased.
id An ID that identifies the item within the company.
image_url An image of the item in question.
groups The category(ies) an item belongs to.
facets The facet(s) an item is associated with.
variation_id ID of the selected (best matching) variation. All metadata of the best matching variation will also be merged into the item's data object.
variations list of this item's variations.

Groups info in results response

The Search API will return information on the group(s) the item belongs to. Three pieces of information will always be returned:

display_name The name of the group as you'd present it to users.
group_id The id of the group. Any ASCII characters can be used.
path The path of group_IDs above this group. /great-grandparent/grandparent/parent/

This example captures common use-cases; please reach out to Constructor.io support if you'd like assistance in designing your search experience.