NAV Navbar
shell javascript ruby python php perl java csharp

Introduction

We have libraries for Python, Ruby, PHP, Node/Javascript, Perl, Java and C#. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Installation

# shell usage doesn't require any installation (except curl)
npm install constructorio-node
gem install constructorio
pip install constructor-io
composer require constructor-io/constructor-io
cpanm WebService::ConstructorIO
/*
 * Please follow the directions at Jitpack.io to add the client to your project
 * https://jitpack.io/#Constructor-io/constructorio-java
 */
/*
Run in the Package Manager Console:

Install-Package constructor.io

Or, if using nuget on the command line:

nuget install constructor.io
*/

Install the library specific to your language by following the instructions on the right.

Authentication

API Token

To authorize, use this code:

# with curl, there's no need to authorize separately -- just pass your API token in with every call
curl -X POST -H "Content-Type: application/json" \
  -d '{"item_name":"xyz","keywords":["k1","k2"]}' \
  -u "[your API token]:" https://ac.cnstrc.com/v1/item
var ConstructorIO = require('constructorio-node');
var constructorio = new ConstructorIO({
  apiToken: "[your API token]",
  apiKey: "[your API key]",
});

require('constructorio')
ConstructorIO.configure do |config|
  config.api_token = "[your API token]"
  config.autocomplete_key = "[your API key]"
end
constructorio = ConstructorIO::Client.new
from constructor_io import ConstructorIO
constructor_instance = ConstructorIO(
    api_token="[your api token]",
    autocomplete_key="[your API key]")
<?php
// if using Composer autoloading:
// require_once "vendor/autoload.php";
use ConstructorIO\ConstructorIO;
$constructorio = new ConstructorIO("[your API token]","[your API key]");
use WebService::ConstructorIO;
my $constructorio = new WebService::ConstructorIO->new(
  api_token => "[your API token]",
  autocomplete_key => "[your API key]"
);
import io.constructor.client.*;

String apiToken = "[your API token]";
String apiKey = "[your API key]";
ConstructorIO constructorio = new ConstructorIO(apiToken, apiKey, true, null);
using ConstructorIO;
var ConstructorIOAPI = new ConstructorIOAPI("[your API token]", "[your API key]");

Make sure to replace [your API token] with your API token from your dashboard.

You authenticate to the REST API by providing your API token, which you can obtain from your dashboard.

Authentication is done using HTTP Basic Auth. Provide your API token as the basic auth username in every request. You do not need to provide a password. All API requests must be made over HTTPS.

Verification

curl -u "[your API token]:" "https://ac.cnstrc.com/v1/verify?key=[your API key]"
constructorio.verify(function(error, response) {
  if (error) {
    console.log("Error: ", error);
  } else {
    console.log("Response: ", response);
  }
});
response = constructorio.verify
response = constructor_instance.verify()
<?php
$response = $constructorio->verify();
my $response = $constructorio->verify();
boolean isValid = constructorio.verify();
bool isValid = ConstructorIOAPI.Verify();

You can verify that authentication works correctly by issuing a simple verification request.

HTTP Request

GET https://ac.cnstrc.com/v1/verify?key=[your API key]

Items

Suggestions that are shown in results are called items. items can be full product names (with metadata including images and descriptions) or simple search terms.

Most users prefer to leverage our bulk methods below, which allow adding, updating, or removing up to 1,000 items at a time.

Batch Add Items

# search suggestions
curl -X POST -H "Content-Type: application/json" \
  -d '{"items": [ {"item_name": "Golden Retriever"}, {"item_name": "Poodle"} ],
    "section":"Search Suggestions"}' \
  -u"[your token]:" "https://ac.cnstrc.com/v1/batch_items?key=[your API key]"

# products
curl -X POST -H "Content-Type: application/json" \
  -d '{
        "section":"Products",
        "items": [
          {
            "item_name": "Labradoodle",
            "suggested_score": 360,
            "keywords": ["poodle","labrador","retriever"],
            "url": "http://www.mydogs.com/labradoodle",
            "image_url": "https://images.mydogs.com/labradoodle.jpg",
            "description": "A crossbreed dog created by crossing the Labrador Retriever and the Poodle",
            "metadata": { "animal": "dog" },
            "group_ids": [ "23", "45" ],
            "variations": [
              {
                "id": "labradoodle-brown",
                "facets": {
                    "Color": ["Brown"]
                },
                "image_url": "https://images.mydogs.com/labradoodle-brown.jpg",
                "suggested_score": 100,
                "metadata": {
                    "is_default": true
                }
              },
              {
                "item_name": "Black Labradoodle",
                "id": "labradoodle-black",
                "facets": {
                    "Color": ["Black"]
                },
                "image_url": "https://images.mydogs.com/labradoodle-black.jpg",
                "suggested_score": 200
              }
            ]
          },
          {
            "item_name": "Australian Shepherd",
            "suggested_score": 130,
            "keywords": ["aussie"],
            "url": "http://www.mydogs.com/australian_shepherd",
            "image_url": "https://images.mydogs.com/australian_shepherd.jpg",
            "description": "A medium-sized breed of dog developed on ranches in the Western United States",
            "metadata": { "animal": "dog" },
            "group_ids": [ "67", "89" ]
          }
        ]
      }' \
  -u"[your token]:" "https://ac.cnstrc.com/v1/batch_items?key=[your API key]"
constructorio.addItemBatch(
  {
    section: "Products",
    items: [
      {
        item_name: "Labradoodle",
        suggested_score: 360,
        keywords: ["poodle","labrador","retriever"],
        url: "http://www.mydogs.com/labradoodle",
        image_url: "https://images.mydogs.com/labradoodle.jpg",
        description: "A crossbreed dog created by crossing the Labrador Retriever and the Poodle",
        metadata: { "animal": "dog" },
        group_ids: [ "23", "45" ],
        variations: [
          {
            "id": "labradoodle-brown",
            "facets": {
              "color": ["Brown"]
            },
            "image_url": "https://images.mydogs.com/labradoodle-brown.jpg",
            "suggested_score": 100,
            "metadata": {
                "is_default": true
            }
          },
          {
            "id": "labradoodle-black",
            "facets": {
              "color": ["Black"]
            },
            "image_url": "https://images.mydogs.com/labradoodle-black.jpg",
            "suggested_score": 200
          }
        ]
      },
      {
        item_name: "Australian Shepherd",
        suggested_score: 130,
        keywords: ["aussie"],
        url: "http://www.mydogs.com/australian_shepherd",
        image_url: "https://images.mydogs.com/australian_shepherd.jpg",
        description: "A medium-sized breed of dog developed on ranches in the Western United States",
        metadata: { "animal": "dog" },
        group_ids: [ "67", "89" ]
      }
    ]
  },
  function(error, response) {
    if (error) {
      console.log(error);
    }
  }
);
# search suggestions
response = constructorio.add_batch(
  {
    section: "Search Suggestions",
    items: [
      { item_name: "Golden Retriever" },
      { item_name: "Poodle" }
    ],
  }
)

# products
response = constructorio.add_batch(
  {
    section: "Products",
    items: [
      {
        item_name: "Labradoodle",
        suggested_score: 360,
        keywords: ["poodle", "labrador", "retriever"],
        url: "http://www.mydogs.com/labradoodle",
        image_url: "https://images.mydogs.com/labradoodle.jpg",
        description: "A crossbreed dog created by crossing the Labrador Retriever and the Poodle",
        metadata: { animal: "dog" },
        group_ids: ["23", "45"],
        variations: [
          {
            "id": "labradoodle-brown",
            "facets": {
              "color": ["Brown"]
            },
            "image_url": "https://images.mydogs.com/labradoodle-brown.jpg",
            "suggested_score": 100,
            "metadata": {
                "is_default": true
            }
          },
          {
            "id": "labradoodle-black",
            "facets": {
              "color": ["Black"]
            },
            "image_url": "https://images.mydogs.com/labradoodle-black.jpg",
            "suggested_score": 200,
          }
        ]
      },
      {
        item_name: "Australian Shepherd",
        suggested_score: 130,
        keywords: ["aussie"],
        url: "http://www.mydogs.com/australian_shepherd",
        image_url: "https://images.mydogs.com/australian_shepherd.jpg",
        description: "A medium-sized breed of dog developed on ranches in the Western United States",
        metadata: { animal: "dog" },
        group_ids: ["67", "89"]
      }
    ]
  }
)
# search suggestions
items = response = constructor_instance.add_batch(
  section="Search Suggestions",
  items=[
    {"item_name": "Golden Retriever"},
    {"item_name": "Poodle"}
  ]
)

# products
response = constructor_instance.add_batch(
    section="Products",
    items=[
      {
        "item_name": "Labradoodle",
        "suggested_score": 360,
        "keywords": ["poodle","labrador","retriever"],
        "url": "http://www.mydogs.com/labradoodle",
        "image_url": "https://images.mydogs.com/labradoodle.jpg",
        "description": "A crossbreed dog created by crossing the Labrador Retriever and the Poodle",
        "metadata": { "animal": "dog" },
        "group_ids": ["23","45"],
        "variations": [
          {
            "id": "labradoodle-brown",
            "facets": {
              "color": ["Brown"]
            },
            "image_url": "https://images.mydogs.com/labradoodle-brown.jpg",
            "suggested_score": 100,
            "metadata": {
                "is_default": True
            }
          },
          {
            "id": "labradoodle-black",
            "facets": {
              "color": ["Black"]
            },
            "image_url": "https://images.mydogs.com/labradoodle-black.jpg",
            "suggested_score": 200,
          }
        ]
      },
      {
        "item_name": "Australian Shepherd",
        "suggested_score": 130,
        "keywords": ["aussie"],
        "url": "http://www.mydogs.com/australian_shepherd",
        "image_url": "https://images.mydogs.com/australian_shepherd.jpg",
        "description": "A medium-sized breed of dog developed on ranches in the Western United States",
        "metadata": { "animal": "dog" },
        "group_ids": ["67","89"]
      }
    ]
)
<?php
// search suggestions
$response = $constructorio->addBatch(
  array("Golden Retriever", "Poodle"),
  "Search Suggestions"
);

// products
$response = $constructorio->addBatch(
  array(
     array(
      "item_name" => "Labradoodle",
      "suggested_score" => 360,
      "keywords" => ["poodle", "labrador", "retriever"],
      "url" => "http://www.mydogs.com/labradoodle",
      "image_url" => "https://images.mydogs.com/labradoodle.jpg",
      "description" => "A crossbreed dog created by crossing the Labrador Retriever and the Poodle",
      "metadata" => array( "animal" => "dog" ),
      "group_ids" => ["23, "45"]
     ),
     array(
      "item_name" => "Australian Shepherd",
      "suggested_score" => 130,
      "keywords" => ["aussie"],
      "url" => "http://www.mydogs.com/australian_shepherd",
      "image_url" => "https://images.mydogs.com/australian_shepherd.jpg",
      "description" => "A medium-sized breed of dog developed on ranches in the Western United States",
      "metadata" => array( "animal" => "dog" ),
      "group_ids" => ["67, "89"]
     )
  )
  , "Products");
# search suggestions
my $response = $constructorio->add_batch(
  section => "Search Suggestions",
  items => [
    { item_name => "Golden Retriever" },
    { item_name => "Poodle" }
  ]
);

# products
my $response = $constructorio->add_batch(
  section: "Products",
  items: [
    {
      item_name => "Labradoodle",
      suggested_score => 360,
      keywords => ["poodle", "labrador", "retriever"],
      url => "http://www.mydogs.com/labradoodle",
      image_url => "https://images.mydogs.com/labradoodle.jpg",
      description => "A crossbreed dog created by crossing the Labrador Retriever and the Poodle",
      metadata => { animal => "dog" },
      group_ids => ["23", "45"],
      variations => [
        {
          "id" => "labradoodle-brown",
          "facets" => {
            "color" => ["Brown"]
          },
          "image_url" => "https://images.mydogs.com/labradoodle-brown.jpg",
          "suggested_score" => 100,
          "metadata" => {
              "is_default" => 1
          }
        },
        {
          "id" => "labradoodle-black",
          "facets" => {
            "color" => ["Black"]
          },
          "image_url" => "https://images.mydogs.com/labradoodle-black.jpg",
          "suggested_score" => 200,
        }
      ],
    },
    {
      item_name => "Australian Shepherd",
      suggested_score => 130,
      keywords => ["aussie"],
      url => "http://www.mydogs.com/australian_shepherd",
      image_url => "https://images.mydogs.com/australian_shepherd.jpg",
      description => "A medium-sized breed of dog developed on ranches in the Western United States",
      metadata => { animal => "dog" },
      group_ids => ["67", "89"]
    }
  ]
)
ConstructorItem item1 = new ConstructorItem("Labradoodle");
item1.setSuggestedScore(360);
item1.setUrl("http://www.mydogs.com/labradoodle");
item1.setImageUrl("https://images.mydogs.com/labradoodle.jpg");
item1.setDescription("A crossbreed dog created by crossing the Labrador Retriever and the Poodle");
item1.setKeywords(new ArrayList<>(Arrays.asList("poodle","labrador","retriever")));

ConstructorItem item2 = new ConstructorItem("Australian Shepherd");
item2.setSuggestedScore(130);
item2.setUrl("http://www.mydogs.com/australian_shepherd");
item2.setImageUrl("hhttps://images.mydogs.com/australian_shepherd.jpg");
item2.setDescription("A medium-sized breed of dog developed on ranches in the Western United States");
item2.setKeywords(new ArrayList<>(Arrays.asList("aussie")));

ConstructorItem[] items = { item1, item2 };
boolean success = constructorio.addItemBatch(items, "Products");
// search suggestions
List<ListItem> itemList = new List<ListItem>();
itemList.Add(new ListItem(
  Name: "Golden Retriever"
)
itemList.Add(new ListItem(
  Name: "Poodle"
)
bool success = ConstructorIOAPI.AddBatch(itemList, "Search Suggestions");

// products
List<ListItem> itemList = new List<ListItem>();

itemList.Add(new ListItem(
  Name: "Labradoodle",
  SuggestedScore: 360,
  Keywords: new string[]
  {
    "poodle",
    "labrador",
    "retriever"
  },
  URL: "http://www.mydogs.com/labradoodle",
  ImageUrl => "https://images.mydogs.com/labradoodle.jpg",
  Description: "A crossbreed dog created by crossing the Labrador Retriever and the Poodle",
  Metadata: new Dictionary<string, string>
  {
    { "animal", "dog" }
  },
  GroupIds: new string[]
  {
    "23",
    "45"
  }
));

itemList.Add(new ListItem(
  Name: "Australian Shepherd",
  SuggestedScore: 130,
  Keywords: new string[]
  {
    "aussie,
  },
  URL: "http://www.mydogs.com/australian_shepherd",
  ImageUrl: "https://images.mydogs.com/australian_shepherd.jpg",
  Description: "A medium-sized breed of dog developed on ranches in the Western United States",
  Metadata: new Dictionary<string, string>
  {
    { "animal", "dog" }
  },
  GroupIds: new string[]
  {
    "67",
    "89"
  }
));

bool success = ConstructorIOAPI.AddBatch(itemList, "Products");

The above command(s) return a 204 Success response on success.

To add multiple items to your index as a batch, use the POST /batch_items call. The items parameter is required and is a list of items with the same attributes as defined in the Add an Item resource. Because your autosuggest and search results can have multiple sections, like categories, search suggestions, and direct links to products, you must specify which section you are adding an item to. You can do this with the section parameter.

There is a limit of 1,000 items per batch request.

HTTP Request

POST https://ac.cnstrc.com/v1/batch_items?key=[your API key]

JSON Parameters

Parameter Required? Description
items Yes A list of items with the same attributes as defined in the Add an Item resource
section Yes Your autosuggest and search results can have multiple sections like "Products" and "Search Suggestions". This indicates which section this item is for. See your dashboard for the section names to use.

Batch Add or Update Items

# search suggestions
curl -X PUT -H "Content-Type: application/json" \
  -d '{"items": [ {"item_name": "Golden Retriever"}, {"item_name": "Poodle"} ],
    "section":"Search Suggestions"}' \
  -u"[your token]:" "https://ac.cnstrc.com/v1/batch_items?force=1&key=[your API key]"

# products
curl -X PUT -H "Content-Type: application/json" \
  -d '{
        "section":"Products",
        "items": [
          {
            "item_name": "Labradoodle",
            "suggested_score": 360,
            "keywords": ["poodle","labrador","retriever"],
            "url": "http://www.mydogs.com/labradoodle",
            "image_url": "https://images.mydogs.com/labradoodle.jpg",
            "description": "A crossbreed dog created by crossing the Labrador Retriever and the Poodle",
            "metadata": { "animal": "dog" },
            "group_ids": [ "23", "45" ]
          },
          {
            "item_name": "Australian Shepherd",
            "suggested_score": 130,
            "keywords": ["aussie"],
            "url": "http://www.mydogs.com/australian_shepherd",
            "image_url": "https://images.mydogs.com/australian_shepherd.jpg",
            "description": "A medium-sized breed of dog developed on ranches in the Western United States",
            "metadata": { "animal": "dog" },
            "group_ids": [ "67", "89" ]
          }
        ]
      }' \
  -u"[your token]:" "https://ac.cnstrc.com/v1/batch_items?force=1&key=[your API key]"
Not available
# search suggestions
response = constructorio.add_or_update_batch(
  {
    section: "Search Suggestions",
    items: [
      { item_name: "Golden Retriever" },
      { item_name: "Poodle" }
    ],
  }
)

# products
response = constructorio.add_or_update_batch(
  {
    section: "Products",
    items: [
      {
        item_name: "Labradoodle",
        suggested_score: 360,
        keywords: ["poodle", "labrador", "retriever"],
        url: "http://www.mydogs.com/labradoodle",
        image_url: "https://images.mydogs.com/labradoodle.jpg",
        description: "A crossbreed dog created by crossing the Labrador Retriever and the Poodle",
        metadata: { animal: "dog" },
        group_ids: ["23", "45"]
      },
      {
        item_name: "Australian Shepherd",
        suggested_score: 130,
        keywords: ["aussie"],
        url: "http://www.mydogs.com/australian_shepherd",
        image_url: "https://images.mydogs.com/australian_shepherd.jpg",
        description: "A medium-sized breed of dog developed on ranches in the Western United States",
        metadata: { animal: "dog" },
        group_ids: ["67", "89"]
      }
    ]
  }
)
# search suggestions
items = response = constructor_instance.add_or_update_batch(
  section="Search Suggestions",
  items=[
    {"item_name": "Golden Retriever"},
    {"item_name": "Poodle"}
  ]
)

# products
response = constructor_instance.add_or_update_batch(
    section="Products",
    items=[
      {
        "item_name": "Labradoodle",
        "suggested_score": 360,
        "keywords": ["poodle","labrador","retriever"],
        "url": "http://www.mydogs.com/labradoodle",
        "image_url": "https://images.mydogs.com/labradoodle.jpg",
        "description": "A crossbreed dog created by crossing the Labrador Retriever and the Poodle",
        "metadata": { "animal": "dog" },
        "group_ids": ["23","45"]
      },
      {
        "item_name": "Australian Shepherd",
        "suggested_score": 130,
        "keywords": ["aussie"],
        "url": "http://www.mydogs.com/australian_shepherd",
        "image_url": "https://images.mydogs.com/australian_shepherd.jpg",
        "description": "A medium-sized breed of dog developed on ranches in the Western United States",
        "metadata": { "animal": "dog" },
        "group_ids": ["67","89"]
      }
    ]
)
<?php
// search suggestions
$response = $constructorio->addOrUpdateBatch(
  array("Golden Retriever", "Poodle"),
  "Search Suggestions"
);

// products
$response = $constructorio->addOrUpdateBatch(
  array(
     array(
      "item_name" => "Labradoodle",
      "suggested_score" => 360,
      "keywords" => ["poodle","labrador","retriever"],
      "url" => "http://www.mydogs.com/labradoodle",
      "image_url" => "https://images.mydogs.com/labradoodle.jpg",
      "description" => "A crossbreed dog created by crossing the Labrador Retriever and the Poodle",
      "metadata" => array( "animal" => "dog" ),
      "group_ids" => ["23, "45"]
     ),
     array(
      "item_name" => "Australian Shepherd",
      "suggested_score" => 130,
      "keywords" => ["aussie"],
      "url" => "http://www.mydogs.com/australian_shepherd",
      "image_url" => "https://images.mydogs.com/australian_shepherd.jpg",
      "description" => "A medium-sized breed of dog developed on ranches in the Western United States",
      "metadata" => array( "animal" => "dog" ),
      "group_ids" => ["67, "89"]
     )
  )
  , "Products");
# search suggestions
my $response = $constructorio->add_or_update_batch(
  section => "Search Suggestions",
  items => [
    { item_name => "Golden Retriever" },
    { item_name => "Poodle" }
  ]
);

# products
my $response = $constructorio->add_or_update_batch(
  section: "Products",
  items: [
    {
      item_name => "Labradoodle",
      suggested_score => 360,
      keywords => ["poodle","labrador","retriever"],
      url => "http://www.mydogs.com/labradoodle",
      image_url => "https://images.mydogs.com/labradoodle.jpg",
      description => "A crossbreed dog created by crossing the Labrador Retriever and the Poodle",
      metadata => { animal => "dog" },
      group_ids => ["23", "45"]
    },
    {
      item_name => "Australian Shepherd",
      suggested_score => 130,
      keywords => ["aussie"],
      url => "http://www.mydogs.com/australian_shepherd",
      image_url => "https://images.mydogs.com/australian_shepherd.jpg",
      description => "A medium-sized breed of dog developed on ranches in the Western United States",
      metadata => { animal => "dog" },
      group_ids => ["67", "89"]
    }
  ]
)
ConstructorItem item1 = new ConstructorItem("Labradoodle");
item1.setSuggestedScore(360);
item1.setUrl("http://www.mydogs.com/labradawdle");
item1.setImageUrl("https://images.mydogs.com/labradawdle.jpg");
item1.setDescription("A crossbreed dog created by crossing the Labrador Retriever and the Pawdle");
item1.setKeywords(new ArrayList<>(Arrays.asList("pawdle","labrador","retriever")));

ConstructorItem item2 = new ConstructorItem("Australian Shepherd");
item2.setSuggestedScore(130);
item2.setUrl("http://www.mydogs.com/australian_shepherde");
item2.setImageUrl("hhttps://images.mydogs.com/australian_shepherde.jpg");
item2.setDescription("A medium-sized breed of doge developed on ranches in the Western United States");
item2.setKeywords(new ArrayList<>(Arrays.asList("aussiee")));

ConstructorItem[] items = { item1, item2 };
boolean success = constructorio.addOrUpdateItemBatch(items, "Products");
// search suggestions
List<ListItem> itemList = new List<ListItem>();
itemList.Add(new ListItem(
  Name: "Golden Retriever"
)
itemList.Add(new ListItem(
  Name: "Poodle"
)
bool success = ConstructorIOAPI.AddOrUpdateBatch(itemList, "Search Suggestions");

// products
List<ListItem> itemList = new List<ListItem>();

itemList.Add(new ListItem(
  Name: "Labradoodle",
  SuggestedScore: 360,
  Keywords: new string[]
  {
    "poodle",
    "labrador",
    "retriever"
  },
  URL: "http://www.mydogs.com/labradoodle",
  ImageUrl: "https://images.mydogs.com/labradoodle.jpg",
  Description: "A crossbreed dog created by crossing the Labrador Retriever and the Poodle",
  Metadata: new Dictionary<string, string>
  {
    { "animal", "dog" }
  },
  GroupIds: new string[]
  {
    "23",
    "45"
  }
));

itemList.Add(new ListItem(
  Name: "Australian Shepherd",
  SuggestedScore: 130,
  Keywords: new string[]
  {
    "aussie,
  },
  URL: "http://www.mydogs.com/australian_shepherd",
  ImageUrl: "https://images.mydogs.com/australian_shepherd.jpg",
  Description: "A medium-sized breed of dog developed on ranches in the Western United States",
  Metadata: new Dictionary<string, string>
  {
    { "animal", "dog" }
  },
  GroupIds: new string[]
  {
    "67",
    "89"
  }
));

bool success = ConstructorIOAPI.AddOrUpdateBatch(itemList, "Products");

The above command(s) return a 204 Success response on success.

A batch add or update allows you to add a group of items to your index without first checking to make sure no item in the batch already exists.

Any items that don't already exist are created, and any items that already exist are updated. This is also known as an UPSERT operation.

To add or update a batch of items to your index, use the PUT /batch_items call, with ?force=1. Options are the same as for the standard Batch Add Items call: item_name and section are required and all other parameters are optional.

We determine whether items already exist based on the item_name and section set for each item. However, if the optional id parameter is set for the items, we determine whether items already exist using this parameter.

There is a limit of 1,000 items per batch request.

HTTP Request

PUT https://ac.cnstrc.com/v1/batch_items?force=1&key=[your API key]

JSON Parameters

Parameter Required? Description
section Yes Your autosuggest and search reuslts can have multiple sections like "Products" and "Search Suggestions". This indicates which section this item is for. See your dashboard for the section names to use.
items Yes A list of items with the same attributes as defined in the Add an Item resource

Batch Patch Items

# search suggestions
curl -X PATCH -H "Content-Type: application/json" \
  -d '{"items": [ {"item_name": "Golden Retriever"}, {"item_name": "Poodle"} ],
    "section":"Search Suggestions"}' \
  -u"[your token]:" "https://ac.cnstrc.com/v1/batch_items?key=[your API key]"

# products
curl -X PATCH -H "Content-Type: application/json" \
  -d '{
        "section":"Products",
        "items": [
          {
            "item_name": "Labradoodle",
            "suggested_score": 360,
            "keywords": ["poodle","labrador","retriever"],
            "url": "http://www.mydogs.com/labradoodle",
            "image_url": "https://images.mydogs.com/labradoodle.jpg",
            "description": "A crossbreed dog created by crossing the Labrador Retriever and the Poodle",
            "metadata": { "animal": "dog" },
            "group_ids": [ "23", "45" ]
          },
          {
            "item_name": "Australian Shepherd",
            "suggested_score": 130,
            "keywords": ["aussie"],
            "url": "http://www.mydogs.com/australian_shepherd",
            "image_url": "https://images.mydogs.com/australian_shepherd.jpg",
            "description": "A medium-sized breed of dog developed on ranches in the Western United States",
            "metadata": { "animal": "dog" },
            "group_ids": [ "67", "89" ]
          }
        ]
      }' \
  -u"[your token]:" "https://ac.cnstrc.com/v1/batch_items?key=[your API key]"
Not available
Not available
# search suggestions
items = response = constructor_instance.patch_batch(
  section="Search Suggestions",
  items=[
    {"item_name": "Golden Retriever", "keywords": ["Gold"]},
    {"item_name": "Poodle", "keywords": ["Doodle"]}
  ]
)

# products
response = constructor_instance.patch_batch(
    section="Products",
    items=[
      {
        "item_name": "Labradoodle",
        "keywords": ["poodle","labrador","retriever","v2"],
        "url": "http://www.mydogs.com/labradoodle_v2",
        "image_url": "https://images.mydogs.com/labradoodle_v2.jpg",
        "group_ids": ["47"]
      },
      {
        "item_name": "Australian Shepherd",
        "suggested_score": 1300,
        "keywords": ["aussie", "v2"],
        "url": "http://www.mydogs.com/australian_shepherd_v2",
        "image_url": "https://images.mydogs.com/australian_shepherd_v2.jpg",
        "description": "A medium-sized breed of dog developed on ranches in the Western United States",
        "metadata": { "animal": "dog" },
        "group_ids": ["67","89"]
      }
    ]
)
Not available
Not available
Not available
Not available

The above command(s) return a 204 Success response on success.

To patch multiple items to your index as a batch, use the PATCH /batch_items call. The items parameter is required and is a list of items with the same attributes as defined in the Patch an Item resource. Because your autosuggest and search results can have multiple sections, like categories, search suggestions, and direct links to products, you must specify which section you are patching an item from. You can do this with the section parameter.

There is a limit of 1,000 items per batch request.

HTTP Request

PATCH https://ac.cnstrc.com/v1/batch_items?key=[your API key]

JSON Parameters

Parameter Required? Description
items Yes A list of items with the same attributes as defined in the Patch an Item resource
section Yes Your autosuggest and search results can have multiple sections like "Products" and "Search Suggestions". This indicates which section this item is for. See your dashboard for the section names to use.

Batch Remove Items

curl -X DELETE -H "Content-Type: application/json" \
  -d '{"items": [ {"item_name": "Labradoodle"}, {"id": "D26"} ],
    "section":"Products"}' \
  -u "[your token]:" "https://ac.cnstrc.com/v1/batch_items?key=[your API key]"
constructorio.removeItemBatch(
  {
    section: "Products",
    items: [
      { item_name: "Labradoodle" },
      { id: "D26" }
    ]
  },
  function(error, response) {
    if (error) {
      console.log(error);
    }
  }
);

response = constructorio.remove_batch(
  {
    section: "Products",
    items: [
      { item_name: "Labradoodle" },
      { id: "D26" }
    ],
  }
);
response = constructor_instance.remove_batch(
  section="Products",
  items=[
    {"item_name": "Labradoodle"},
    {"id": "D26"}
  ]
)
<?php
$items = array(
  array("item_name" => "Labradoodle"),
  array("id" => "D26")
);
$response = $constructorio->removeBatch($items, "Products");
# This method is not currently supported in our perl client.
ConstructorItem[] items = {
  new ConstructorItem("Labradoodle"),
  new ConstructorItem("Australian Shepherd")
}
boolean success = constructorio.removeItemBatch(items, "Products")
List<ListItem> itemList = new List<ListItem>();
itemList.Add(new ListItem(
  Name: "Labradoodle")
);
itemList.Add(new ListItem(
  ID: "D26")
);
bool success = ConstructorIOAPI.RemoveBatch(itemList, "Products");

The above command returns a 204 Success response on success.

To remove multiple items from your index as a batch, use the DELETE /batch_items call. Note: this will remove all meta-information such as keywords we currently store on the items.

The items parameter is required and is a list of items with the same attributes as defined in the Remove an Item resource. Because your autosuggest and search results can have multiple sections (i.e. products, categories, and search suggestions), you must specify the name of the section from which you're removing the items.

There is a limit of 1,000 items per batch request.

HTTP Request

DELETE https://ac.cnstrc.com/v1/batch_items?key=[your API key]

JSON Parameters

Parameter Required? Description
items Yes A list of items with the same attributes as defined in the Remove an Item resource.
section Yes Your autosuggest and search results can have multiple sections like "Products" and "Search Suggestions". This indicates which section this item is for. See your dashboard for the section names to use.

Add an Item

# search suggestion
curl -X POST -H "Content-Type: application/json" \
  -d '{"item_name": "Golden Retriever",
       "section": "Search Suggestions"}' \
  -u"[your token]:" "https://ac.cnstrc.com/v1/item?key=[your API key]"

# product
curl -X POST -H "Content-Type: application/json" \
  -d '{"item_name": "Labradoodle",
       "section":"Products",
       "suggested_score": 360,
       "keywords": ["poodle","labrador","retriever"],
       "url": "http://www.mydogs.com/labradoodle",
       "image_url": "https://images.mydogs.com/labradoodle.jpg",
       "description": "A crossbreed dog created by crossing the Labrador Retriever and the Poodle",
       "facets": {
           "Personality": ["Friendly", "Playful"]
       },
       "variations": [
           {
               "id": "labradoodle-brown",
               "facets": {
                   "Color": ["Brown"]
               },
               "image_url": "https://images.mydogs.com/labradoodle-brown.jpg",
               "suggested_score": 100,
               "metadata": {
                   "is_default": true
               }
           },
           {
               "item_name": "Black Labradoodle",
               "id": "labradoodle-black",
               "facets": {
                   "Color": ["Black"]
               },
               "image_url": "https://images.mydogs.com/labradoodle-black.jpg",
               "suggested_score": 200
           }
       ],
       "metadata": { "animal": "dog" },
       "group_ids": [ "23", "45" ]}'\
  -u"[your token]:" "https://ac.cnstrc.com/v1/item?key=[your API key]"
constructorio.addItem(
  {
    item_name: "Labradoodle",
    section: "Products",
    suggested_score: 360,
    keywords: ["poodle","labrador","retriever"],
    url: "http://www.mydogs.com/labradoodle",
    image_url: "https://images.mydogs.com/labradoodle.jpg",
    description: "A crossbreed dog created by crossing the Labrador Retriever and the Poodle",
    facets: {
        "Personality": ["Friendly", "Playful"],
    },
    variations: [
      {
        "id": "labradoodle-brown",
        "facets": {
          "color": ["Brown"]
        },
        "image_url": "https://images.mydogs.com/labradoodle-brown.jpg",
        "suggested_score": 100,
        "metadata": {
            "is_default": true
        }
      },
      {
        "id": "labradoodle-black",
        "facets": {
          "color": ["Black"]
        },
        "image_url": "https://images.mydogs.com/labradoodle-black.jpg",
        "suggested_score": 200
      }
    ]
    metadata: { "animal": "dog" },
    group_ids: [ "23", "45" ]
  },
  function(error, response) {
    if (error) {
      console.log(error);
    }
  }
);
# search suggestion
response = constructorio.add(
  {
    item_name: "Golden Retriever",
    section: "Search Suggestions"
  }
);

# product
response = constructorio.add(
  {
    item_name: "Labradoodle",
    section: "Products",
    suggested_score: 360,
    keywords: ["poodle","labrador","retriever"],
    url: "http://www.mydogs.com/labradoodle",
    image_url: "https://images.mydogs.com/labradoodle.jpg",
    description: "A crossbreed dog created by crossing the Labrador Retriever and the Poodle",
    facets: {
        "Personality": ["Friendly", "Playful"]
    },
    variations: [
      {
        "id": "labradoodle-brown",
        "facets": {
          "color": ["Brown"]
        },
        "image_url": "https://images.mydogs.com/labradoodle-brown.jpg",
        "suggested_score": 100,
        "metadata": {
            "is_default": true
        }
      },
      {
        "id": "labradoodle-black",
        "facets": {
          "color": ["Black"]
        },
        "image_url": "https://images.mydogs.com/labradoodle-black.jpg",
        "suggested_score": 200,
      }
    ]
    metadata: { "animal": "dog" },
    group_ids: [ "23", "45" ]
  }
);
# search suggestion
response = constructor_instance.add(
    item_name="Golden Retriever",
    section="Search Suggestions")

# product
response = constructor_instance.add(
    item_name="Labradoodle",
    section="Products",
    suggested_score=360,
    keywords=["poodle","labrador","retriever"],
    url="http://www.mydogs.com/labradoodle",
    image_url="https://images.mydogs.com/labradoodle.jpg",
    description="A crossbreed dog created by crossing the Labrador Retriever and the Poodle",
    facets={
        "Personality": ["Friendly", "Playful"]
    },
    variations=[
      {
        "id": "labradoodle-brown",
        "facets": {
          "color": ["Brown"]
        },
        "image_url": "https://images.mydogs.com/labradoodle-brown.jpg",
        "suggested_score": 100,
        "metadata": {
            "is_default": True
        }
      },
      {
        "id": "labradoodle-black",
        "facets": {
          "color": ["Black"]
        },
        "image_url": "https://images.mydogs.com/labradoodle-black.jpg",
        "suggested_score": 200,
      }
    ]
    metadata={ "animal": "dog" },
    group_ids=["23", "45"])
<?php
// search suggestion
$response = $constructorio->add(
  "Golden Retriever", // item name
  "Search Suggestions" // section name
);

// product
$response = $constructorio->add(
  "Labradoodle", // item name
  "Products", // section name
  array(
    "suggested_score" => 360,
    "keywords" => array("poodle", "labrador", "retriever"),
    "url" => "http://www.mydogs.com/labradoodle",
    "image_url" => "https://images.mydogs.com/labradoodle.jpg",
    "description" => "A crossbreed dog created by crossing the Labrador Retriever and the Poodle",
    "facets" => array(
        "Color" => "Brown",
        "Personality" => array("Friendly", "Playful"),
    ),
    "metadata" => array(
      "animal" => "dog"
    ),
    "group_ids" => array("23", "45")
  );
);
# search suggestion
my $response = $constructorio->add(
  item_name => "Golden Retriever",
  section => "Search Suggestions"
);

# product
my $response = $constructorio->add(
  item_name => "Labradoodle",
  section => "Products",
  suggested_score => 360,
  keywords => ["poodle","labrador","retriever"],
  url => "http://www.mydogs.com/labradoodle",
  image_url => "https://images.mydogs.com/labradoodle.jpg",
  description => "A crossbreed dog created by crossing the Labrador Retriever and the Poodle",
  facets => {
      "Personality" => ["Friendly", "Playful"]
  },
  variations => [
    {
      "id" => "labradoodle-brown",
      "facets" => {
        "color" => ["Brown"]
      },
      "image_url" => "https://images.mydogs.com/labradoodle-brown.jpg",
      "suggested_score" => 100,
      "metadata" => {
          "is_default" => 1
      }
    },
    {
      "id" => "labradoodle-black",
      "facets" => {
        "color" => ["Black"]
      },
      "image_url" => "https://images.mydogs.com/labradoodle-black.jpg",
      "suggested_score" => 200,
    }
  ],
  metadata => { "animal" => "dog" },
  group_ids => ["23", "45"]
);
ConstructorItem item = new ConstructorItem("Labradoodle");
item.setSuggestedScore(360);
item.setUrl("http://www.mydogs.com/labradoodle");
item.setImageUrl("https://images.mydogs.com/labradoodle.jpg");
item.setDescription("A crossbreed dog created by crossing the Labrador Retriever and the Poodle");
item.setKeywords(new ArrayList<>(Arrays.asList("poodle","labrador","retriever")));
boolean success = constructorio.addItem(item, "Products");
// search suggestion
ListItem item = new ListItem(
  Name: "Golden Retriever",
  AutocompleteSection: "Search Suggestion"
);
bool success = ConstructorIOAPI.Add(item);

// product
ListItem item = new ListItem(
  Name: "Labradoodle",
  AutocompleteSection: "Products",
  SuggestedScore: 360,
  Keywords: new string[]
  {
    "poodle",
    "labrador",
    "retriever"
  },
  URL: "http://www.mydogs.com/labradoodle",
  ImageURL: "https://images.mydogs.com/labradoodle.jpg",
  Description: "A crossbreed dog created by crossing the Labrador Retriever and the Poodle",
  Metadata: new Dictionary<string, string>
  {
      { "animal", "dog" }
  },
  GroupIds: new string[]
  {
    "23",
    "45"
  }
);
bool success = ConstructorIOAPI.Add(item);

The above command returns a 204 Success response on success.

To add an item to your index, use the POST /item call. The item_name is required. You can also pass in an optional suggested_score between 1 and 100 million, which will influence the item's initial ranking relative to other item scores (the higher the score, the higher in the list of suggestions the item will appear). You can also optionally pass in the item's keywords to give us more meta information and help us better determine how and where to display the item when autocompleting. If you would like to add an item that points to a direct link, just pass in that link as a url. Finally, because your autosuggest and search results can have multiple sections, like categories, search suggestions, and direct links to products, you must specify which section you are adding an item to. You can do this with the section parameter.

HTTP Request

POST https://ac.cnstrc.com/v1/item?key=[your API key]

JSON Parameters

Parameter Required? Description
item_name Yes The name of the item, as it will appear in the results
section Yes Your autosuggest and search results can have multiple sections like "Products" and "Search Suggestions". This indicates which section this item is for. See your dashboard for the section names to use.
suggested_score No A number between 1 and 100 million that will influence the item's initial ranking relative to other item scores (the higher the score, the higher in the list of suggestions the item will appear)
keywords No An array of keywords for this item. Keywords are useful if you want a product name to appear when a user enters a searchterm that isn't in the product name itself.
url No A URL to directly send the user after selecting the item
image_url No A URL that points to an image you'd like displayed next to some item (only applicable when url is supplied)
description No A description for some item (only applicable when url is supplied)
id No An arbitrary ID you would like associated with this item. You can use this field to store your own IDs of the items to more easily access them in other API calls.
facets No key/value pairs that can be associated with an item and used to filter them during a search. You can associate multiple values with the same key, by making values a list. Facets can be used as filters in search, autosuggest, and browse requests.
metadata No You can associate schema-less data with items by passing in an object of keys and values. To configure search and display of this data reach out to support@constructor.io.
group_ids No You can associate each item with one or more groups (i.e. categories). To set up a group hierarchy please contact support@constructor.io. group_ids can be used as filters in search, autosuggest, and browse requests.
variations No List of this item's variations. See Variations

Add or Update an Item

# search suggestion
curl -X PUT -H "Content-Type: application/json" \
  -d '{"item_name": "Golden Retriever",
       "section": "Search Suggestions"}' \
  -u"[your token]:" "https://ac.cnstrc.com/v1/item?force=1&key=[your API key]"

# product
curl -X PUT -H "Content-Type: application/json" \
  -d '{"item_name": "Labradoodle",
       "section":"Products",
       "suggested_score": 360,
       "keywords": ["poodle","labrador","retriever"],
       "url": "http://www.mydogs.com/labradoodle",
       "image_url": "https://images.mydogs.com/labradoodle.jpg",
       "description": "A crossbreed dog created by crossing the Labrador Retriever and the Poodle",
       "metadata": { "animal": "dog" }}',
       "group_ids": [ "23", "45" ]}'\
  -u"[your token]:" "https://ac.cnstrc.com/v1/item?key=[your API key]"
Not available
# search suggestion
response = constructorio.add_or_update(
  {
    item_name: "Golden Retriever",
    section: "Search Suggestions"
  }
);

# product
response = constructorio.add_or_update(
  {
    item_name: "Labradoodle",
    section: "Products",
    suggested_score: 360,
    keywords: ["poodle","labrador","retriever"],
    url: "http://www.mydogs.com/labradoodle",
    image_url: "https://images.mydogs.com/labradoodle.jpg",
    description: "A crossbreed dog created by crossing the Labrador Retriever and the Poodle",
    metadata: { "animal": "dog" },
    group_ids: [ "23", "45" ]
  }
);
# search suggestion
response = constructor_instance.add_or_update(
    item_name="Golden Retriever",
    section="Search Suggestions")

# product
response = constructor_instance.add_or_update(
    item_name="Labradoodle",
    section="Products",
    suggested_score=360,
    keywords=["poodle","labrador","retriever"],
    url="http://www.mydogs.com/labradoodle",
    image_url="https://images.mydogs.com/labradoodle.jpg",
    description="A crossbreed dog created by crossing the Labrador Retriever and the Poodle",
    metadata={ "animal": "dog" },
    group_ids=["23", "45"])
<?php
// search suggestion
$response = $constructorio->addOrUpdate(
  "Golden Retriever", // item name
  "Search Suggestions" // section name
);

// product
$response = $constructorio->addOrUpdate(
  "Labradoodle", // item name
  "Products", // section name
  array(
    "suggested_score" => 360,
    "keywords" => array("poodle", "labrador", "retriever"),
    "url" => "http://www.mydogs.com/labradoodle",
    "image_url" => "https://images.mydogs.com/labradoodle.jpg",
    "description" => "A crossbreed dog created by crossing the Labrador Retriever and the Poodle",
    "metadata" => array(
      "animal" => "dog"
    ),
    "group_ids" => array("23", "45")
  );
);
# search suggestion
my $response = $constructorio->add_or_update(
  item_name => "Golden Retriever",
  section => "Search Suggestions"
);

# product
my $response = $constructorio->add_or_update(
  item_name => "Labradoodle",
  section => "Products",
  suggested_score => 360,
  keywords => ["poodle","labrador","retriever"],
  url => "http://www.mydogs.com/labradoodle",
  image_url => "https://images.mydogs.com/labradoodle.jpg",
  description => "A crossbreed dog created by crossing the Labrador Retriever and the Poodle",
  metadata => { "animal" => "dog" },
  group_ids => ["23", "45"]
);
ConstructorItem item = new ConstructorItem("Labradoodle");
item.setSuggestedScore(360);
item.setUrl("http://www.mydogs.com/labradawdle");
item.setImageUrl("https://images.mydogs.com/labradawdle.jpg");
item.setDescription("A crossbreed dog created by crossing the Labrador Retriever and the Pawdle");
item.setKeywords(new ArrayList<>(Arrays.asList("pawdle","labrador","retriever")));
boolean success = constructorio.addOrUpdateItem(item, "Products");
// search suggestion
ListItem item = new ListItem(
  Name: "Golden Retriever",
  AutocompleteSection: "Search Suggestion"
);
bool success = ConstructorIOAPI.AddOrUpdate(item);

// product
ListItem item = new ListItem(
  Name: "Labradoodle",
  AutocompleteSection: "Products",
  SuggestedScore: 360,
  Keywords: new string[]
  {
    "poodle",
    "labrador",
    "retriever"
  },
  URL: "http://www.mydogs.com/labradoodle",
  ImageURL: "https://images.mydogs.com/labradoodle.jpg",
  Description: "A crossbreed dog created by crossing the Labrador Retriever and the Poodle",
  Metadata: new Dictionary<string, string>
  {
      { "animal", "dog" }
  },
  GroupIds: new string[]
  {
    "23",
    "45"
  }
);
bool success = ConstructorIOAPI.AddOrUpdate(item);

The above commands return a 204 Success response on success.

An add or update operation (also known as an UPSERT) updates an item in your index if it already exists, or adds the item to your index if it does not yet exist.

To add or update an item in your index, use the PUT /item call, with ?force=1. Options are the same as for the standard Add an Item call: item_name and section are required and all other parameters are optional.

We determine whether an item already exists based on the optional id set for the item, or if not present, the item_name and section.

HTTP Request

PUT https://ac.cnstrc.com/v1/item?force=1&key=[your API key]

JSON Parameters

Parameter Required? Description
item_name Yes The name of the item, as it will appear in the results
section Yes Your autosuggest and search results can have multiple sections like "Products" and "Search Suggestions". This indicates which section this item is for. See your dashboard for the section names to use.
suggested_score No A number between 1 and 100 million that will influence the item's initial ranking relative to other item scores (the higher the score, the higher in the list of suggestions the item will appear)
keywords No An array of keywords for this item. Keywords are useful if you want a product name to appear when a user enters a searchterm that isn't in the product name itself.
url No A URL to directly send the user after selecting the item
image_url No A URL that points to an image you'd like displayed next to some item (only applicable when url is supplied)
description No A description for some item (only applicable when url is supplied)
id No An arbitrary ID you would like associated with this item. You can use this field to store your own IDs of the items to more easily access them in other API calls.
metadata No You can associate schema-less data with items by passing in an array of keys and values. To configure search and display of this data reach out to support@constructor.io.
facets No key/value pairs that can be associated with an item and used to filter them during a search. You can associate multiple values with the same key, by making values a list. Facets can be used as filters in search, autosuggest, and browse requests.
group_ids No You can associate each item with one or more groups (i.e. categories). To set up a group hierarchy please contact support@constructor.io.

Retrieve Items

Retrieves all items for the given key and section, paginated by num_results_per_page, optionally filtered by id -- multiple ids represent an OR request, returning results including any of the provided ids. If id is specified in the URL, returns just the item with that id.

curl -X GET -H "Content-Type: application/json" \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/item?key=[your index key]&section=[section]"

curl -X GET -H "Content-Type: application/json" \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/item?key=[your index key]&section=[section]&id=1&id=2"

curl -X GET -H "Content-Type: application/json" \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/item/123?key=[your index key]&section=Products"
constructorio.getItem(
  {
    section: "Products"
  },
  function(error, response) {
    if (error) {
      console.log(error);
    }
  }
);
# This method is not currently supported in our ruby client.
# This method is not currently supported in our python client.
// This method is not currently supported in our php client.
# This method is not currently supported in our perl client.
// This method is not currently supported in our java client.
// This method is not currently supported in our csharp client.

HTTP Requests

GET https://ac.cnstrc.com/v1/item?key=[your index key]&section=[section]

GET https://ac.cnstrc.com/v1/item?key=[your index key]&section=[section]&id=[id]&id=[id]

GET https://ac.cnstrc.com/v1/item/[id]?key=[your index key]&section=[section]

Response format

{
  "items": [
    {
      "name": "[item_name]",
      "suggested_score": "[item_score]",
      "metadata": {[item_metadata]},
      "id": "[item_id]",
      "variations": [
        {
          "name": "[variation_name]",
          "suggested_score": "[variation_score]",
          "metadata": {[variation_metadata]},
          "id": "[variation_id]",
        }
      ]
    },
    {
      "name": "[another_item_name]",
      "suggested_score": "[another_item_score]",
      "metadata": {[another_item_metadata]},
      "id": "[another_item_id]"
    }
  ],
  "total_count": "[number_of_items]"
}

URL Parameters

Parameter Description
id The id of the item you'd like to retrieve.

Query Parameters

Parameter Required? Description
key Yes The index you'd like to to retrieve results from.
section Yes The index section you'd like to retrieve results from.
id No Id(s) of items to return.
num_results_per_page No The number of items to return. Defaults to 20. Maximum value 1,000.
page No The page of results to return. Defaults to 1.

Remove an Item

# remove by name
curl -X DELETE -H "Content-Type: application/json" \
  -d '{"item_name": "Golden Retriever",
       "section": "Search Suggestions"}' \
  -u "[your token]:" "https://ac.cnstrc.com/v1/item?key=[your API key]"

# remove by ID
curl -X DELETE -H "Content-Type: application/json" -d '{"item_name":"power drill","section":"products_autocomplete"}' \
  -u "[your token]:" "https://ac.cnstrc.com/v1/item?key=[your API key]"
// remove by name
constructorio.removeItem(
  {
    item_name: "Golden Retriever",
    section: "Search Suggestions"
  },
  function(error, response) {
    if (error) {
      console.log(error);
    }
  }
);

// remove by ID
constructorio.removeItem(
  {
    id: "D26",
    section: "Search Suggestions"
  },
  function(error, response) {
    if (error) {
      console.log(error);
    }
  }
);
# remove by name
response = constructorio.remove(
  {
    item_name: "Golden Retriever",
    section: "Search Suggestions"
  }
);

# remove by ID
response = constructorio.remove(
  {
    id: "D26",
    section: "Search Suggestions"
  }
);
# remove by name
response = constructor_instance.remove(
  item_name="Golden Retriever",
  section="Search Suggestions")
<?php
// remove by name
$response = $constructorio->remove(
  "Golden Retriever", // item name
  "Search Suggestions" // section name
);
# remove by name
my $response = $constructorio->remove(
  item_name => "Golden Retriever",
  section => "Search Suggestions"
);

# remove by ID
my $response = $constructorio->remove(
  id => "D26",
  section => "Search Suggestions"
);
ConstructorItem item = new ConstructorItem("Golden Retriever");
boolean success = constructorio.removeItem(item, "Products");
// remove by name
ListItem itemByName = new ListItem(
  Name: "Golden Retriever",
  AutocompleteSection: "Search Suggestions"
);

bool success = ConstructorIOAPI.Remove(itemByName);

ListItem itemByID = new ListItem(
  ID: "D26",
  AutocompleteSection: "Search Suggestions"
);

bool success = ConstructorIOAPI.Remove(itemByID);

The above command returns a 204 Success response on success.

To remove an item from your index (if, for instance, a product has been discontinued), issue a DELETE /item call. Note: this will remove all meta-information such as keywords we currently have on the item. Because autosuggest and search results can have multiple sections (i.e. products, categories, and search suggestions), you must specify the name of the section from which you're removing an item.

HTTP Request

DELETE https://ac.cnstrc.com/v1/item?key=[your API key]

JSON Parameters

Parameter Required? Description
item_name Yes * The name of the item, as it will appear in the results
section Yes Your autosuggest and search results can have multiple sections like "Products" and "Search Suggestions". This indicates which section this item is for. See your dashboard for the section names to use.
id Yes * An arbitrary ID you optionally specified when adding the item. If supplied, you don't need to pass in item_name.

* If you included an id along with the item that was previously added, you will need to provide the id when issuing the DELETE /item call. Otherwise, you can just specify item_name to delete the item.

Modify an Item

# search suggestion
curl -X PUT -H "Content-Type: application/json" \
  -d '{"item_name": "Golden Retriever",
       "new_item_name": "Breed: Golden Retriever",
       "section": "Search Suggestions"}' \
  -u"[your token]:" "https://ac.cnstrc.com/v1/item?key=[your API key]"

# product
curl -X PUT -H "Content-Type: application/json" \
  -d '{"item_name": "Labradoodle",
       "new_item_name": "Breed: Labradoodle",
       "section":"Products",
       "suggested_score": 360,
       "keywords": ["poodle","labrador","retriever"],
       "url": "http://www.mydogs.com/labradoodle",
       "image_url": "https://images.mydogs.com/labradoodle.jpg",
       "description": "A crossbreed dog created by crossing the Labrador Retriever and the Poodle",
       "metadata": { "animal": "dog" },
       "group_ids": [ "23", "45" ]}'\
  -u"[your token]:" "https://ac.cnstrc.com/v1/item?key=[your API key]"
Not available
# search suggestion
response = constructorio.modify(
  {
    item_name: "Golden Retriever",
    new_item_name: "Breed: Golden Retriever",
    section: "Search Suggestions"
  }
);

# product
response = constructorio.modify(
  {
    item_name: "Labradoodle",
    new_item_name: "Breed: Labradoodle",
    section: "Products",
    suggested_score: 360,
    keywords: ["poodle","labrador","retriever"],
    url: "http://www.mydogs.com/labradoodle",
    image_url: "https://images.mydogs.com/labradoodle.jpg",
    description: "A crossbreed dog created by crossing the Labrador Retriever and the Poodle",
    metadata: { "animal": "dog" },
    group_ids: [ "23", "45" ]
  }
);
# search suggestion
response = constructor_instance.modify(
    item_name="Golden Retriever",
    new_item_name="Golden Retriever",
    section="Search Suggestions")

# product
response = constructor_instance.modify(
    item_name="Labradoodle",
    new_item_name="Breed: Labradoodle",
    section="Products",
    suggested_score=360,
    keywords=["poodle","labrador","retriever"],
    url="http://www.mydogs.com/labradoodle",
    image_url="https://images.mydogs.com/labradoodle.jpg",
    description="A crossbreed dog created by crossing the Labrador Retriever and the Poodle",
    metadata={ "animal": "dog" },
    group_ids=["23", "45"])
<?php
// search suggestion
$response = $constructorio->modify(
  "Golden Retriever", // item name
  "Breed: Golden Retriever", // new item name
  "Search Suggestions" // section name
);

// product
$response = $constructorio->modify(
  "Labradoodle", // item name
  "Breed: Labradoodle", // new item name
  "Products", // section name
  array(
    "suggested_score" => 360,
    "keywords" => array("poodle", "labrador", "retriever"),
    "url" => "http://www.mydogs.com/labradoodle",
    "image_url" => "https://images.mydogs.com/labradoodle.jpg",
    "description" => "A crossbreed dog created by crossing the Labrador Retriever and the Poodle",
    "metadata" => array(
      "animal" => "dog"
    ),
    "group_ids" => array("23", "45")
  );
);
# search suggestion
my $response = $constructorio->modify(
  item_name => "Golden Retriever",
  new_item_name => "Breed: Golden Retriever",
  section => "Search Suggestions"
);

# product
my $response = $constructorio->modify(
  item_name => "Labradoodle",
  new_item_name => "Breed: Labradoodle",
  section => "Products",
  suggested_score => 360,
  keywords => ["poodle","labrador","retriever"],
  url => "http://www.mydogs.com/labradoodle",
  image_url => "https://images.mydogs.com/labradoodle.jpg",
  description => "A crossbreed dog created by crossing the Labrador Retriever and the Poodle",
  metadata => { "animal" => "dog" },
  group_ids => ["23", "45"]
);
String oldItemName = "Australian Shepard";
ConstructorItem item = new ConstructorItem("Australian Awesome Shepherd");
item.setSuggestedScore(130);
item.setUrl("http://www.mydogs.com/australian_shepherd");
item.setImageUrl("hhttps://images.mydogs.com/australian_shepherd.jpg");
item.setDescription("A medium-sized breed of dog developed on ranches in the Western United States");
item.setKeywords(new ArrayList<>(Arrays.asList("aussie")));
boolean success = constructorio.modifyItem(item, "Products", oldItemName);
// search suggestion
ListItem item = new ListItem(
  Name: "Golden Retriever", // old item name
  AutocompleteSection: "Search Suggestion"
);
item.Name = "Breed: Golden Retriever" // new item name
bool success = ConstructorIOAPI.Modify(item);

// product
ListItem item = new ListItem(
  Name: "Labradoodle", // old item name
  AutocompleteSection: "Products",
  SuggestedScore: 360,
  Keywords: new string[]
  {
    "poodle",
    "labrador",
    "retriever"
  },
  URL: "http://www.mydogs.com/labradoodle",
  ImageURL: "https://images.mydogs.com/labradoodle.jpg",
  Description: "A crossbreed dog created by crossing the Labrador Retriever and the Poodle",
  Metadata: new Dictionary<string, string>
  {
      { "animal", "dog" }
  },
  GroupIds: new string[]
  {
    "23",
    "45"
  }
);
item.Name = "Breed: Labradoodle" // new item name
bool success = ConstructorIOAPI.Modify(item);

The above command returns a 204 Success response on success.

To modify an item already in your index, use the PUT /item call. The item_name is required. You can also pass in an optional suggested_score between 1 and 100 million, which will influence the item's initial ranking relative to other item scores (the higher the score, the higher in the list of suggestions the item will appear). You can also optionally pass in the item's keywords to give us more meta information and help us better determine how and where to display the item when autocompleting. If the item should point to a direct link, just pass in that link as a url. Finally, because your autosuggest and search results can have multiple sections, like categories, search suggestions, and direct links to products, you must specify in which section you are modifying an item. You can do this with the section parameter.

Note: modifying an item replaces all meta information, such as keywords, we previously had on the item, but does not update the score unless you provide a new suggested_score.

HTTP Request

PUT https://ac.cnstrc.com/v1/item?key=[your API key]

JSON Parameters

Parameter Required? Description
item_name Yes The name of the item, as it currently appears in the results
new_item_name Yes The name of the item, as it you'd like it to appear in the results
section Yes Your autosuggest and search results can have multiple sections like "Products" and "Search Suggestions". This indicates which section this item is for. See your dashboard for the section names to use.
suggested_score No A number between 1 and 100 million that will influence the item's initial ranking relative to other item scores (the higher the score, the higher in the list of suggestions the item will appear)
keywords No An array of keywords for this item. Keywords are useful if you want a product name to appear when a user enters a searchterm that isn't in the product name itself.
url No A URL to directly send the user after selecting the item
image_url No A URL that points to an image you'd like displayed next to some item (only applicable when url is supplied)
description No A description for some item (only applicable when url is supplied)
id No An arbitrary ID you optionally specified when adding the item. If passed in, you don't need to pass in item_name.
facets No key/value pairs that can be associated with an item and used to filter them during a search. You can associate multiple values with the same key, by making values a list. Facets can be used as filters in search, autosuggest, and browse requests.
metadata No You can associate schema-less data with items by passing in an object of keys and values. To configure search and display of this data reach out to support@constructor.io.
group_ids No You can associate each item with one or more groups (i.e. categories). To set up a group hierarchy please contact support@constructor.io.

Patch an Item

# search suggestion
curl -X PATCH -H "Content-Type: application/json" \
  -d '{"item_name": "Golden Retriever",
       "section": "Search Suggestions"}' \
  -u"[your token]:" "https://ac.cnstrc.com/v1/item?force=1&key=[your API key]"

# product
curl -X PATCH -H "Content-Type: application/json" \
  -d '{"item_name": "Labradoodle",
       "section":"Products",
       "suggested_score": 360,
       "keywords": ["poodle","labrador","retriever"],
       "url": "http://www.mydogs.com/labradoodle",
       "image_url": "https://images.mydogs.com/labradoodle.jpg",
       "description": "A crossbreed dog created by crossing the Labrador Retriever and the Poodle",
       "metadata": { "animal": "dog" }}',
       "group_ids": [ "23", "45" ]}'\
  -u"[your token]:" "https://ac.cnstrc.com/v1/item?key=[your API key]"
Not available
Not available
# search suggestion
response = constructor_instance.patch(
    item_name="Golden Retriever",
    section="Search Suggestions")

# product
response = constructor_instance.patch(
    item_name="Labradoodle",
    section="Products",
    suggested_score=120,
    keywords=["poodle","labrador","retriever", "v2"],
    url="http://www.mydogs.com/labradoodle_v2",
    image_url="https://images.mydogs.com/labradoodle_v2.jpg",
    description="A crossbreed dog created by crossing the Labrador Retriever and the Poodle",
    group_ids=["47"])
Not available
Not available
Not available
Not available

The above commands return a 204 Success response on success.

The patch operation modifies an item's attributes in your index if the item already exists, or does nothing if the item does not exist. Every field except id and item_name can be patched.

To patch an item in your index, use the PATCH /item call. The options are the same as for the standard Add an Item resource: item_name and section are required and all other parameters are optional.

We determine whether an item already exists based on the optional id for the item, or if id is not present, the item_name and section.

Note that since the item_name parameter is mandatory, one can not use the Patch an Item resource to update the item name.

Also note that item attributes are patched independently: patching the image_url field will not affect the url field and vice versa. That is the main difference between the Patch an Item and the Modify an Item resource: Modify an Item replaces all meta information.

HTTP Request

PATCH https://ac.cnstrc.com/v1/item?key=[your API key]

JSON Parameters

Parameter Required? Description
item_name Yes The name of the item, as it will appear in the results
section Yes Your autosuggest and search results can have multiple sections like "Products" and "Search Suggestions". This indicates which section this item is for. See your dashboard for the section names to use.
suggested_score No A number between 1 and 100 million that will influence the item's initial ranking relative to other item scores (the higher the score, the higher in the list of suggestions the item will appear)
keywords No An array of keywords for this item. Keywords are useful if you want a product name to appear when a user enters a searchterm that isn't in the product name itself.
url No A URL to directly send the user after selecting the item
image_url No A URL that points to an image you'd like displayed next to some item (only applicable when url is supplied)
description No A description for some item (only applicable when url is supplied)
id No An arbitrary ID you would like associated with this item. You can use this field to store your own IDs of the items to more easily access them in other API calls.
facets No key/value pairs that can be associated with an item and used to filter them during a search. You can associate multiple values with the same key, by making values a list. Facets can be used as filters in search, autosuggest, and browse requests.
metadata No You can associate schema-less data with items by passing in an array of keys and values. To configure search and display of this data reach out to support@constructor.io.
group_ids No You can associate each item with one or more groups (i.e. categories). To set up a group hierarchy please contact support@constructor.io.

Responses

# shell responses will return raw JSON
// responses and errors that return data are JSON structures
console.log(response.message);
console.log(error.message);
# responses are Faraday objects with JSON bodies
puts response.status # print the status code
puts JSON(response.body)["message"]
# responses are converted to dictionaries for your convenience
response = constructor_instance.verify()
print response
# {u'message': u'successful authentication'}
<?php
// responses are converted to arrays for your convenience
$response = $constructorio->verify();
print_r($response);
// {
//   "message": "successful authentication"
// }
# responses are HTTP::Response objects
my $response = $constructorio->verify();

Most successful responses return 204 No Data codes without any further information.

Responses and errors that return data are JSON structures that will contain a "message" parameter with more information.

Variations

In an eCommerce context, items (products) are often offered in several variations, such as different sizes, fits and/or colors. Constructor's item API allows customers to define all the variations available for each item, so that end users can choose to filter on size, fit and/or color.

A single variation is a fully qualified product. For example, if an item comes in 3 sizes and 4 colors, you can upload 12 variations of that item, 1 for each size/color combination. All information that is shared across variations of a single item should be uploaded at the item level. All variation-specific information must be uploaded at the variation level.

Matching

Variation search and matching works like 'search within search'.

Constructor's search (as well as browse and autocomplete) first identifies all products that match a query (where a query encompasses a search term and zero or more filter selections; or a browse group id and zero or more filter selections).

Next Constructor searches within each item (typically, a product) to identify all matching variations for the query in question.

Finally, Constructor identifies the best matching variation among those that match the query. First the algorithm will look for any variation with is_default set to true, then will search for the best variation match based on NLP, ranking optimizations and variation suggested_score.

Results

Items are returned one-by-one, with the best matching variation's data presented at the top level for the item in question. Other matching variations are returned in an array on the item in question.

Endpoints

The item and bulk item endpoints can accept up to 100 variations on each product.

While the item update and patch methods allow updating certain fields on an item while leaving others untouched, the variation array must be updated in full when using the REST endpoints. However, the catalog update endpoints allow updating just certain variations.

Item Groups

Item groups allow customers to communicate information about the hierarchy of categories associated with their items (typically, their products). This information powers hierarchical category faceting and search-in-category autosuggest suggestions.

Hierarchy

The data about the hierarchy of item groups is edited independently of the item records themselves to allow flexibility to define or redefine group hierarchies.

Scope

Item groups are set at the level of each search key, so separate keys in one account can contain different group hierarchies.

Add item group

An item group can be added by passing its id, name, parent_id (the id of the parent item group if any) and data.

Add item group

curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{"name": "<item_group_name>", "parent_id": "<item_group_parent_id>", "data": {"foo": "bar"}}' \
  -u "[your token]:" \
  "https://ac.cnstrc.com/v1/item_groups/<item_group_id>?key=[your API key]"

Response

{
  "id": "<item_group_id>",
  "name": "<item_group_name>",
  "parent_id": "<item_group_parent_id>",
  "data": {"foo": "bar"}
}

HTTP request

PUT https://ac.cnstrc.com/v1/item_groups/[item_group_id]?key=[your API key]

JSON parameters

Parameter Required? Description
name No Item group display name.
parent_id No Parent item group customer ID or null for root item groups.
data No JSON object with custom metadata attached with the item group. Defaults to null if not provided.

Update item group

An item group can be updated by passing its id, name, parent_id (the id of the parent item group if any) and data. When only one of name, parent_id or data needs to be updated, the other one doesn't need to be passed in the request body.

Update item group

curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{"name": "<new_item_group_name>", "parent_id": "<new_parent_item_group_id>", "data": {"foo": "bar"}}' \
  -u "[your token]:" \
  "https://ac.cnstrc.com/v1/item_groups/<item_group_id>?key=[your API key]"

Response

{
  "id": "<item_group_id>",
  "name": "<new_item_group_name>",
  "parent_id": "<new_item_group_parent_id>",
  "data": {"foo": "bar"}
}

HTTP request

PUT https://ac.cnstrc.com/v1/item_groups/[item_group_id]?key=[your API key]

JSON parameters

Parameter Required? Description
name No Item group display name.
parent_id No Parent item group customer ID or null for root item groups.
data No JSON object with custom metadata attached with the item group.

Add multiple item groups

Item groups can be added to a key using a json payload that describes the item groups hierarchy using the following schema for each item group element:

Attributes Type Description
id string Item group customer ID.
name string Item group display name.
data object JSON object with custom metadata attached with the item group.
children List[item_group] List of item groups categorized under the current item group.

Note: Up to 1,000 item groups can be submitted in a single request. However, there is no limit to the depth of nested groups within an item group.

There are two different HTTP methods depending on the desired update semantics:

Insert new item groups and skip existing ones

Request example #1: json payload with new item groups

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
        "item_groups": [
          {
            "id": "<group_id_1>",
            "name": "<group_name_1>",
            "data": {"foo": "bar"}
          },
          {
            "id": "<group_id_2>",
            "name": "<group_name_2>"
          }
        ]
      }' \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/item_groups?key=[your API key]"

Response example #1: all new item groups were inserted

{
  "item_groups": {
    "processed": 2,
    "inserted": 2,
    "updated": 0
  }
}

Request example #2: json payload with updated item group

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
        "item_groups": [
          {
            "id": "<group_id_1>",
            "name": "<group_name_1>",
            "children": [
              {
                "id": "<group_id_2>",
                "name": "<new_group_name_2>",
                "data": {"foo": "bar"}
              }
            ]
          }
        ]
      }' \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/item_groups?key=[your API key]"

Response example #2: existing item group was skipped (not updated)

{
  "item_groups": {
    "processed": 2,
    "inserted": 0,
    "updated": 0
  }
}

HTTP request

POST https://ac.cnstrc.com/v1/item_groups?key=[your API key]

JSON parameters

Parameter Required? Description
item_groups Yes A list of item groups

Insert new item groups and update existing ones

Request example #3: add new item groups

curl -X PATCH \
  -H "Content-Type: application/json" \
  -d '{
        "item_groups": [
          {
            "id": "<group_id_3>",
            "name": "<group_name_3>",
          },
          {
            "id": "<group_id_4>",
            "name": "<group_name_4>"
          }
        ]
      }' \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/item_groups?key=[your API key]"

Response example #3: all new item groups were inserted

{
  "item_groups": {
    "processed": 2,
    "inserted": 2,
    "updated": 0
  }
}

Request example #4: json payload with updated item group

curl -X PATCH \
  -H "Content-Type: application/json" \
  -d '{
        "item_groups": [
          {
            "id": "<group_id_3>",
            "name": "<group_name_3>",
            "children": [
              {
                "id": "<group_id_4>",
                "name": "<new_group_name_4>"
              }
            ]
          }
        ]
      }' \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/item_groups?key=[your API key]"

Response example #4: existing item group was updated

{
  "item_groups": {
    "processed": 2,
    "inserted": 0,
    "updated": 1
  }
}

HTTP request

PATCH https://ac.cnstrc.com/v1/item_groups?key=[your API key]

JSON parameters

Parameter Required? Description
item_groups Yes A list of item groups

Get item groups

Retrieves item groups for a given key in a tree structure. If no group_id is specified, returns a list consisting of all top-level groups (groups without any parents), and their descendants. If a group_id is specified, returns a list consisting of the group with that group_id, and its descendants. All groups are linked to their children through the children field.

curl -X GET -H "Content-Type: application/json" \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/item_groups?key=[your API key]"

curl -X GET -H "Content-Type: application/json" \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/item_groups/123?key=[your API key]"
// This method is not currently supported in our javascript client.
# This method is not currently supported in our ruby client.
# This method is not currently supported in our python client.
// This method is not currently supported in our php client.
# This method is not currently supported in our perl client.
// This method is not currently supported in our java client.
// This method is not currently supported in our csharp client.

HTTP Requests

GET https://ac.cnstrc.com/v1/item_groups?key=[your API key]

GET https://ac.cnstrc.com/v1/item_groups/[group id]?key=[your API key]

Response format

Request example #1: get all item groups

curl -X GET -H "Content-Type: application/json" \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/item_groups?key=[your API key]"

Response example #1

{
  "item_groups": [{
    "id": "1",
    "name": "group 1",
    "data": {"foo": "bar"},
    "children": [{
      "id": "3",
      "name": "group 3",
      "data": null,
      "children": []
    }]
  }, {
    "id": "2",
    "name": "group 2",
    "data": null,
    "children": []
  }],
  "total_count": 3
}

Request example #2: get specific item group with id

curl -X GET -H "Content-Type: application/json" \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/item_groups/2?key=[your API key]"

Response example #2

{
  "item_groups": [{
    "id": "2",
    "name": "group 2",
    "data": null,
    "children": []
  }],
  "total_count": 1
}

URL Parameters

Parameter Description
group id The group id you'd like to retrieve results for.

Query Parameters

Parameter Required? Description
key Yes The index you'd like to to retrieve results from.

Delete item groups

Request example

# Delete item groups
curl -X DELETE \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/item_groups?key=[your API key]"

Response example

{
  "message": "We've started deleting all of your groups. This may take some time to complete."
}

Delete all item groups for a given key.

HTTP request

DELETE https://ac.cnstrc.com/v1/item_groups?key=[your API key]

Full Catalog

In the sections above, we have introduced ways to interact with items, variations and item groups. Here we present a way to update or replace the entire catalog in a single API call. We define the catalog as the set of all your item groups, items and variations. This endpoint can be useful if you want to sync the state of your entire catalog with constructor.

The number of items/variations you can upload at once through the catalog endpoint is unlimited. In order to support any number of updates, we ask you to upload items, variations and item groups using CSV files instead of including them in the JSON body of the request.

Once we receive all the provided CSV files, we will return the id of an asynchronous task that will process the data and perform the update in the background. You can check the status of that task using the Tasks API.

In order to avoid data inconsistencies, if the update fails for any of the provided resources, none of them will be updated. I.e: If there is an issue with data in the items file, we will not update any items, variations or item groups, even if the provided variations and/or item groups are themselves correct.

Should a catalog upload result in substantial changes to the existing items (defined for now as deleting more than 50% of items), it will be rejected. It's possible to override this behavior, as shown below.

All files should be UTF-8 encoded CSVs.

Replace the catalog (sync)

To replace all items, variations and/or item groups, use the PUT /v1/catalog endpoint. In this endpoint you may upload up to 3 files in the form data under the following keys: items, variations, item_groups. If you do not wish to replace one of these types of resources, then simply omit it from the request. For example, if you only provide an items and a variations file, we will keep the existing item_groups. Every uploaded file will be treated as a SYNC request, meaning that any records that already exist in the Constructor backend will be deleted & replaced with the records that you provide in the file. Below you can find the expected format for each of these CSV files:

HTTP Request

PUT https://ac.cnstrc.com/v1/catalog?key=[your API key]&section=[your section]&notification_email=[email]&force=True

URL Parameters

Attribute Type Required? Description
section string Yes The section that you want to update
notification_email string No An email address where you'd like to receive an email notifcation in case the task fails.
force boolean No Process the catalog even if it will invalidate a large number of existing items. Defaults to False.

Form Parameters

Attribute Type Required? Description
items CSV File No The CSV file with all new items
variations CSV File No The CSV file with all new variations
item_groups CSV File No The CSV file with all new item_groups

Response format

{
    "task_id": 1,
    "task_status_path": "/v1/task/1"
}
# Replace all items, variations and/or item groups.
curl -X PUT \
    -F 'items=@path/to/items.csv' \
    -F 'variations=@path/to/variations.csv' \
    -F 'item_groups=@path/to/item_groups.csv' \
    -u"[your token]:" "https://ac.cnstrc.com/v1/catalog?key=[your API key]&section=[your section]&notification_email=[email]&force=True"

// This method is not currently supported in our javascript client.
# This method is not currently supported in our ruby client.
# This method is not currently supported in our python client.
// This method is not currently supported in our php client.
# This method is not currently supported in our perl client.
// This method is not currently supported in our java client.
// This method is not currently supported in our csharp client.

Update the catalog (delta)

To update specific items, variations and/or item groups, use the PATCH /v1/catalog endpoint. In this endpoint you may upload up to 3 files in the form data under the following keys: items, variations, item_groups. Each of these files must contain only the records that you want to update. Any other records that may exist in the backend will remain unaffected. This may be useful for example to send inventory updates, deactivate items that are out of stock, or introduce new categories. The expected file format is the same as the one in the Replace the catalog section. The response format is also the same.

# Update some items, variations and/or item groups
curl -X PATCH \
    -F 'items=@path/to/items.csv' \
    -F 'variations=@path/to/variations.csv' \
    -F 'item_groups=@path/to/item_groups.csv' \
    -u"[your token]:" "https://ac.cnstrc.com/v1/catalog?key=[your API key]&section=[your section]&notification_email=[email]&force=True"
// This method is not currently supported in our javascript client.
# This method is not currently supported in our ruby client.
# This method is not currently supported in our python client.
// This method is not currently supported in our php client.
# This method is not currently supported in our perl client.
// This method is not currently supported in our java client.
// This method is not currently supported in our csharp client.

Autocomplete

Autocomplete Queries

curl -X GET -H "Content-Type: application/json" \
"https://ac.cnstrc.com/autocomplete/[query]?key=[your API key]" \
"&filters[group_id]=123"
constructorio.getAutocompleteResults(
  {
    query: "dog",
  }, {
    s: "user",
    i: 1
  }, (error, response) => {
    if (error) {
      console.log(error);
    }
});
# The autocomplete query endpoint is not implemented for backend libraries.
# Please refer to shell documentation or our Javascript (front-end) client.
# The autocomplete query endpoint is not implemented for backend libraries.
# Please refer to shell documentation or our Javascript (front-end) client.
<?php
// The autocomplete query endpoint is not implemented for backend libraries.
// Please refer to shell documentation or our Javascript (front-end) client.
# The autocomplete query endpoint is not implemented for backend libraries.
# Please refer to shell documentation or our Javascript (front-end) client.
AutocompleteResponse result = constructorio.autocomplete("Pood");
// The autocomplete query endpoint is not implemented for backend libraries.
// Please refer to shell documentation or our Javascript (front-end) client.

The above command returns a 200 Success response on success.

Refer here for shell documentation, and here for instructions on installing our Javascript (front-end) client.

You can try out an autocomplete query on your dataset by typing the following URL into a web browser: https://ac.cnstrc.com/autocomplete/[query]?key=[your API key], replacing [query] with the query you'd like to make, and [your API key] with your API key.

Want to try it right now? You can search for labrador from our demo list of dog breeds here.

When implementing our autocomplete on a website, we recommend most customers use our Javascript (front-end) client. For other uses, such as within native or mobile apps, we recommend customers issue HTTP requests to our API.

HTTP Request

GET https://ac.cnstrc.com/autocomplete/[query]?key=[your API key]

Parameters

Parameter Required? Description
query Yes The URL-encoded autocomplete query.
key Yes The key for the autocomplete you would like to query.
num_results No The number of results to return across all sections in the autocomplete (rounded down if num_results isn't divisible by the number of autocomplete sections).
num_results_[section_name] No The number of results to return from autocomplete section section_name. section_name is URL encoded, so 3 results from section Dog Breeds would be num_results_Dog%20Breeds=3. A single request can include several of these parameters to specify the number of results to return from multiple sections.
filters No A filter to be applied to autocomplete requests, so that only results that have that filter are returned. You can use facets or group_ids as filters. Autosuggest calls allow a maximum of one filter to be applied.

Autocomplete Responses: Overview

Constructor.io's autocomplete returns easy-to-process JSON responses.

Response structure: Sections

Autocomplete responses are returned in discrete sections. Most typically there will be two such sections: Products and Search Suggestions. The purpose of these is as follows:

These are the typical sections, but we also support suggesting category page results, store locations, etc. You can work with our Implementation Engineering team to define and optimize other entities you'd like to search within.

{
  "request": {
    ...
  },
  "response": {
    "sections": {
      "Search Suggestions": [
        ...
      ],
      "Products": [
        ...
      ]
    }
  }
}

Response structure: Request object

Within each autocomplete response JSON, we include data on the submitted request.

Values with a default as well as the autocompleted term will always be returned. Otherwise, only given parameters will be returned within the request data.

We intentionally omit the following parameters from the response request object for privacy reasons: key, c, i, ui, s, _dt

Example: For the query 'https://ac.cnstrc.com/autocomplete/bird%20food?key=[your_key]' we might get the following request info: json { "request": { "term": "bird food" }, "response": { "sections": { ... } } }

Response structure: Value & matched terms

All autosuggest responses will include at least two fields:

{
  "sections": {
    "Search Suggestions": [
      {
        "data": [
          ...
        ],
        "matched_terms": [
          "dog food"
        ],
        "value": "mccormick's farmstand dog food"
      },
      ...
    ],
    "Products": [
      {
        "data": [
          ...
        ],
        "matched_terms": [
          "dog food"
        ],
        "value": "McCormick's Farmstand Small Bites Potato & Duck Formula Dog Food"
      },
      ...
    ]
  }
}

Autocomplete Responses: Search Suggestions

Search Suggestions and Products response structures are broadly similar, but reviewing them individually is helpful as certain fields are more common or bear different significance depending on their location.

Search Suggestions: Groups

One of the most important roles of autosuggest is to clarify ambiguous queries. By leveraging Constructor's category suggestions, we can help users clarify their intent. Users often make over-broad searches like shirts which may be men's or women's shirts or juniors shirts.

User types shirt

Autosuggest returns: Shirts in Women's Clothing in Men's Clothing in Juniors' Clothing

Each Search Suggestion is returned with a data array containing Constructor's ordered recommendations for group suggestions.

The contents of this array are configurable, but most often include the following fields:

{
  "sections": {
    "Search Suggestions": [
      {
        "data": {
          "groups": [
            {
              "display_name": "Women's Clothing",
              "group_id": "394",
              "path": "/95/394/"
            },
            {
              "display_name": "Men's Clothing",
              "group_id": "339",
              "path": "/95/339/"
            },
            {
              "display_name": "Juniors' Clothing",
              "group_id": "455",
              "path": "/95/455/"
            }
          ],
        },
        "matched_terms": [
          "dog"
        ],
        "value": "Natural Balance Small Bites Potato & Duck Formula Dog Food"
      }
    ],
    "Products": [
      ...
    ]
  }
}

Autocomplete Responses: Products

Products are typically the main items a company is interested in promoting so typically have the most metadata associated with them.

Products: Common fields

In addition to the value and matched_terms always returned, Constructor can display any data that's been uploaded for the items in question, which is returned in a data object. We'll go over a typical subset below:

Additional Data (may not be present)

The autocomplete response format for product data matches the search response format.

Search

Constructor.io's Search Platform provides the speed, intelligent matching and advanced learning necessary to drive conversions.

Constructor.io supports integrating with our Search Platform via our RESTful API to ensure maximum compatibility with all existing customer front-end search UIs.

Search Queries

curl -X GET -H "Content-Type: application/json" \
"https://ac.cnstrc.com/search/[query]?key=[your API key]"

# search the dog breed data set for "sheep", show 2 results per page and the 3rd page of results.
curl -X GET -H "Content-Type: application/json" \
"https://ac.cnstrc.com/search/sheep?key=pAFl6rReRSI0uXckcxZS&num_results_per_page=2&page=3"

# search for figs, but only return results within the cookies category.
curl -X GET -H "Content-Type: application/json" \
"https://ac.cnstrc.com/search/figs?key=example_key&filters%5Bgroup_id%5D=COOKIES_CATEGORY_ID"

# search cashmere dog sweaters, but show the cheapest ones first
curl -X GET -H "Content-Type: application/json" \
"https://ac.cnstrc.com/search/cashmere%20dog%20sweaters?key=example_key&sort_by=price&sort_order=ascending"

# pass additional user segments to take into account in redirect rule evaluation
curl -X GET -H "Content-Type: application/json" \
"https://ac.cnstrc.com/search/[query]?key=[your API key]&us=<user-segment#1>&us=<user-segment#2>"

constructorio.getSearchResults(
  {
    query: "milk",
    section: "Products"
  }, {
    s: "user",
    i: 1
  }, (error, response) => {
    if (error) {
      console.log(error);
    }
});

The above command returns a 200 Success response on success.

HTTP Request

GET https://ac.cnstrc.com/search/[query]?key=[your API key]&filters[group_id]=123&filters[Color]=Brown&filters[Color]=White&filters[Price]=100-200&fmt_options[groups_start]=current&fmt_options[groups_max_depth]=1

Option Default Description
page 1 The page number of the results
num_results_per_page 20 The number of results per page to return
num_results_per_page_[section] n/a The number of results per page for a given section (when a dataset has multiple sections). Results from sections that were not included in the request will not be returned at all.
filters[filter_name]=filter_value n/a Any number of criteria by which you'd like to narrow the result set. This might be by color, size, or category (group) an item belongs to. Facets (uploaded through the Add an Item API) and group ids can be used as filters. Filters with the same key are ORed together, while filters with different keys are ANDed together by default. If filter_value has the form <min>-<max>, it's interpreted as a range (e.g: filters[Price]=100-200 will match all items with Price from 100 to 200).
fmt_options[groups_start] current Either current or top. Specifies the top-level group that should be returned in the response. If a group_id is provided in filters and the value for this option is current, we'll return groups starting from the currently selected one. If the value is top, we will always start returning groups from the root category in the hierarchy, regardless of which one is selected
fmt_options[groups_max_depth] 1 Maximum depth of the group hierarchy that should be included in the response.
sort_by relevance The criteria by which search results should be sorted. The default value relevance sorts by Constructor.io's relevance & personalization algorithms and is reserved. Please reach out to support@constructor.io to define alternate sort criteria.
sort_order descending Either descending or ascending. The sort order by which search results should be sorted. Only valid in conjunction with sort_by.
us None User segment is a client context value (such as platform, location, etc.) that is used to evaluate redirect or refined tag rules. You can supply multiple segments by passing multiple us arguments.

Search Results

Constructor.io's search engine returns easy-to-process JSON responses, including both data on what was requested and the response for your query.

The response format is as follows:

Result structure overview

{
  "request": {
    ...
  }
  "response": {
    "facets": [
      ...
    ],
    "groups": [
      ...
    ],
    "sort_options": [
      ...
    ],
    "results": [
      ...
    ],
    "total_num_results": 454
  }
}

Sections

Constructor.io defaults to provide search results only for the Products section of a customer's search index.

Groups, facets, sort_options, results

Within each result section, there are four arrays returned, and a summary of the total count of results within that section total_num_results.

The four groups are described below:

Search: Request object

To simplify the interpretation of results and pairing a given request with the relevant response, the search endpoint will 'parrot back' the request that was understood by the search service in the request object.

Values with a default (ie. page, num_results_per_page, section) will always be returned. Otherwise, only the provided parameters will be returned within the request data.

We intentionally omit the following parameters from the response request object for privacy reasons: key, c, i, ui, s, _dt

Example: For the query '/search/food?key=[your API key]&num_results_per_page=75&filter['animal_type']=bird' we might get the following request info:

{
  "request": {
    "page": 1,
    "num_results_per_page": 75,
    "term": "food",
    "section": "Products",
    "sort_by": "relevance",
    "sort_order": "descending",
    "fmt_options": {
      "groups_max_depth": 1,
      "groups_start": "current"
    },
    "filters": {
      "animal_type": ["bird"]
    },
    "filter_match_types": {
      "animal_type": "any"
    }
  },
  "response": {
    "facets": [
      ...
    ],
    "groups": [
      ...
    ],
    "sort_options": [
      ...
    ],
    "results": [
      ...
    ]
  }
}

Search: Results structure

{
  "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
  }
}

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.

Default Data

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

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)

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:

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

Search: Groups structure

Groups Intro

Groups are typically used to indicate high-level categories for products. Each search query will return all groups associated with items in the result set.

Flat group listings

{
  "request": {
    ...
  },
  "response": {
    "facets": [
      ...
    ],
    "groups": [
      {
        "children": [],
        "count": 33,
        "display_name": "Baby Care Products",
        "group_id": "baby_care_products",
        "parents": []
      },
      {
        "children": [],
        "count": 11,
        "display_name": "Beverages",
        "group_id": "beverages",
        "parents": []
      },
    ],
    "sort_options": [
      ...
    ],
    "results": [
      ...
    ],
    "total_num_results": 44
  }
}

If the index searched just has a flat group hierarchy, a flat array of groups is returned, with empty arrays for children and parents fields.

Notice in this example that total_num_results is the sum of the count for each group. In this example, no products are a member of more than one group.

Groups fields

field_name Always present? Description
display_name Yes The name of the group as you'd present it to users.
group_id Yes The id of the group. Any ASCII characters can be used.
children Not when group is in parents array An array of groups that are 'children' of the group in question i.e. hierarchically below. Empty if no children.
count Not when group is in parents array The number of item results within the group that match the search query.
parents Not when group is in children array The group_id of any parents. Empty for top-level categories.

Hierarchical group listings

{
  "request": {
    ...
  },
  "response": {

    "facets": [
      ...
    ],
    "groups": [
      {
        "children": [
          {
            "children": [],
            "count": 2,
            "display_name": "Baby Hair Brushes",
            "group_id": "baby_hair_brushes"
          },
          {
            "children": [],
            "count": 3,
            "display_name": "Diapers",
            "group_id": "diapers"
          }
        ],
        "count": 5,
        "display_name": "Baby Care Products",
        "group_id": "baby_care_products",
        "parents": []
      },
      {
        "children": [],
        "count": 5,
        "display_name": "Beverages",
        "group_id": "beverages",
        "parents": []
      },
    ],
    "sort_options": [
      ...
    ],
    "results": [
      ...
    ],
    "total_num_results": 10
  }
}

If an index has a hierarchy of groups, we return the full list of groups with results matching the search query, with children groups returned within the children array of their parent group.

Notice in this example that the count for parent category Baby Care Products is the sum of its children, and total_num_results is the sum of the count for each top-level group. In this example, no products are a member of more than one group.

Search: Facets structure

{
  "request": {
    ...
  },
  "response": {
    "facets": [
      {
        "name": "Brand",
        "display_name": "Brand",
        "type": "multiple",
        "data": {},
        "options": [
          {
            "value": "Natural Balance",
            "display_name": "Natural Balance",
            "data": {},
            "status": "",
            "count": 8
          },
          {
            "value": "WholeHearted",
            "display_name": "WholeHearted",
            "data": {
              "image_url": "https://www.example.com/image.png"
            },
            "status": "selected",
            "count": 10
          }
        ]
      },
      {
        "name": "rating",
        "display_name": "Rating",
        "type": "single",
        "data": {},
        "options": [
          {
            "value": "4-inf",
            "display_name": "4 and more",
            "data": {},
            "status": "",
            "count": 13,
          },
          {
            "value": "3-inf",
            "display_name": "3 and more",
            "status": "selected",
            "data": {},
            "count": 16,
          },
          {
            "value": "2-inf",
            "display_name": "2 and more",
            "status": "",
            "data": {},
            "count": 18,
          },
          {
            "value": "1-inf",
            "display_name": "1 and more",
            "data": {},
            "status": "",
            "count": 19,
          },
        ]
      },
      {
        "name": "price",
        "display_name": "Price",
        "type": "range",
        "data": {},
        "min": 0,
        "max": 265,
        "status": {
          "min": 100,
          "max": 200,
        }
      }
    ],
    "groups": [
      ...
    ],
    "sort_options": [
      ...
    ],
    "results": [
      ...
    ],
    "total_num_results": 10
  }
}

Facets fields

field_name Always present? Description
name Yes The name of the facet. This should be passed in the filters parameter when a facet of this type is selected. filters[name]=value
display_name Yes The display name of the facet. This can be used for displaying the facet name, but it's not necessarily the value that needs to be passed in filters.
type Yes Either "single", "multiple", or "range". If a facet is of type single, then only one of the options may be selected (e.g: display as radio button). If the type is multiple, then multiple options may be selected (e.g: display as checkboxes). If the type is range, then no options are provided. Instead a min and max value is provided to specify the range of values that can be sent in filters. To configure the types of your facets, please reach out to support@constructor.io.
status No Object containing min and max values. Only provided at the facet field level for facets of type range. Specifies the currently selected range. If no range is currently selected, status will be an empty object ({})
options No The list of possible facet values matching this search. Only provided if type is single or multiple. By default, facet options are sorted by relevance. To configure the sort order of your facet options, please reach out to support@constructor.io.
data Yes Object containing custom data associated with this facet. An empty object ({}) if no data is currently associated with this facet. If you need help associating custom data with your facets, please reach out to support@constructor.io.

Facet option fields

field_name Always present? Description
value Yes The value that should be passed in filters to select this option: filters[name]=value
display_name Yes Display name of the facet option. This can be used for displaying the facet option, but it's not necessarily the value that needs to be passed in filters
status Yes "selected" if this option is selected in the current search request, empty string ("") otherwise.
data Yes Object containing custom data associated with this facet option. An empty object ({}) if no data is currently associated with this option. If you need help associating custom data with your facet options, please reach out to support@constructor.io.
count Yes Number of items in the current search that match this option.

Search: Redirect structure

When a search query matches any redirect rule previously configured using the redirect rules endpoint, then the response uses the redirect structure with the following attributes:

Redirect structure

{
  "request": {
    ...
  },
  "response": {
    "redirect": {
      "data": {
        "url": "<url>"
      },
      "matched_terms": [
        "<a term>",
        "<another term>",
      ],
      "matched_user_segments": [
        "<a segment>",
        "<another segment>",
      ]
    }
  }
}

Attribute Type Description
redirect object Object containing information about the match.
redirect.data object Object containing the target URL together with any metadata defined in the redirect rule.
redirect.matched_terms List[string] A list of all the terms in the redirect match definition that matched the search query.
redirect.user_segments List[string] A list of all the user segmentes in the redirect match definition that matched the search query.

Search: Sort options structure

Sort options Intro

Sort options are different ways in which you can request the results to be sorted. By default results are sorted by relevance (i.e: most relevant items to the query in question come first), but you can choose to sort them by price or any other property. To set up custom sort options for your dataset, please reach out to support@constructor.io.

Sort options structure

{
  "request": {
    ...
  },
  "response": {
    "facets": [
      ...
    ],
    "groups": [
      ...
    ],
    "sort_options": [
      {
        "sort_by": "relevance",
        "sort_order": "descending",
        "display_name": "Most Relevant",
        "status": "selected"
      },
      {
        "sort_by": "price",
        "sort_order": "descending",
        "display_name": "Price, High to Low",
        "status": ""
      },
      {
        "sort_by": "price",
        "sort_order": "ascending",
        "display_name": "Price, Low to High",
        "status": ""
      },
      {
        "sort_by": "brand",
        "sort_order": "ascending",
        "display_name": "Brand name, A-Z",
        "status": ""
      },
      {
        "sort_by": "brand",
        "sort_order": "descending",
        "display_name": "Brand name, Z-A",
        "status": ""
      }
    ],
    "results": [
      ...
    ],
    "total_num_results": 454
  }
}

Sort options fields

field_name Always present? Description
sort_by Yes The name of the attribute results will be sorted by. The value of this field should be passed to the sort_by query string parameter in the search request when this option is selected.
sort_order Yes Either "descending" or "ascending". The value of this attribute should be passed to the sort_order query string parameter in the search request when this option is selected.
display_name Yes The user-friendly name of this sort option that should be displayed to users.
status Yes "selected" if this option is selected in the current search request, empty string ("") otherwise.

Browse

Constructor.io's Browse Platform provides the speed, intelligent matching and advanced learning necessary for a category page.

Constructor.io supports integrating with our Browse Platform via our RESTful API to ensure maximum compatibility with all existing customer front-end UIs.

Browse Queries

curl -X GET -H "Content-Type: application/json" \
"https://ac.cnstrc.com/browse/[filter_name]/[filter_value]?key=[your API key]"

# Browse Spring Break Sale collection
curl -X GET -H "Content-Type: application/json" \
"https://ac.cnstrc.com/browse/collection_id/spring_break_sale?key=pAFl6rReRSI0uXckcxZS"

# Browse categories for dogs, show 2 results per page and the 3rd page of results.
curl -X GET -H "Content-Type: application/json" \
"https://ac.cnstrc.com/browse/group_id/dogs?key=pAFl6rReRSI0uXckcxZS&num_results_per_page=2&page=3"

HTTP Request

GET https://ac.cnstrc.com/browse/[filter_name]/[filter_value]?key=[your API key]&filters[Color]=Brown&filters[Color]=White&filters[Price]=100-200&fmt_options[groups_start]=current&fmt_options[groups_max_depth]=1

URL Parameters

Option Default Description
page 1 The page number of the results
num_results_per_page 20 The number of results per page to return
filters[filter_name]=filter_value n/a Any number of criteria by which you'd like to narrow the result set. This might be by color, size, or category (group) an item belongs to. Facets (uploaded through the Add an Item API) and group ids can be used as filters. Filters with the same key are ORed together, while filters with different keys are ANDed together by default. If filter_value has the form <min>-<max>, it's interpreted as a range (e.g: filters[Price]=100-200 will match all items with Price from 100 to 200).
fmt_options[groups_start] current Either current or top. Specifies the top-level group that should be returned in the response. If a group_id is provided in filters and the value for this option is current, we'll return groups starting from the currently selected one. If the value is top, we will always start returning groups from the root category in the hierarchy, regardless of which one is selected
fmt_options[groups_max_depth] 1 Maximum depth of the group hierarchy that should be included in the response.
sort_by relevance The criteria by which browse results should be sorted. The default value relevance sorts by Constructor.io's relevance & personalization algorithms and is reserved. Please reach out to support@constructor.io to define alternate sort criteria.
sort_order descending Either descending or ascending. The sort order by which browse results should be sorted. Only valid in conjunction with sort_by.
us None User segment is a client context value (such as platform, location, etc.) that is used to evaluate redirect and refined tag rules. You can supply multiple segments by passing multiple us arguments.

Browse Results

Constructor.io's browse returns easy-to-process JSON responses (similar to search endpoint), including both data on what was requested and the response for your query.

The response format is as follows:

Result structure overview

{
  "request": {
      ...
  },
  "response": {
    "features": [
      ...
    ],
    "facets": [
      ...
    ],
    "collection": {
      ...
    },
    "groups": [
      ...
    ],
    "sort_options": [
      ...
    ],
    "results": [
      ...
    ],
    "total_num_results": 454
  }
}

Sections

Constructor.io defaults to provide browse results only for the Products section of a customer's browse index.

Groups, facets, features, sort_options, results

There are five arrays returned in the results, and a summary of the total count of results total_num_results. When requesting a collection, a collection object is also returned.

Browse: Request object

To simplify the interpretation of results and pairing a given request with the relevant response, the browse endpoint will 'parrot back' the request that was understood by the browse service in the request object.

Values with a default (ie. page, num_results_per_page, section) will always be returned. Otherwise, only the provided parameters will be returned within the request data.

We intentionally omit the following parameters from the response request object for privacy reasons: key, c, i, ui, s, _dt

Example: For the query '/browse/group_id/food?key=[your API key]&num_results_per_page=75&filter['animal_type']=bird' we might get the following request info:

{
  "request": {
    "browse_filter_name": "group_id",
    "browse_filter_value": "food",
    "page": 1,
    "num_results_per_page": 75,
    "term": "",
    "section": "Products",
    "sort_by": "relevance",
    "sort_order": "descending",
    "fmt_options": {
      "groups_max_depth": 1,
      "groups_start": "current"
    },
    "filters": {
      "animal_type": ["bird"]
    },
    "filter_match_types": {
      "animal_type": "any"
    },
    "features": {
      "auto_generated_refined_query_rules": true,
      "manual_searchandizing": true,
      "personalization": true,
      "query_items": true
    }
  }
}

Browse: Results structure

{
  "request": {
    ...
  },
  "response": {
    "facets": [
      ...
    ],
    "groups": [
      ...
    ],
    "sort_options": [
      ...
    ],
    "collection": {
      ...
    },
    "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",
            }
          }
        ]
      },
      "is_slotted": false,
      "matched_terms": [],
      "value": "Natural Balance Small Bites Potato & Duck Formula Dog Food"
      }
    ],
    "total_num_results": 1
  }
}

Data field

Structure in data is loosely defined, allowing additional fields for each items depending on your needs.

Groups info in results response

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

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

Facets info in results response

The Browse API will return information on the facet(s) this item possesses. Facets are usually displayed as key-value pairs. "Brand": "Natural Balance" for example, represents the facet of "Brand" type with "Natural Balance" as the key.

Collection in results response

The Browse API will return information on the collection only for browse collection requests browse/collection_id/<collection_id>, otherwise it will be not present in results response. Collection is an object containing display_name and data fields of browsed collection.

Variations info in results response

A list of variations for the parent product will be returned. Variations data can also be configured to fit your needs accordingly.

Other useful info in results response * id The customer_id of the product obtained from the product catalog. * image_url URL of the product image. * url URL pf the product page.

Miscellaneous fields

Browse: Groups structure

Groups Intro

Groups are typically used to indicate high-level categories for products. Each browse request will return all groups associated with items in the result set.

Flat group listings

{
  "request": {
    ...
  },
  "response": {
    "facets": [
      ...
    ],
    "groups": [
      {
        "children": [],
        "count": 33,
        "display_name": "Baby Care Products",
        "group_id": "baby_care_products",
        "parents": []
      },
      {
        "children": [],
        "count": 11,
        "display_name": "Beverages",
        "group_id": "beverages",
        "parents": []
      },
    ],
    "sort_options": [
      ...
    ],
    "results": [
      ...
    ],
    "total_num_results": 44
  }
}

If the index browsed just has a flat group hierarchy, a flat array of groups is returned, with empty arrays for children and parents fields.

Notice in this example that total_num_results is the sum of the count for each group. In this example, no products are a member of more than one group.

Groups fields

field_name Always present? Description
display_name Yes The name of the group as you'd present it to users.
group_id Yes The id of the group. Any ASCII characters can be used.
children Not when group is in parents array An array of groups that are 'children' of the group in question i.e. hierarchically below. Empty if no children.
count Not when group is in parents array The number of item results within the group that match the browse request.
parents Not when group is in children array The group_id of any parents. Empty for top-level categories.

Hierarchical group listings

{
  "request": {
    ...
  },
  "response": {
    "facets": [
      ...
    ],
    "groups": [
      {
        "children": [
          {
            "children": [],
            "count": 2,
            "display_name": "Baby Hair Brushes",
            "group_id": "baby_hair_brushes",
            "parents": []
          },
          {
            "children": [],
            "count": 3,
            "display_name": "Diapers",
            "group_id": "diapers",
            "parents": []
          }
        ],
        "count": 5,
        "display_name": "Baby Care Products",
        "group_id": "baby_care_products",
        "parents": []
      },
      {
        "children": [],
        "count": 5,
        "display_name": "Beverages",
        "group_id": "beverages",
        "parents": []
      },
    ],
    "sort_options": [
      ...
    ],
    "results": [
      ...
    ],
    "total_num_results": 10
  }
}

If an index has a hierarchy of groups, we return the full list of groups with results matching the browse request, with children groups returned within the children array of their parent group.

Notice in this example that the count for parent category Baby Care Products is the sum of its children, and total_num_results is the sum of the count for each top-level group. In this example, no products are a member of more than one group.

Browse: Facets structure

{
  "request": {
    ...
  },
  "response": {
    "facets": [
      {
        "name": "Brand",
        "display_name": "Brand",
        "type": "multiple",
        "data": {},
        "options": [
          {
            "value": "Natural Balance",
            "display_name": "Natural Balance",
            "data": {},
            "status": "",
            "count": 8
          },
          {
            "value": "WholeHearted",
            "display_name": "WholeHearted",
            "data": {
              "image_url": "https://www.example.com/image.png"
            },
            "status": "selected",
            "count": 10
          }
        ]
      },
      {
        "name": "rating",
        "display_name": "Rating",
        "type": "single",
        "data": {},
        "options": [
          {
            "value": "4-inf",
            "display_name": "4 and more",
            "data": {},
            "status": "",
            "count": 13,
          },
          {
            "value": "3-inf",
            "display_name": "3 and more",
            "status": "selected",
            "data": {},
            "count": 16,
          },
          {
            "value": "2-inf",
            "display_name": "2 and more",
            "status": "",
            "data": {},
            "count": 18,
          },
          {
            "value": "1-inf",
            "display_name": "1 and more",
            "data": {},
            "status": "",
            "count": 19,
          },
        ]
      },
      {
        "name": "price",
        "display_name": "Price",
        "type": "range",
        "data": {},
        "min": 0,
        "max": 265,
        "status": {
          "min": 100,
          "max": 200,
        }
      }
    ],
    "groups": [
      ...
    ],
    "sort_options": [
      ...
    ],
    "results": [
      ...
    ],
    "total_num_results": 10
  }
}

Facets fields

field_name Always present? Description
name Yes The name of the facet. This should be passed in the filters parameter when a facet of this type is selected. filters[name]=value
display_name Yes The display name of the facet. This can be used for displaying the facet name, but it's not necessarily the value that needs to be passed in filters.
type Yes Either "single", "multiple", or "range". If a facet is of type single, then only one of the options may be selected (e.g: display as radio button). If the type is multiple, then multiple options may be selected (e.g: display as checkboxes). If the type is range, then no options are provided. Instead a min and max value is provided to specify the range of values that can be sent in filters. To configure the types of your facets, please reach out to support@constructor.io.
status No Object containing min and max values. Only provided at the facet field level for facets of type range. Specifies the currently selected range. If no range is currently selected, status will be an empty object ({})
options No The list of possible facet values matching this browse request. Only provided if type is single or multiple. By default, facet options are sorted by relevance. To configure the sort order of your facet options, please reach out to support@constructor.io.
data Yes Object containing custom data associated with this facet. An empty object ({}) if no data is currently associated with this facet. If you need help associating custom data with your facets, please reach out to support@constructor.io.

Facet option fields

field_name Always present? Description
value Yes The value that should be passed in filters to select this option: filters[name]=value
display_name Yes Display name of the facet option. This can be used for displaying the facet option, but it's not necessarily the value that needs to be passed in filters
status Yes "selected" if this option is selected in the current browse request, empty string ("") otherwise.
data Yes Object containing custom data associated with this facet option. An empty object ({}) if no data is currently associated with this option. If you need help associating custom data with your facet options, please reach out to support@constructor.io.
count Yes Number of items in the current browse that match this option.

Browse: Collection structure

{
  "request": {
    ...
  },
  "response": {
    "collection": {
      "collection_id": "my_collection",
      "display_name": "Collection",
      "data": {"foo": "bar"}
    },
    "facets": [
      ...
    ],
    "groups": [
      ...
    ],
    "sort_options": [
      ...
    ],
    "results": [
      ...
    ],
    "total_num_results": 10
  }
}

Collection fields

field_name Always present? Description
id Yes Id of browsed collection.
display_name Yes Display name of the collection.
data Yes JSON object with custom metadata attached with the collection.

Browse: Features structure

{
  "request": {
    ...
  },
  "response": {
    "facets": [
      ...
    ],
    "features": [
      {
        "display_name": "Affinity Engine",
        "enabled": true,
        "feature_name": "auto_generated_refined_query_rules",
        "variant": null
      },
      {
        "display_name": "Searchandizing",
        "enabled": true,
        "feature_name": "manual_searchandizing",
        "variant": null
      },
      {
        "display_name": "Personalization",
        "enabled": true,
        "feature_name": "personalization",
        "variant": null
      },
      {
        "display_name": "Learn To Rank",
        "enabled": true,
        "feature_name": "query_items",
        "variant": null
      }
    ],
    "collection": {
      ...
    },
    "groups": [
      ...
    ],
    "sort_options": [
      ...
    ],
    "results": [
      ...
    ],
    "total_num_results": 454
  }
}

Features fields

field_name Always present? Description
enabled Yes Displays the enabled status of the feature.
feature_name Yes Name of the feature.
display_name Yes The user-friendly name of this feature that should be displayed to users.
variant Yes Displays the variant of this feature if there are any.

Browse: Sort options group

Sort options Intro

Sort options are different ways in which you can request the results to be sorted. By default results are sorted by relevance (i.e: most relevant items to the query in question come first), but you can choose to sort them by price or any other property. To set up custom sort options for your dataset, please reach out to support@constructor.io.

Sort options structure

{
  "request": {
    ...
  },
  "response": {
    "facets": [
      ...
    ],
    "groups": [
      ...
    ],
    "sort_options": [
      {
        "sort_by": "relevance",
        "sort_order": "descending",
        "display_name": "Most Relevant",
        "status": "selected"
      },
      {
        "sort_by": "price",
        "sort_order": "descending",
        "display_name": "Price, High to Low",
        "status": ""
      },
      {
        "sort_by": "price",
        "sort_order": "ascending",
        "display_name": "Price, Low to High",
        "status": ""
      },
      {
        "sort_by": "brand",
        "sort_order": "ascending",
        "display_name": "Brand name, A-Z",
        "status": ""
      },
      {
        "sort_by": "brand",
        "sort_order": "descending",
        "display_name": "Brand name, Z-A",
        "status": ""
      }
    ],
    "results": [
      ...
    ],
    "total_num_results": 454
  }
}

Sort options fields

field_name Always present? Description
sort_by Yes The name of the attribute results will be sorted by. The value of this field should be passed to the sort_by query string parameter in the browse request when this option is selected.
sort_order Yes Either "descending" or "ascending". The value of this attribute should be passed to the sort_order query string parameter in the browse request when this option is selected.
display_name Yes The user-friendly name of this sort option that should be displayed to users.
status Yes "selected" if this option is selected in the current browse request, empty string ("") otherwise.

Browse Items

The browse item endpoint accepts a list of items and returns a standard browse response structure. Additional filters may be passed in the request, but custom sort orders are not supported (items will always be returned in the order of ids that are specified in the request).

The browse items endpoint is designed for fast lookup of item data in production where performance and scalability are critical. It is used by customers in contexts such as: populating product detail pages with product information, retrieving data for products returned on a homepage with representative store pricing, or supplementing result pages with data for items that are placed from alternate systems, such as ad servers. Typically customers use this functionality where the responses from their eCommerce platform are not sufficiently performant, or don't support store or regional pricing. The browse items endpoint does not return results for items that have not yet been indexed.

In contrast, the items ingestion API retrieves any item that has been uploaded to a customer's index, even if it hasn't yet been indexed. It is intended only for integration and backend usage, requires authentication and has more aggressive rate limiting -- it is not designed for end-users. The endpoint also does not support filter logic.

The browse items endpoint is something of a special use case and is not leveraged by most customers (most customers will use their eCommerce platform for this case). Rather, most customers and browse contexts (browse a brand or category or collection) will utilize the standard browse endpoint.

# Request items with ids `item-1` and `item-2`
curl -X GET -H "Content-Type: application/json" \
"https://ac.cnstrc.com/browse/items?key=[your API key]&ids=item-1&ids=item-2"

# Request items with ids `item-1` and `item-2` and also apply filtering on color Black. Only items with provided ids, which have color Black will be returned.
curl -X GET -H "Content-Type: application/json" \
"https://ac.cnstrc.com/browse/items?key=[your API key]&ids=item-1&ids=item-2&filters[Color]=Black"

HTTP Request

GET https://ac.cnstrc.com/browse/items?key=[your API key]&ids=item-1&ids=item-2&ids=item-3&filters[Color]=Black&filters[Brand]=Nike&filters[Price]=100-200

URL Parameters

The URL parameters are the same as those in the Browse Queries section, with the additional requirement of the ids parameter:

Option Default Description
ids n/a List of item ids to request.

Browse Facets

The browse facets endpoint lists all the customer-defined facets present in the current index, while the facet options endpoint (shown below) indicates all the facet options (values) available for a given facet group (key), along with counts for the number of items available for each.

This can be useful to validate the integrity of a catalog by checking the number of products present for each brand, or within each group (category) as well as to power facet listings for web interfaces.

The browse facets endpoint can be used with production-level loads. Given customers may potentially define thousands of facets, the full list of facets is sorted ascending alphabetically, and paginated.

The browse facets endpoint does not return individual item results - for this purpose reference the standard browse endpoint.

# Request facets.
curl -X GET -H "Content-Type: application/json" \
"https://ac.cnstrc.com/browse/facets?key=[your API key]"

# Request facets, but also show hidden facets.
curl -X GET -H "Content-Type: application/json" \
"https://ac.cnstrc.com/browse/facets?key=[your API key]&fmt_options[show_hidden_facets]=true"

HTTP Request

GET https://ac.cnstrc.com/browse/facets?key=[your API key]&page=1&num_results_per_page=20&fmt_options[show_hidden_facets]=true&fmt_options[show_protected_facets]=true

URL Parameters

The URL parameters the endpoint accepts are shown below.

Option Required? Default Description
page No 1 The page number of the results
num_results_per_page No 20 The number of results per page to return
fmt_options[show_hidden_facets] No False Include facets configured as hidden
fmt_options[show_protected_facets] No False Include facets configured as protected

Response format overview

{
  "request": {
      ...
  },
  "response": {
    "facets": [
      {
        "data": {},
        "display_name": "Brand",
        "name": "brand",
        "type": "multiple"
      },
      {
        "data": {},
        "display_name": "Price",
        "name": "price",
        "type": "range"
      },
    ],
    "total_num_results": 2
  }
}

Browse Facet Options

The browse facet options endpoint lists all the customer-configured facet options (values) present in the latest index. The browse facet options endpoint does not return individual item results - for this purpose reference the standard browse endpoint.

# Request all options for a specific facet
curl -X GET -H "Content-Type: application/json" \
"https://ac.cnstrc.com/browse/facet_options?facet_name=[name of your facet]&key=[your API key]"

# Request all options for a specific _hidden_ facet
curl -X GET -H "Content-Type: application/json" \
"https://ac.cnstrc.com/browse/facet_options?facet_name=[name of your hidden facet]&key=[your API key]&fmt_options[show_hidden_facets]=true"

HTTP Request

GET https://ac.cnstrc.com/browse/facet_options?facet_name=[name of your facet]&key=[your API key]&fmt_options[show_hidden_facets]=true&fmt_options[show_protected_facets]=true

URL Parameters

The URL parameters the endpoint accepts are shown below.

Option Required? Default Description
facet_name Yes n/a Name of the facet whose options to return
fmt_options[show_hidden_facets] No False Requesting options of a hidden facet without setting this flag to True, will return 0 results
fmt_options[show_protected_facets] No False Requesting options of a protected facet without setting this flag to True, will return 0 results

Response Parameters

Parameter Configurable Description
data Yes Optional data communicated with facet such as image url or description. Can be set using facet configuration endpoint.
display_name Yes Name displayed for the facet to end-users. Can be set using facet configuration endpoint.
name No The key used to reference the facet in catalog or REST item data uploads.
value No The value used to reference the facet in catalog or REST item data uploads.
type Yes Configuration for how the facet should be treated. Can be set using facet configuration endpoint.
status No Refers to whether or not a given facet is selected. This parameter doesn't serve a purpose for the browse facets endpoint and is included for consistency with standard browse requests and browse items endpoints.

Response format overview

{
  "request": {
      ...
  },
  "response": {
    "facets": [
      {
        "data": {},
        "display_name": "Brand",
        "name": "brand",
        "options": [
          {
            "count": 1,
            "data": {},
            "display_name": "Nike",
            "status": "",
            "value": "nike"
          },
          {
            "count": 4,
            "data": {},
            "display_name": "Puma",
            "status": "",
            "value": "puma"
          }
        ],
        "type": "multiple"
      }
    ]
  }
}

Browse Groups

The browse groups endpoint lists all the customer-configured groups present in the latest index. The browse groups endpoint does not return individual item results - for this purpose reference the standard browse endpoint.

# Request all groups
curl -X GET -H "Content-Type: application/json" \
"https://ac.cnstrc.com/browse/groups?key=[your API key]"

# Request a single group
curl -X GET -H "Content-Type: application/json" \
"https://ac.cnstrc.com/browse/groups?filter[group_id]=[your group id]"

HTTP Request

GET https://ac.cnstrc.com/browse/groups?filter[group_id]=[your group id]&key=[your API key]&fmt_options[groups_max_depth]=5

URL Parameters

The URL parameters the endpoint accepts are shown below.

Option Required? Default Description
filter[group_id] No n/a The id of the specific group that should be included in the response
fmt_options[groups_max_depth] No 1 In case of hierarchical groups, maximum depth of the hierarchy that should be included in the response

Response format overview

{
  "request": {
      ...
  },
  "response": {
    "groups": [
      {
        "children": [
          {
            "children": [],
            "count": 1,
            "data": null,
            "display_name": "Dog food",
            "group_id": "dog-food",
            "parents": [
              {
                "display_name": "Pet food",
                "group_id": "pet-food"
              }
            ]
          }
        ],
        "count": 2,
        "data": null,
        "display_name": "Pet food",
        "group_id": "pet-food",
        "parents": []
      },
      {
        "children": [],
        "count": 2,
        "data": null,
        "display_name": "Pet toys",
        "group_id": "pet-toys",
        "parents": []
      }
    ]
  }
}

Blacklist Terms

Online marketplaces may sell products of an adult nature that they don't want to display as autocomplete suggestions. Constructor.io's Blacklist API allows such marketplaces to exclude items matching objectionable terms from the autosuggest, but continue to include these products in search and/or product detail pages.

Blacklist Types

Single-term Blacklist

You may blacklist suggestions that match a single term.

Example: Blacklisting the term cat would prevent display of the cat in the hat.

Multi-term Blacklist

You may blacklist suggestions that match all of a set of terms (a multi-term blacklist rule).

Example: Blacklisting the set of terms cats, bite and scratch, would prevent display of cats that bite and scratch, but not cats that bite.

Multi-term blacklist rules blacklist suggestions where all the terms appear in any order.

Example: Blacklisting the set of terms cats, bite and scratch, would prevent display of cats that scratch and bite (scratch comes before bite).

Blacklist Matching Logic

Example: Blacklisting cats would prevent display of cats as well as Cats, CATS or any other variation.

Example: cats would not prevent display of wildcats.

Example: cats would prevent display of wild-cats.

Example: cat would not prevent display of cats.

Add Blacklist Terms

# Add terms to the blacklist
curl -X POST -H "Content-Type: application/json" \
  -d '{"blacklist_terms": ["cats","snakes","bees"]}' \
  -u"[your token]:" "https://ac.cnstrc.com/v1/blacklist_autosuggest_terms?key=[your API key]"

# Add sets of terms (multi-term rules) to the blacklist
curl -X POST -H "Content-Type: application/json" \
  -d '{"blacklist_terms": [["cats","bite","scratch"],["bees","sting"]]}' \
  -u"[your token]:" "https://ac.cnstrc.com/v1/blacklist_autosuggest_terms?key=[your API key]"
// This method is not currently supported in our javascript client.
# This method is not currently supported in our ruby client.
# This method is not currently supported in our python client.
// This method is not currently supported in our php client.
# This method is not currently supported in our perl client.
// This method is not currently supported in our java client.
// This method is not currently supported in our csharp client.

The above command returns a 204 Success response on success. For simplicity sake, a 204 Success response will be returned even if some or all items already exist.

HTTP Request

POST https://ac.cnstrc.com/v1/blacklist_autosuggest_terms?key=[your API key]

JSON Parameters

Parameter Required? Description
blacklist_terms Yes The term(s) or set(s) of terms to add to the blacklist.

Remove Blacklist Terms

Example: If a user previously added a multi-term blacklist rule ["cats", "bite", "scratch"], removing the multi-term rule ["cats", "bite"] and ["cats", "bite", "scratch", "hiss"] would not remove the ["cats", "bite", "scratch"] rule from the blacklist.

Example: If a user previously added a multi-term blacklist rule ["cats", "bite", "scratch"], you could remove this rule by deleting ["bite", "scratch", "cats"]

# Remove terms from the blacklist
curl -X DELETE -H "Content-Type: application/json" \
  -d '{"blacklist_terms": ["cats","snakes","bees"]}' \
  -u"[your token]:" "https://ac.cnstrc.com/v1/blacklist_autosuggest_terms?key=[your API key]"

# Remove sets of terms (multi-term rules) from blacklist
curl -X DELETE -H "Content-Type: application/json" \
  -d '{"blacklist_terms": [["cats","bite","scratch"],["bees","sting"]]}' \
  -u"[your token]:" "https://ac.cnstrc.com/v1/blacklist_autosuggest_terms?key=[your API key]"
// This method is not currently supported in our javascript client.
# This method is not currently supported in our ruby client.
# This method is not currently supported in our python client.
// This method is not currently supported in our php client.
# This method is not currently supported in our perl client.
// This method is not currently supported in our java client.
// This method is not currently supported in our csharp client.

The above command returns a 204 Success response on success. For simplicity sake, a 204 Success response will be returned even if some or all items don't exist.

HTTP Request

DELETE https://ac.cnstrc.com/v1/blacklist_autosuggest_terms?key=[your API key]

JSON Parameters

Parameter Required? Description
blacklist_terms Yes The term(s) or set(s) of terms to remove from the blacklist.

Delete Entire Blacklist

curl -X DELETE -H "Content-Type: application/json" \
  -u"[your token]:" "https://ac.cnstrc.com/v1/delete_all_blacklist?key=[your API key]"
// This method is not currently supported in our javascript client.
# This method is not currently supported in our ruby client.
# This method is not currently supported in our python client.
// This method is not currently supported in our php client.
# This method is not currently supported in our perl client.
// This method is not currently supported in our java client.
// This method is not currently supported in our csharp client.

The above command returns a 200 Success response for all valid requests, but the delete occurs asynchronously.

HTTP Request

POST https://ac.cnstrc.com/v1/delete_all_blacklist?key=[your API key]

Redirect Rules

Redirect rules allow customers to alter the destination of users' queries. Imagine a user searches for shopping cart: redirects allow a customer to send this user to the shopping cart URL rather than a search result page for shopping cart products.

The redirect rule endpoint allows customers to define a set of patterns that are checked against search queries; if there is a match, the search endpoint returns a redirect response to the client pointing to the desired target URL (or alternative content identifier in mobile contexts).

Rules are matched in order of specificity, from most specific to least. This allows customers to set one redirect for a broad term, but override this with more specific keywords or phrases.

Redirect objects

In this section the json objects that are sent to/returned by the API are described.

Redirect rule object

The redirect rule object describes a complete redirect rule and may have multiple, separate match conditions (matches). For example, dog mattresses and dog beds could be defined to target the same URL.

Attribute Type Required? Description
url string Yes Target URL returned when a match happens
matches List[RedirectRuleMatch] Yes List of match definitions
start_time string No Time at which rule begins to apply (ISO8601 format preferred)
end_time string No Time at which rule stops to apply (ISO8601 format preferred)
user_segments List[str] No List of user segments
metadata Object No Object with arbitrary metadata

Redirect rule match object

The redirect rule match object is the definition of a match in a redirect rule.

Attribute Type Required? Description
match_type string Yes Match type (any of "EXACT", "UNORDERED" or "PHRASE")
pattern string Yes Pattern that needs to be matched against the search query

where:

Create redirect rule

To create a redirect rule, the POST method needs to be used.

Create redirect rule

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"url": "<url>", "matches": [{"pattern": "<pattern>", "match_type": "EXACT"}]}'
  -u "[your token]:"
  "https://ac.cnstrc.com/v1/redirect_rules?key=[your API key]"

Response

{
  "id": 1,
  "start_time": null,
  "end_time": null,
  "user_segments": null,
  "metadata": null,
  "url": "<url>",
  "matches": [
    {
      "id": 1,
      "match_type": "EXACT",
      "pattern": "<pattern>"
    }
  ]
}

HTTP request

POST https://ac.cnstrc.com/v1/redirect_rules?key=[your API key]

JSON body

The JSON body for the POST request needs to be a redirect rule object as defined in the redirect objects section.

Read all redirect rules

To get all redirect rules, the GET method needs to be used.

Read all redirect rules

curl -X GET \
  -H "Content-Type: application/json" \
  -u "[your token]:"
  "https://ac.cnstrc.com/v1/redirect_rules?key=[your API key]"

Response

{
  "redirect_rules": [
    {
      "id": 1,
      "start_time": null,
      "end_time": null,
      "user_segments": null,
      "metadata": null,
      "url": "<url>",
      "matches": [
        {
          "id": 1,
          "match_type": "EXACT",
          "pattern": "<pattern>"
        }
      ]
    }
  ]
}

HTTP request

GET https://ac.cnstrc.com/v1/redirect_rules?key=[your API key]

URL Parameters

Parameter Required Description
key Yes The index you'd like to to retrieve redirect rules from.
num_results_per_page No The number of rules to return. Defaults to 20.
page No The page of redirect rules to return. Defaults to 1.
query No Return redirect rules whose url or match pattern match the provided query.
status No One of "current" (return redirect rules that are currently active), "pending" (return redirect rules that will become active in the future), and "expired" (return redirect rules that are not active anymore).

Read redirect rule

To get all redirect rules, the GET method needs to be used together with a redirect rule ID passed as part of the URL.

Read redirect rule

curl -X GET \
  -H "Content-Type: application/json" \
  -u "[your token]:"
  "https://ac.cnstrc.com/v1/redirect_rules/<redirect_rule_id>?key=[your API key]"

Response

{
  "id": 1,
  "start_time": null,
  "end_time": null,
  "user_segments": null,
  "metadata": null,
  "url": "<url>",
  "matches": [
    {
      "id": 1,
      "match_type": "EXACT",
      "pattern": "<pattern>"
    }
  ]
}

HTTP request

GET https://ac.cnstrc.com/v1/redirect_rules/<redirect_rule_id>?key=[your API key]

Update redirect rule (completely)

To update a redirect rule completely, use a PUT method and pass the redirect rule ID as part of the URL.

Update redirect rule (completely)

curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{"url": "<new_url>", "matches": [{"pattern": "<new_pattern>", "match_type": "EXACT"}]}'
  -u "[your token]:"
  "https://ac.cnstrc.com/v1/redirect_rules/<redirect_rule_id>?key=[your API key]"

Response

{
  "id": 1,
  "start_time": null,
  "end_time": null,
  "user_segments": null,
  "metadata": null,
  "url": "<new_url>",
  "matches": [
    {
      "id": 2,
      "match_type": "EXACT",
      "pattern": "<new_pattern>"
    }
  ]
}

HTTP request

PUT https://ac.cnstrc.com/v1/redirect_rules/<redirect_rule_id>?key=[your API key]

JSON body

The JSON body for the PUT request needs to be a redirect rule object as defined in the redirect objects section.

Update redirect rule (partially)

To update part of a redirect rule, such as by changing just the target URL but not the match criteria, the PATCH method should be used together with a redirect rule ID passed as part of the URL.

Update redirect rule (partially)

curl -X PATCH \
  -H "Content-Type: application/json" \
  -d '{"url": "<new_url>"}'
  -u "[your token]:"
  "https://ac.cnstrc.com/v1/redirect_rules/<redirect_rule_id>?key=[your API key]"

Response

{
  "id": 1,
  "start_time": null,
  "end_time": null,
  "user_segments": null,
  "metadata": null,
  "url": "<new_url>",
  "matches": [
    {
      "id": 1,
      "match_type": "EXACT",
      "pattern": "<pattern>"
    }
  ]
}

HTTP request

PATCH https://ac.cnstrc.com/v1/redirect_rules/<redirect_rule_id>?key=[your API key]

JSON body

The JSON body for the PATCH request needs to be a subset of the redirect rule object as defined in the redirect objects section.

Delete redirect rule

To delete a redirect rule, the DELETE method needs to be used together with a redirect rule ID passed as part of the URL.

Delete redirect rule

curl -X DELETE \
  -H "Content-Type: application/json" \
  -d '{"url": "<new_url>"}'
  -u "[your token]:"
  "https://ac.cnstrc.com/v1/redirect_rules/<redirect_rule_id>?key=[your API key]"

Response

{
  "id": 1,
  "start_time": null,
  "end_time": null,
  "user_segments": null,
  "metadata": null,
  "url": "<new_url>",
  "matches": [
    {
      "id": 1,
      "match_type": "EXACT",
      "pattern": "<pattern>"
    }
  ]
}

HTTP request

DELETE https://ac.cnstrc.com/v1/redirect_rules/<redirect_rule_id>?key=[your API key]

Searchandizing

Intro

Constructor.io's searchandizing capability allows merchants to create rich sets or rules to promote, demote or feature items and brands.

By leveraging the APIs underlying these capabilities, customer data science teams can incorporate their own expertise and understanding of user behavior to optimize results, much like Constructor.io does with its automatic rule-setting for boost and bury.

Taxonomy Rules leverage your existing product taxonomy, so any facet or category (group_id) in your index can be used to create a rule.

Scope Currently rules can be set for individual search term or browse pages (which may be based on a facet or category/group_id page). That said, global rule APIs are in limited release for early access customers.

Types Boost (and bury) Boost (or bury) the score (and in turn, ranking) of items with one or more attributes, where attributes could be a particular size, price range, or brand.

Blacklist Remove items from recall that share particular attributes.

Whitelist Return only items that share particular particular attributes.

Slotting Add an item to recall at a particular position.

Add Rule


curl -X PUT -H "Content-Type: application/json" \
  -d '{"allow_fuzzy_matching": false}' \
  -u"[your token]:" "https://ac.cnstrc.com/v1/searchandized_queries/dog%20leash/position/1/item/adorable_dog_leash_id?key=[your API key]&section=Products"
// This method is not currently supported in our javascript client.
# This method is not currently supported in our ruby client.
# This method is not currently supported in our python client.
// This method is not currently supported in our php client.
# This method is not currently supported in our perl client.
// This method is not currently supported in our java client.
// This method is not currently supported in our csharp client.

The above command returns a 204 Success response on success. For simplicity sake, a 204 Success response will be returned even if the item already exists.

HTTP Request

PUT https://ac.cnstrc.com/v1/searchandized_queries/[query]/position/[int:position]/item/[id]?key=[your API key]&section=[section]

URL Parameters

Parameter Description
query The query you'd like to add a searchandizing rule to.
position The position you'd like to add a searchandized product at. (use 0 to blacklist the item)
id The id for the item you'd like added to the position and query in question.

JSON Parameters

Parameter Required? Description
section Yes Your suggestions can have multiple sections like “Products” and “Search Suggestions”. This indicates which section this searchandizing rule is for. See your dashboard for the section names to use.
allow_fuzzy_matching No Defaults to TRUE. Allows you to permit fuzzy matching.

Batch Add Rules

curl -X PUT -H "Content-Type: application/json" \
  -d '{
        "section": "Products",
        "rules": [
            {
                "query": "dog leash",
                "position": 2,
                "id": "very_cool_dog_leash_id",
                "allow_fuzzy_matching": true
            },
            {   "query": "dog leash",
                "position": 3,
                "id": "almost_as_cool_dog_leash_id",
                "allow_fuzzy_matching": true
            },
            {   "query": "cat leash",
                "position": 1,
                "id": "adorable_cat_leash_id",
                "allow_fuzzy_matching": true
            }
        ]
    }' \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/searchandized_queries/leashes?key=[your API key]"
// This method is not currently supported in our javascript client.
# This method is not currently supported in our ruby client.
# This method is not currently supported in our python client.
// This method is not currently supported in our php client.
# This method is not currently supported in our perl client.
// This method is not currently supported in our java client.
// This method is not currently supported in our csharp client.

The above command returns a 204 Success response on success. For simplicity sake, a 204 Success response will be returned even if some or all items already exist.

HTTP Request

PUT https://ac.cnstrc.com/v1/searchandized_queries/[query]?key=[your API key]

JSON Parameters

Parameter Required? Description
section Yes The section the searchandizing rules will be applied within (typically Products).
rules Yes A list of searchandizing rules with the following attributes:
query Yes The query to which a product is being searchandized.
position Yes The position a product should be added at. (use 0 to blacklist the item)
id Yes The id for the product being searchandized.
allow_fuzzy_matching No Defaults to true. Disable or enable fuzzy matching.

Retrieve Rules

curl -X GET -H "Content-Type: application/json" \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/searchandized_queries?key=[your API key]&section=[section]"

curl -X GET -H "Content-Type: application/json" \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/searchandized_queries/leashes?key=[your API key]&section=Products"
// This method is not currently supported in our javascript client.
# This method is not currently supported in our ruby client.
# This method is not currently supported in our python client.
// This method is not currently supported in our php client.
# This method is not currently supported in our perl client.
// This method is not currently supported in our java client.
// This method is not currently supported in our csharp client.

HTTP Requests

GET https://ac.cnstrc.com/v1/searchandized_queries?key=[your API key]&section=[section]

GET https://ac.cnstrc.com/v1/searchandized_queries/[query]?key=[your API key]&section=[section]

Response format

Response format documentation is in progress.

URL Parameters

Parameter Description
query The query you'd like to retrieve rules for.

Query Parameters

Parameter Required? Description
key Yes The index you'd like to to retrieve results from.
section Yes The index section you'd like to retrieve results from.
num_results_per_page No The number of rules to return. Defaults to 100.
page No The page of results to return. Defaults to 1.

Remove Rules

curl -X DELETE -H "Content-Type: application/json" \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/searchandized_queries/leashes?key=[your API key]&section=Products"

curl -X DELETE -H "Content-Type: application/json" \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/searchandized_queries/leashes/position/1?key=[your API key]&section=Products"

curl -X DELETE -H "Content-Type: application/json" \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/searchandized_queries/leashes/item/not_the_coolest_dog_leash_id?key=[your API key]&section=Products"
// This method is not currently supported in our javascript client.
# This method is not currently supported in our ruby client.
# This method is not currently supported in our python client.
// This method is not currently supported in our php client.
# This method is not currently supported in our perl client.
// This method is not currently supported in our java client.
// This method is not currently supported in our csharp client.

The above command returns a 204 Success response on success.

HTTP Requests

DELETE https://ac.cnstrc.com/v1/searchandized_queries/[query]?key=[your API key]&section=[section]

DELETE https://ac.cnstrc.com/v1/searchandized_queries/[query]/position/[int:position]?key=[your API key]&section=[section]

DELETE https://ac.cnstrc.com/v1/searchandized_queries/[query]/item/[id]?key=[your API key]&section=[section]

URL Parameters

Parameter Description
query The query you'd like to delete searchandizing rules from.
position The searchandized result you'd like removed from the query in question.
id The id for the item you'd like removed from the query in question.

Query Parameters

Parameter Required? Description
key Yes The index you'd like to remove searchandizing rules from.
section Yes The index section you'd like to remove searchandizing rules from.

Browse Searchandizing

Constructor.io's browse searchandizing allows one to modify ranking of results to browse requests.

Browse requests are typically used to power category pages, as well as pages dedicated to a particular brand. Browse searchandizing allows customers to influence rankings for these pages.

Searchandizing is accomplished by referencing the key and value of the particular browse entity you want to searchandize.

For instance, the Fiddo's Food brand listing would mean referencing the brand key and the Fiddo's Food value, while searchandizing the Dog Food category would require referencing the group_id corresponding to the Dog Food category.

Add Rules

Putting new rules will replace all existing rules associated with the specified filter_name and filter_value if there are any.


curl -X PUT -H "Content-Type: application/json" \
  -d '{
        "slot_rules": [
            {
                "rule": {
                    "item_id": "fiddos_food_item",
                    "position": 1
                },
                "active": true,
                "start_time": "2018-06-28 01:34:08",
                "end_time": "2018-06-30 01:34:08"
            }
        ]
    }' \
  -u"[your token]:" "https://ac.cnstrc.com/refined_filters/group_id/dog%20food?key=[your index key]&section=Products"
// This method is not currently supported in our javascript client.
# This method is not currently supported in our ruby client.
# This method is not currently supported in our python client.
// This method is not currently supported in our php client.
# This method is not currently supported in our perl client.
// This method is not currently supported in our java client.
// This method is not currently supported in our csharp client.

The above command returns a 204 Success response on success. For simplicity sake, a 204 Success response will be returned even if the item already exists.

HTTP Request

PUT https://ac.cnstrc.com/refined_filters/[filter_name]/[filter_value]?key=[your index key]&section=[section]

URL Parameters

Parameter Description
filter_name The name of facet you'd like to add searchandizing rules for.
filter_value The value of that facet you'd like to add searchandizing rules for.
section Yes

JSON Specifications

Example JSON: json { "slot_rules": [ { "rule": { "item_id": "fiddos_food_item", "position": 1 }, "active": true, "start_time": "2018-06-28 01:34:08", "end_time": "2018-06-30 01:34:08" } ], "whitelist_rule": { "rule": { "filters": {"brand": ["fiddos food"]}, }, "end_time": "2018-06-28 01:34:08", }, "blacklist_rules": [ { "rule": { "filters": {"type": ["toys"]}, }, "start_time": "2018-06-28 01:34:08", "end_time": "2018-06-30 01:34:08" } ], "boost_rules": [ { "rule": { "filters": {"color": ["red"]}, "boost": 0.5, } } ] }

Types of rules

id Description
slot_rules With slot rules, you can add an item to recall and pin it to a particular position. Provide item_id and a particular position for the item(s).
boost_rules Boost or bury the score (and in turn, ranking) of matching items.
whitelist_rule Restrict recall to only the matching items.
blacklist_rules Remove matching items from recall.

Parameters

Parameter Required? Description
rule Yes Rules can accept a dictionary of the various rule specs as show in the above JSON example.
active No Your slot rule can be defined but set to inactive if you wish by setting the active field to false.
start_time No Start time when the searchandizing rule should be enabled.
end_time No End time when the searchandizing rule should be disabled.

Patch Existing Rules

Patching rules will only change the rules that are specified in the request.


curl -X PUT -H "Content-Type: application/json" \
  -d '{
        "slot_rules": [
            {
                "rule": {
                    "item_id": "fiddos_food_item",
                    "position": 2
                },
                "active": true,
                "start_time": "2018-06-28 01:34:08",
                "end_time": "2018-06-30 01:34:08"
            }
        ]
    }' \
  -u"[your token]:" "https://ac.cnstrc.com/refined_filters/group_id/dog%20food?key=[your index key]&section=Products"
// This method is not currently supported in our javascript client.
# This method is not currently supported in our ruby client.
# This method is not currently supported in our python client.
// This method is not currently supported in our php client.
# This method is not currently supported in our perl client.
// This method is not currently supported in our java client.
// This method is not currently supported in our csharp client.

The above command returns a 204 Success response on success. For simplicity sake, a 204 Success response will be returned even if the item already exists.

HTTP Request

PATCH https://ac.cnstrc.com/refined_filters/[filter_name]/[filter_value]?key=[your index key]&section=[section]

URL Parameters

Parameter Description
filter_name The name of the facet you'd like to patch searchandizing rules for.
filter_value The value of the facet you'd like to patch searchandizing rules for.
section Yes

JSON Specifications

Example JSON: json { "slot_rules": [ { "rule": { "item_id": "fiddos_food_item", "position": 1 }, "active": true, "start_time": "2018-06-28 01:34:08", "end_time": "2018-06-30 01:34:08" } ], "whitelist_rule": { "rule": { "filters": {"brand": ["fiddos food"]}, }, "end_time": "2018-06-28 01:34:08", }, "blacklist_rules": [ { "rule": { "filters": {"type": ["toys"]}, }, "start_time": "2018-06-28 01:34:08", "end_time": "2018-06-30 01:34:08" } ], "boost_rules": [ { "rule": { "filters": {"color": ["red"]}, "boost": 0.5, } } ] }

Types of rules

id Description
slot_rules With slot rules, you can add an item to recall and pin it to a particular position. Provide item_id and a particular position for the item(s).
boost_rules Boost or bury the score (and in turn, ranking) of matching items.
whitelist_rule Restrict recall to only the matching items.
blacklist_rules Remove matching items from recall.

Parameters

Parameter Required? Description
rule Yes Rules can accept a dictionary of the various rule specs as show in the above JSON example.
active No Your slot rule can be defined but set to inactive if you wish by setting active field to false.
start_time No Start time of when the searchandizing rule should be enabled.
end_time No End time of when the searchandizing rule should be disabled.

Remove a rule


curl -X DELETE -H "Content-Type: application/json" \
  -u"[your token]:" \
  "https://ac.cnstrc.com/refined_filters/group_id/dog%20food?key=[your index key]&section=Products"
// This method is not currently supported in our javascript client.
# This method is not currently supported in our ruby client.
# This method is not currently supported in our python client.
// This method is not currently supported in our php client.
# This method is not currently supported in our perl client.
// This method is not currently supported in our java client.
// This method is not currently supported in our csharp client.

The above command returns a 204 Success response on success.

HTTP Requests

DELETE https://ac.cnstrc.com/refined_filters/[filter_name]/[filter_value]?key=[your index key]&section=[section]

URL Parameters

Parameter Description
filter_name The name of the facet you'd like to remove searchandizing rules from.
filter_value The value of the facet you'd like to remove searchandizing rules from.
section Yes

Retrieve Browse Rules

curl -X GET -H "Content-Type: application/json" \
  -u"[your token]:" \
  "https://ac.cnstrc.com/refined_filters/group_id/dog%20food?key=[your index key]&section=[section]"

curl -X GET -H "Content-Type: application/json" \
  -u"[your token]:" \
  "https://ac.cnstrc.com/refined_filters/group_id?key=[your index key]&section=Products"
// This method is not currently supported in our javascript client.
# This method is not currently supported in our ruby client.
# This method is not currently supported in our python client.
// This method is not currently supported in our php client.
# This method is not currently supported in our perl client.
// This method is not currently supported in our java client.
// This method is not currently supported in our csharp client.

HTTP Requests

GET https://ac.cnstrc.com/refined_filters/[filter_name]/[filter_value]?key=[your index key]&section=[section]

GET https://ac.cnstrc.com/refined_filters/[filter_name]?key=[your index key]&section=[section]

Response format

{
    "refined_filters": [
        {
            "allow_automatic_rules": false,
            "blacklist_rules": [
                {
                    "active": true,
                    "automatically_generated": false,
                    "created_at": "2020-04-07T13:45:42",
                    "end_time": null,
                    "rule": {"filters": {"type": ["toys"]}},
                    "rule_type": "BLACKLIST",
                    "start_time": null,
                    "updated_at": null
                }
            ],
            "boost_rules": [
                {
                    "active": true,
                    "automatically_generated": false,
                    "created_at": "2020-04-07T13:45:42",
                    "end_time": null,
                    "rule": {"filters": {"boost": 1.0, "color": ["red"]}},
                    "rule_type": "BOOST",
                    "start_time": null,
                    "updated_at": null
                }
            ],
            "filter_name": "group_id",
            "filter_value": "dog food",
            "slot_rules": [
                {
                    "active": true,
                    "automatically_generated": false,
                    "created_at": "2020-04-07T13:45:42",
                    "end_time": "2020-04-17T13:45:42",
                    "rule": {"item_id": "fiddos_food_item", "position": 1},
                    "rule_type": "SLOT",
                    "start_time": "2020-04-07T13:45:42",
                    "updated_at": null
                }
            ],
            "whitelist_rule": {
                "active": true,
                "automatically_generated": false,
                "created_at": "2020-04-07T13:45:42",
                "end_time": null,
                "rule": {"filters": {"brand": ["fiddos food"]}},
                "rule_type": "WHITELIST",
                "start_time": null,
                "updated_at": null
            }
        }
    ],
    "total_count": 1
}

URL Parameters

Parameter Description
filter_name The name of the facet you'd like to retrieve searchandizing rules for.
filter_value The value of the facet you'd like to retrieve searchandizing rules for.

Query Parameters

Parameter Required? Description
key Yes The index you'd like to to retrieve results from.
section Yes The index section you'd like to retrieve results from (typically Products).
num_results_per_page No The number of rules to return. Defaults to 100.
page No The page of results to return. Defaults to 1.

One way synonyms

Constructor's One Way Synonym API allows a user to define a word or words (parent phrase) which will be treated as synonymous to several other word or words (child phrases) by Constructor.io's search algorithms in only one direction.

In other words, search results for the parent phrase will be enriched with all results matching any of the child phrase(s) associated with that parent phrase, but results for the child phrase(s) will be unchanged. Linguistics typically refers to these as hyperonyms and hyponyms.

As an example, a customer of a grocery store may search for fruit (parent phrase) and expect to see all items that match blueberries, strawberries, bananas, oranges, apples, etc (child phrases) along with items matching just fruit.

Dashboard

The following documentation covers adding one-way synonyms manually via the API, but these can also be added in the dashboard.

Platform synonyms

Constructor.io algorithms can identify many synonyms using data science for specific eCommerce verticals such as fashion, grocery and others. Reach out to Constructor.io support to learn more and to enable this feature.

Index-by-index

One way synonyms are set on each index key separately, so a customer can have separate synonym rules for two independent properties, such as their Dutch and French grocery stores.

Case Insensitive

Synonyms ignore case, so a synonym rule for milk chocolate would apply to delicious milk chocolate as well as DELICIOUS MILK CHOCOLATE .

Exact Phrase Match

Synonyms match an exact phrase, so a child phrase for chocolate milk would match products like McCormick's 2% Chocolate Milk, but would not apply to milk chocolate or chocolate-flavored reduced-fat milk. To match these products, you'd need to include child phrases rules for milk chocolate and chocolate-flavored reduced-fat milk.

This approach is taken because intervening words and term order can influence meaning: as one example, a shirt dress is not equivalent to a dress shirt. Another case (mentioned in the example above) is that milk chocolate is not equivalent to chocolate milk.

Version

The one way synonyms API is available at http://ac.cnstrc.com/v2/one_way_synonyms (note v2).

Add One Way Synonyms

This method creates new one way synonyms for a parent phrase. Any synonyms provided in the JSON structure are added to the parent phrase.

curl -X POST -H 'Content-Type: application/json' \
  -u '[your token]:' \
  "http://ac.cnstrc.com/v2/one_way_synonyms/spices?key=[your API key]"
  -d '{
    "child_phrases": [
      { "phrase": "pepper" },
      { "phrase": "cinnamon" }
    ]
  }'
// This method is not currently supported in our javascript client.
# This method is not currently supported in our ruby client.
# This method is not currently supported in our python client.
// This method is not currently supported in our php client.
# This method is not currently supported in our perl client.
// This method is not currently supported in our java client.
// This method is not currently supported in our csharp client.

The above command returns a 204 No Content response on success.

HTTP Request

POST http://ac.cnstrc.com/v2/one_way_synonyms/[phrase]?key=[your API key]

Response Example

HTTP 204 OK (No Content)

JSON Parameters

Parameter Required? Description
child_phrases Yes Array of synonyms

Modify One Way Synonyms

This method modifies one-way synonyms (child phrases) for a parent phrase. All existing child phrases are replaced with those provided in the child_phrases array.

curl -X PUT -H 'Content-Type: application/json' \
  -u '[your token]:' \
  "http://ac.cnstrc.com/v2/one_way_synonyms/spices?key=[your API key]"
  -d '{
    "child_phrases": [
      { "phrase": "pepper" },
      { "phrase": "cinnamon" }
    ]
  }'
// This method is not currently supported in our javascript client.
# This method is not currently supported in our ruby client.
# This method is not currently supported in our python client.
// This method is not currently supported in our php client.
# This method is not currently supported in our perl client.
// This method is not currently supported in our java client.
// This method is not currently supported in our csharp client.

The above command returns a 204 No Content response on success.

HTTP Request

PUT http://ac.cnstrc.com/v2/one_way_synonyms/[phrase]?key=[your API key]

Response Example

HTTP 204 OK (No Content)

JSON Parameters

Parameter Required? Description
child_phrases Yes Array of synonyms

Retrieve One Way Synonyms

This endpoint is used to retrieve synonyms associated with the given key.

If a parent phrase is provided, only the one-way synonyms associated with the parent phrase for the given key will be returned. If no parent phrase is provided, all parent phrases for the given key will be returned.

The child phrase may contain the "automatically_generated" flag which indicates whether the phrase was created by the customer or by the Constructor.io platform.


curl -X GET -H "Content-Type: application/json" \
  -u"[your token]:" "https://ac.cnstrc.com/v2/one_way_synonyms?key=[your API key]"

curl -X GET -H "Content-Type: application/json" \
  -u"[your token]:" "https://ac.cnstrc.com/v2/one_way_synonyms/spices?key=[your API key]"
// This method is not currently supported in our javascript client.
# This method is not currently supported in our ruby client.
# This method is not currently supported in our python client.
// This method is not currently supported in our php client.
# This method is not currently supported in our perl client.
// This method is not currently supported in our java client.
// This method is not currently supported in our csharp client.

The above command returns a 204 No Content response on success.

HTTP Request

GET https://ac.cnstrc.com/v2/one_way_synonyms?key=[your API key]

GET https://ac.cnstrc.com/v2/one_way_synonyms/[parent phrase]?key=[your API key]

Response format

Response Format

{
  "one_way_synonym_relations":
  [
    {
      "parent_phrase": "spices",
      "child_phrases": [
        { "phrase": "pepper", "automatically_generated": false },
        { "phrase": "cinnamon", "automatically_generated": false }
      ]
    }
  ],
  "total_count": 1
}

Query Parameters

Parameter Required? Description
parent phrase No The phrase for which all synonym groups containing it will be returned.
num_results_per_page No The number of synonym groups to return. Defaults to 100.
page No The page of results to return. Defaults to 1.

Remove One Way Synonyms

This method deletes a parent phrase and its associated one-way synonyms (child phrases).

Note: If not given a parent phrase, all synonyms belonging to the given key will be deleted.


curl -X DELETE -H "Content-Type: application/json" \
  -u"[your token]:" "https://ac.cnstrc.com/v2/one_way_synonyms?key=[your API key]"

curl -X DELETE -H "Content-Type: application/json" \
  -u"[your token]:" "https://ac.cnstrc.com/v2/one_way_synonyms/spices?key=[your API key]"
// This method is not currently supported in our javascript client.
# This method is not currently supported in our ruby client.
# This method is not currently supported in our python client.
// This method is not currently supported in our php client.
# This method is not currently supported in our perl client.
// This method is not currently supported in our java client.
// This method is not currently supported in our csharp client.

The above command returns a 204 Success response on success.

HTTP Request

DELETE https://ac.cnstrc.com/v2/one_way_synonyms?key=[your API key]

DELETE https://ac.cnstrc.com/v2/one_way_synonyms/[parent phrase]?key=[your API key]

Query Parameters

Parameter Required? Description
parent phrase No The parent phrase you would like to delete.

Recommendations

Constructor.io recommendations bring the same personalization graphs, conversion optimization and product data used to power browse and search to product recommendations.

Rather than offer fixed endpoints such as "Recently-viewed items" or "Complementary Items", Constructor.io implements recommendations using two related concepts: pods and strategies.

Pods represent a specific location on a page or set of pages (template) where recommendations may be rendered. A page may have one or more pods. You may have several pods on the homepage, a pod on the product detail page or in an email campaign.

Strategies represent a particular algorithm used to generate recommendations. Currently, a pod can be assigned a (single) strategy, but the capability is possible in the future to support multiple strategies in a single pod. Example strategies might be "Recently viewed," "Alternative items," etc.

Available strategies

Constructor.io provides several strategies that can be associated with a given pod. Currently the association is configured @ onboarding and upon request thereafter.

Recently Viewed Items

The simplest but often most-interacted-with strategy: Show a user’s most recently viewed items.

Provide personalized recommendations to a user based on their entire search, view, click, add to cart and purchase history. This algorithm is particularly valuable on homepages and zero result pages -- anywhere outside the context of a particular product page.

Alternative Items

Show items a user might consider as an alternative to a particular item or set of items. For example, if a user is looking at toothpaste, this algorithm would most likely show other sizes or brands of toothpaste.

Complementary Items

Show items a user would purchase in addition to a particular item or set of items. For example, if a user is looking at toothpaste, this algorithm would tend to show toothbrushes and dental floss.

Zero-result Suggested Items

Show items to users on a zero-result page based on the term and data on intent Constructor has collected. The strategy primarily leverages refinements data -- what other users have clicked, added to cart and/or purchased after encountering this zero-result page. Useful to quickly capture lost conversions on zero result pages. Will return zero or more items depending on behavior and available data.

Filtered items (Show more from given facet)

Show items from a provided filter expression, such as grade: 6th, or recommended use: fishing, and optionally focus these on items more similar to a given product. If you sell educational books to an audience of teachers, you could apply this strategy on product pages to show products most similar to the current product within a specific grade level.

The only requirement for this strategy is a filter expression of the format filters[filter_name]=filter_value, as you would provide in browse or search endpoints. You may include several facets, such as filters[grade]=6&filters[Size]=S. Providing the optional item_id will prioritize items more similar to a particular product, which product will not be returned as a recommendation (to avoid duplication).

Create pod

There is not yet a customer-facing API for pod creation and configuration. To define the pods for your app or web property, reach out to support@constructor.io or in your dedicated Slack channel.

Retrieve recomendations

HTTP Request

GET https://ac.cnstrc.com/recommendations/v1/pods/[pod_id]?key=[your key]&section=[section]&item_id=[item id]&num_results=[num results]

URL Parameters

Parameter Description
pod_id Pod identifier

Query Parameters

Parameter Required? Description
key Yes The index from which you'd like to retrieve recommendations.
section Yes The index section you'd like to retrieve recommendations from, this is typically Products.
num_results No The number of recommendations to return. Defaults to 10. Generally you should request only the recommendations you intend to display to simplify tracking.
item_id Yes, if strategy is alternative or complementary Item id for which to retrieve recommendations. You can pass multiple item ids, e.g. &item_id=id1&item_id=id2, which may be useful, for example, for cart page recommendations.
ui Yes, if strategy is user featured or recently viewed items User id to retrieve recommendations for.
filters Yes, if strategy is filtered items A filtering expression with which to retrieve results.

Synonyms

Constructor's Synonym API allows customers to define groups of terms that will be treated as equivalent by the Constructor.io search and autosuggest algorithms. As an example, a grocery customer could create a group of synonyms for fat-free milk: fat-free milk, 0% milk, skim milk. A user searching for fat-free milk, 0% milk or skim milk would see all products containing the phrases fat-free milk, 0% milk or skim milk.

Index-by-index

Synonyms are set on each index key separately, so a customer could have separate synonym rules with their grocery property and their electronics property.

Case Insensitive

Synonyms ignore case, so a synonym rule for fat-free milk would apply to McCormick's Farmstand Fat-Free Milk as well as McCormick's farmstand fat-free milk .

Exact Phrase Match

Synonyms match the exact word ordering, so a rule for 0% milk would not apply to products McCormick's Farmstand Milk 0% or McCormick's Farmstand 0% fat milk. To match these products, you'd need to include milk 0% or 0% fat milk synonyms in the group.

This approach is taken because intervening words and term order can influence meaning: as one example, a shirt dress is not equivalent to a dress shirt.

Transitive Within Group

All synonyms in a group are transitive. Fat-free searches return 0% milk and skim milk products, skim milk searches return 0% milk products and vice-versa.

However, a separate group containing non-fat milk and skim milk would not establish equivalence between non-fat milk and 0% milk by virtue of the separate group establishing the skim milk relationship.

Add Synonym Group

This creates a new synonym group. Any phrases provided in the JSON are added to the group.


curl -X POST -H "Content-Type: application/json" \
  -d '{"synonyms": ["0% milk", "skim milk"]}' \
  -u"[your token]:" "https://ac.cnstrc.com/v1/synonym_groups?key=[your API key]"
// This method is not currently supported in our javascript client.
# This method is not currently supported in our ruby client.
# This method is not currently supported in our python client.
// This method is not currently supported in our php client.
# This method is not currently supported in our perl client.
// This method is not currently supported in our java client.
// This method is not currently supported in our csharp client.

The above command returns a 200 Success response on success.

HTTP Request

POST https://ac.cnstrc.com/v1/synonym_groups?key=[your API key]

Response Example

{
  "group_id": 4
}

JSON Parameters

Parameter Required? Description
synonyms Yes Allows you to add synonyms to the newly created group.

Modify Synonym Group

This can be used to reset a single synonym group to the given set of synonyms.


curl -X PUT -H "Content-Type: application/json" \
  -d '{"synonyms": ["0% milk", "skim milk", "nonfat milk"]}' \
  -u"[your token]:" "https://ac.cnstrc.com/v1/synonym_groups/4?key=[your API key]"
// This method is not currently supported in our javascript client.
# This method is not currently supported in our ruby client.
# This method is not currently supported in our python client.
// This method is not currently supported in our php client.
# This method is not currently supported in our perl client.
// This method is not currently supported in our java client.
// This method is not currently supported in our csharp client.

The above command returns a 204 Success response on success. For simplicity's sake, a 204 Success response will be returned even if the request leaves the group unchanged.

HTTP Request

PUT https://ac.cnstrc.com/v1/synonym_groups/[group_id]?key=[your API key]

JSON Parameters

Parameter Required? Description
synonyms Yes Determines what phrases will be included in the final synonym group.

Retrieve Synonym Groups

This endpoint is used to retrieve any or all synonym groups owned by the given key. If no group_id or phrase is given, all owned groups will be returned. Otherwise, only the synonym group with the given group id will be returned.


curl -X GET -H "Content-Type: application/json" \
  -u"[your token]:" "https://ac.cnstrc.com/v1/synonym_groups?key=[your API key]"

curl -X GET -H "Content-Type: application/json" \
  -u"[your token]:" "https://ac.cnstrc.com/v1/synonym_groups/4?key=[your API key]"
// This method is not currently supported in our javascript client.
# This method is not currently supported in our ruby client.
# This method is not currently supported in our python client.
// This method is not currently supported in our php client.
# This method is not currently supported in our perl client.
// This method is not currently supported in our java client.
// This method is not currently supported in our csharp client.

The above command returns a 200 Success response on success.

HTTP Request

GET https://ac.cnstrc.com/v1/synonym_groups?key=[your API key]

GET https://ac.cnstrc.com/v1/synonym_groups/[group_id]?key=[your API key]

GET https://ac.cnstrc.com/v1/synonym_groups/[phrase]?key=[your API key]

Response format

Response Format

{
  "synonym_groups": 
  [
    {
      "synonym_group_id": 4, 
      "synonyms": ["0% milk", "skim milk", "nonfat milk"]
    },
    {
      "synonym_group_id": 5, 
      "synonyms": ["orange juice", "oj", "o.j."]
    }
  ],
  "total_count": 2
}

Query Parameters

Parameter Required? Description
group_id No The synonym group you would like returned.
phrase No The phrase for which all synonym groups containing it will be returned.
num_results_per_page No The number of synonym groups to return. Defaults to 100.
page No The page of results to return. Defaults to 1.

Remove Synonym Groups

Note: If not given a group_id, all synonyms belonging to the given key will be deleted.


curl -X DELETE -H "Content-Type: application/json" \
  -u"[your token]:" "https://ac.cnstrc.com/v1/synonym_groups?key=[your API key]"


curl -X DELETE -H "Content-Type: application/json" \
  -u"[your token]:" "https://ac.cnstrc.com/v1/synonym_groups/4?key=[your API key]"
// This method is not currently supported in our javascript client.
# This method is not currently supported in our ruby client.
# This method is not currently supported in our python client.
// This method is not currently supported in our php client.
# This method is not currently supported in our perl client.
// This method is not currently supported in our java client.
// This method is not currently supported in our csharp client.

The above command returns a 200 Success response on success.

HTTP Request

GET https://ac.cnstrc.com/v1/synonym_groups?key=[your API key]

GET https://ac.cnstrc.com/v1/synonym_groups/[group_id]?key=[your API key]

Query Parameters

Parameter Required? Description
group_id No The synonym group you would like deleted.

Request tag rules

Request tag rules are a powerful tool to adjust result ranking for classes of queries. The concept operates on tags assigned to users' requests at query time.

Example use cases include:

Tagging requests

Currently request tags are applied by passing a value in with the us query parameter (user segment). In the future certain types of automatic request tagging will be exposed in this endpoint, such that rules can be generated based on location, time-of-day and other parameters. The goal is to give customer teams similar optimization abilities as applied automatically by Constructor.

You can pass custom user segments to search or behavioral tracking endpoints using the us argument like so: &us=segment1. This then gives one the ability to define behavior on the basis of tag_name user_segment and tag_value segment1.

Types of rules

Note that request tag rules only support boost and bury rules for the time being to increase or decrease ranking of products matching a given condition for requests with the given tag.

Slotting, blacklisting and whitelisting rule types are not yet supported.

Rule limits

A maximum of 50 boost rules may be applied to a given key-value pair - in the above case, the user_segment:segment1 pair.

Applying rules

If a rule has not been defined for a particular request tag, default ranking behavior will be applied. In other words, you can safely pass user segments that have not yet been defined.

If conditions from several rules apply to a given request their boost values will be summed up.

Create request tag rule

To create a rule for the previous example, you can use the following endpoint:

curl -X PATCH -H "Content-Type: application/json"   -d '{
   "boost_rules":[
            {
               "active":true,
               "automatically_generated":false,
               "rule":{
                  "boost":0.48,
                  "filters":{
                     "group_id":[
                        "48"
                     ]
                  }
               },
               "start_time": "2020-07-01 00:00:00",
               "end_time": "2020-07-14 00:00:00"
            }
         ]
}'   -u"[your token]:" "https://ac.cnstrc.com/refined_tags/user_segment/segment1?key=[key]"
Not available
Not available
Not available
Not available
Not available
Not available
Not available

This request will replace existing rules for the user_segment:segment1 key-value pair with the single boost rule provided in the request body.

The above command(s) return a 200 Success response on success.

HTTP Request

PATCH https://ac.cnstrc.com/refined_tags/[tag_name]/[tag_value]?key=[key]

Response format

{
   "allow_automatic_rules":true,
   "boost_rules":[
      {
         "active":true,
         "automatically_generated":false,
         "created_at":"2020-07-03T17:41:56",
         "end_time":null,
         "rule":{
            "boost":0.48,
            "filters":{
               "group_id":[
                  "48"
               ]
            }
         },
         "rule_type":"BOOST",
         "start_time":"2020-07-01 00:00:00", 
         "end_time": "2020-07-14 00:00:00",
         "updated_at":null
      }
   ],
   "tag_name":"user_segment",
   "tag_value":"segment1"
}

URL Parameters

Parameter Description
tag_name The name of the tag you'd like to retrieve rules for.
tag_value The value of the tag you'd like to retrieve rules for.

Query JSON Parameters

Parameter Required? Description
boost_rules Yes List of boost rules that will be applied for matching requests.

Each boost_rule object has the following structure:

Parameter Required? Description
rule Yes An object with a boost field and a filters field, documented below.
active No Your rule can be defined but set to inactive if you wish by setting the active field to false.
automatically_generated No Rules that are generated automatically by Constructor are flagged with true.
start_time No Start time when the rule should be enabled.
end_time No End time when the rule should be disabled.

Each rule object has the following structure:

Parameter Required? Description
boost Yes A value in the range of -1 to +1 representing the standard deviations by which matching items' ranking score should be decreased or increased.
filters Yes Indicates the properties of the products to which this boost should be applied. For more examples of filter expressions, refer to Retrieve searchandizing rules.

List request tag rules

curl -X GET -u"[your token]:" "https://ac.cnstrc.com/refined_tags/user_segment/segment1?key=[key]"
Not available
Not available
Not available
Not available
Not available
Not available
Not available

The above command(s) return a 200 Success response on success.

HTTP Request

GET https://ac.cnstrc.com/refined_tags/[tag_name]/[tag_value]?key=[key]

Response format

{
   "refined_tags":[
      {
         "allow_automatic_rules":true,
         "boost_rules":[
            {
               "active":true,
               "automatically_generated":true,
               "created_at":"2020-06-03T17:41:56",
               "end_time":null,
               "rule":{
                  "boost":0.48,
                  "filters":{
                     "group_id":[
                        "48"
                     ]
                  }
               },
               "rule_type":"BOOST",
               "start_time":null,
               "updated_at":null
            }
         ],
         "tag_name":"user_segment",
         "tag_value":"segment1"
      }
   ],
   "total_count":1
}

URL Parameters

Parameter Description
tag_name The name of the tag you'd like to retrieve rules for.
tag_value The value of the tag you'd like to retrieve rules for.

Remove request tag rules

curl -X DELETE 
  -u"[your token]:" 
  "https://ac.cnstrc.com/refined_tags/user_segment/segment1?key=[key]"
Not available
Not available
Not available
Not available
Not available
Not available
Not available

The above command(s) return a 200 Success response on success.

HTTP Request

DELETE https://ac.cnstrc.com/refined_tags/[tag_name]/[tag_value]?key=[key]

Response format

{
   "allow_automatic_rules":true,
   "boost_rules":[
      {
         "active":true,
         "automatically_generated":true,
         "created_at":"2020-06-03T17:41:56",
         "end_time":null,
         "rule":{
            "boost":0.48,
            "filters":{
               "group_id":[
                  "48"
               ]
            }
         },
         "rule_type":"BOOST",
         "start_time":null,
         "updated_at":null
      }
   ],
   "tag_name":"user_segment",
   "tag_value":"segment1"
}

URL Parameters

Parameter Description
tag_name The name of the tag you'd like to remove rules from.
tag_value The value of the tag you'd like to remove rules from.

Tasks

Retrieve All Tasks

The tasks API allows customers using Constructor's ingestion service to request the status of asynchronous jobs, such as catalog uploads and user data requests made for compliance reasons.

The tasks endpoint is most commonly used to check on the status of files uploaded for ingestion to the FTP and catalog HTTP endpoints, to request ingestion jobs in progress, queued, succeeded and failed.

curl -X GET -H "Content-Type: application/json" \
  -u"[your token]:" "https://ac.cnstrc.com/v1/tasks?key=[your API key]&page=[page number]&num_results_per_page=[number of tasks per page]"

HTTP Request

GET https://ac.cnstrc.com/v1/tasks?key=[your API key]&page=[page number]&num_results_per_page=[number of tasks per page]

Response format

{
    "total_count": 1,
    "tasks": [
        {
            "id": 0,
            "type": "ingestion",
            "status": "QUEUED",
            "submission_time": "2020-04-24T15:06:27Z",
            "last_update": null,
            "filename": "somefile.csv",
        }
    ],
    "status_counts": {
        "QUEUED": 1,
        "DONE": 0,
        "IN_PROGRESS": 0,
        "FAILED": 0,
    }
}

Query Parameters

Parameter Required? Description
key Yes The key of the index you'd like to to retrieve tasks for.
page No Page number you'd like to request. Defaults to 1.
num_results_per_page No Number of tasks per page in paginated response. Default value is 20.

Retrieve By Specific Task ID

curl -X GET -H "Content-Type: application/json" \
  -u"[your token]:" "https://ac.cnstrc.com/v1/task/0?key=[your API key]"

HTTP Request

GET https://ac.cnstrc.com/v1/task/[task_id]?key=[your API key]

Response format

{
    "id": 0,
    "status": "QUEUED",
    "submission_time": "2020-04-24T15:06:27Z",
    "last_update": null,
    "start_time": null",
}

Response fields

Parameter Description
id The id of the task.
status Current status of the task (QUEUED, DONE, FAILED, IN_PROGRESS).
submission_time Time of task submission.
last_update Last time the status of this task was updated. (May be null if the task has never been run before).
start_time Starting time of the task. (May be null if the task has not been run yet).
type The type of the task. References the job that is done by the task. Possible values: ingestion, user_data_request
filename Only for type="ingestion". The name of the file uploaded to constructor.
protocol Only for type="ingestion". Describes if the ingestion was created via FTP ("ftp"), API ("http") or other source (null).

URL Parameters

Parameter Description
task_id The id of the task you would like to retrieve information about.

Query Parameters

Parameter Required? Description
key Yes The index you'd like to to retrieve tasks for.

Task types

Collections

Collections are a powerful tool to create groups of items based on dynamic rules. For instance, one can define the Cyber Monday collection as "the set of all items from the Electronics category which cost less than $200, as well as all laptops that cost less than $800".

Any combination of facets (uploaded through the Add an Item API) and group ids can be used in the filter_expression that defines a collection.

Items can also be manually added to a collection with the items field. (See the section on adding items to a collection manually)

To serve production end-user collection requests, use the browse endpoint by specifying a collection's id /browse/collection_id/<collection_id>.

Features

Create collection

To create a collection, use the POST method.

Create collection

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"id": "my-id", "display_name": "My Collection", "filter_expression": {"name": "Type", "value": "Laptop"}, "data": {"foo": "bar"}}'
  -u "[your token]:"
  "https://ac.cnstrc.com/v1/collections?key=[your API key]&section=[your section]"

Response

{
  "id": "my-id",
  "created_at": "2019-04-12T18:15:30",
  "updated_at": null,
  "display_name": "My Collection",
  "filter_expression": {"name": "Type", "value": "Laptop"},
  "data": {"foo": "bar"}
}

HTTP request

POST https://ac.cnstrc.com/v1/collections?key=[your API key]&section=[your section]

URL Parameters

Attribute Type Required? Description
section string Yes The section that contains items in this collection

JSON Parameters

Attribute Type Required? Description
id string Yes The id that you want to use to refer to this collection
display_name string Yes A display name for this collection
filter_expression object No The filter expression that defines this collection
data object No JSON object with custom metadata attached with the collection. Defaults to null if not provided.

Add items dynamically

Items are added dynamically with logical operators composed of filters (facets and item groups) via the filter_expression.

This could be a valid filter_expression for the "Cyber Monday" example

{
  "or": [
    {
      "and": [
        {
          "name": "group_id",
          "value": "electronics-group-id"
        },
        {
          "name": "Price",
          "range": ["-inf", 200]
        }
      ]
    },
    {
      "and": [
        {
          "name": "Type",
          "value": "Laptop"
        },
        {
          "not": {
            "name": "Price",
            "range": [800, "inf"]
          }
        }
      ]
    }
  ]
}

Add items manually

As discussed above, collections allow customers to create dynamic assortments of products based on rules using product facet and category (group) taxonomy. This allows dynamic product assortments for one-time uses like emails, as well longer-lived featured product listings to link from the homepage or elsewhere. One example is if a merchant wanted to show all McCormick's Farmstand brand Pet Food products that are Organic and between $10 an $20.

In addition to the dynamic rules, customers may also add items manually one-by-one to include products in the collection that may not correspond exactly to a set of product filters. One example is if there's a list of promotional products from a Brand partner.

Collections slotting in the searchandizing UI allows making these manual additions, and the items endpoint on a collections resource (documented here) allows this manual update from API.

Adding (or modifying) items added to a collection manually will require an index build, so changes go live in around 30 minutes or less depending on the size of the index. Plan your updates accordingly, especially when replacing conditions (which changes take effect in a couple of minutes) with items.


curl -X PUT -H "Content-Type: application/json" \
  -d '{"items": [{"id": "pug"}]}' \
  -u"[your token]:" "https://ac.cnstrc.com/v1/collections/dog-collection/items?key=[your API key]&section=[your section]"
// This method is not currently supported in our javascript client.
# This method is not currently supported in our ruby client.
# This method is not currently supported in our python client.
// This method is not currently supported in our php client.
# This method is not currently supported in our perl client.
// This method is not currently supported in our java client.
// This method is not currently supported in our csharp client.

The above command returns a 200 Success response on success.

HTTP Request

PUT https://ac.cnstrc.com/v1/collections/[collection_id]/items?key=[your API key]&section=[your section]

URL Parameters

Attribute Type Required? Description
collection_id string Yes The id of the collection you would like to add items to.

JSON Parameters

Parameter Required? Description
items Yes Array of the items you wish to manually add to the collection.
id Yes id(s) of the item(s) you wish to manually add to the collection.

Remove manual items

Items that have been added manually can be removed with the DELETE method.

curl -X DELETE -H "Content-Type: application/json" \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/collections/dog-collection/items/labradoodle?key=[your API key]&section=[your section]"
// This method is not currently supported in our javascript client.
# This method is not currently supported in our ruby client.
# This method is not currently supported in our python client.
// This method is not currently supported in our php client.
# This method is not currently supported in our perl client.
// This method is not currently supported in our java client.
// This method is not currently supported in our csharp client.

The above command returns a 204 Success response on success.

HTTP Requests

DELETE https://ac.cnstrc.com/v1/collections/[collection_id]/items/[item_id]?key=[your API key]&section=[your section]

URL Parameters

Attribute Type Required? Description
collection_id string Yes The id of the collection you would like to remove items from.
item_id string Yes The id of the item you wish to remove.

Retrieve all collections

To retrieve all collections, use the GET method.

Get collections

curl -X GET \
  -H "Content-Type: application/json" \
  -u "[your token]:" \
  "https://ac.cnstrc.com/v1/collections?key=[your API key]&section=[your section]&sort_by=display_name&sort_order=ascending&page=1&num_results_per_page=20"

Response

{
  "collections": [
    {
      "id": "my-id",
      "created_at": "2019-04-12T18:15:30",
      "updated_at": null,
      "display_name": "My Collection",
      "filter_expression": {"name": "Type", "value": "Laptop"},
      "data": {"foo": "bar"},
    }
  ],
  "total_count": 1
}

HTTP request

GET https://ac.cnstrc.com/v1/collections?key=[your API key]&section=[your section]&sort_by=display_name&sort_order=ascending&page=1&num_results_per_page=20

URL Parameters

Attribute Type Required? Description
section string Yes The section in which your collection is defined. Typically, this will be Products.
page integer No The page number (defaults to 1)
num_results_per_page integer No The number of collections you want to retrieve
query string No Search for collections with a matching id or display name
sort_by string No Field name to sort results by. One of display_name, created_at, updated_at
sort_order string No Sort order of results sorted by sort_by field. One of ascending, descending. Defaults to ascending if not provided

Retrieve a single collection

To retrieve a single collection, use the GET method.

Get collection

curl -X GET \
  -H "Content-Type: application/json" \
  -u "[your token]:"
  "https://ac.cnstrc.com/v1/collections/my-id?key=[your API key]&section=[your section]"

Response

{
    "id": "my-id",
    "created_at": "2019-04-12T18:15:30",
    "updated_at": null,
    "display_name": "My Collection",
    "filter_expression": {"name": "Type", "value": "Laptop"},
    "data": {"foo": "bar"}
}

HTTP request

GET https://ac.cnstrc.com/v1/collections/<collection_id>?key=[your API key]&section=[your section]

URL Parameters

Attribute Type Required? Description
section string Yes The section in which your collection is defined. Typically, this will be Products.

Retrieve collection items

Intended use

The retrieve collection items endpoint allows developers to verify items added to a collection are returned as expected (without having to wait for an index rebuild) or to sync collection items with outside systems of record, such as an eCommerce platform. To simplify both of these activities, the retrieve collection items endpoint will return all items in the collection and is not capped at a maximum of 999 items.

Note: this endpoint is intended for backend development or integration purposes and is not supported for serving production end-user traffic.

To serve production end-user collection requests, use the browse endpoint by specifying a collection's id as so: /browse/collection_id/<collection_id>.

The browse endpoint provides several benefits:

Request format

To retrieve collection items, use the GET method on the collection items resource.

Items added manually and dynamically can be retrieved together or separately by setting manual_items and dynamic_items flags with the request below:

curl -X GET \
  -H "Content-Type: application/json" \
  -u "[your token]:"
  "https://ac.cnstrc.com/v1/collections/dog-collection/items?key=[your API key]&section=[your section]&filters[manual_items]=true&filters[dynamic_items]=false&page=1&num_results_per_page=3"
// This method is not currently supported in our javascript client.
# This method is not currently supported in our ruby client.
# This method is not currently supported in our python client.
// This method is not currently supported in our php client.
# This method is not currently supported in our perl client.
// This method is not currently supported in our java client.
// This method is not currently supported in our csharp client.

HTTP Request

GET https://ac.cnstrc.com/v1/collections/[collection_id]/items?key=[your API key]&section=[your section]&filters[manual_items]=true&filters[dynamic_items]=true&page=1&num_results_per_page=3

Response format

{
  "items": [
      {
        "id": "corgi",
        "type": "dynamic"
      },
      {
        "id": "dachshund",
        "type": "dynamic"
      },
      {
        "created_at": "2019-04-12T18:15:30",
        "updated_at": null,
        "id": "labradoodle",
        "type": "manual"
      }
  ],
  "total_count": 3
}

URL Parameters

Attribute Type Required? Description
collection_id string Yes The id of the collection from which you'd like to retrieve items.

Query Parameters

Attribute Type Required? Description
key string Yes The index you'd like to to retrieve results from.
section string No The section in which your collection is defined. Typically, this will be Products, but the default section will be chosen if no value is provided.
filters[manual_items] boolean No Whether to include manually added items in the response. Defaults to true.
filters[dynamic_items] boolean No Whether to include dynamic items (matching collection.filter_expression) in the response. Defaults to false for backwards compatibility.
page integer No Page number. Defaults to 1.
num_results_per_page integer No Number of items per page. Default value is 100.

Response format

Attribute Type Description
id string Item customer ID.
type string Describes the method of addition for the item - manual if it was manually added to the collection, dynamic if it matches collection.filter_expression.
created_at string Present only for manually added items. Time when the item was added to the collection. (ISO8601 format)
updated_at string Present only for manually added items. Time when the item-collection association was last updated (ISO8601 format)

Update a collection (completely)

To update a collection completely (replace), the PUT method needs to be used.

Replace collection

curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{"id": "new-id", "display_name": "New Collection Name", "filter_expression": {"name": "Type", "value": "New"}, "data": {"foo": "bar"}}' \
  -u "[your token]:"
  "https://ac.cnstrc.com/v1/collections/my-id?key=[your API key]&section=[your section]"

Response

{
    "id": "new-id",
    "created_at": "2019-04-12T18:15:30",
    "updated_at": "2019-04-13T19:15:30",
    "display_name": "New Collection Name",
    "filter_expression": {"name": "Type", "value": "New"},
    "data": {"foo": "bar"}
}

HTTP request

PUT https://ac.cnstrc.com/v1/collections/<collection_id>?key=[your API key]&section=[your section]

URL Parameters

Attribute Type Required? Description
section string Yes The section in which your collection is defined. Typically, this will be Products.

JSON Parameters

The JSON parameters are the same as those in the Create collection section

Update a collection (partially)

To update a collection partially (change only some attributes) the PATCH method needs to be used.

Modify collection

curl -X PATCH \
  -H "Content-Type: application/json" \
  -d '{"display_name": "New Collection Name"}' \
  -u "[your token]:"
  "https://ac.cnstrc.com/v1/collections/my-id?key=[your API key]&section=[your section]"

Response

{
    "id": "my-id",
    "created_at": "2019-04-12T18:15:30",
    "updated_at": "2019-04-13T19:15:30",
    "display_name": "New Collection Name",
    "filter_expression": {"name": "Type", "value": "Laptop"},
    "data": null,
}

HTTP request

PATCH https://ac.cnstrc.com/v1/collections/<collection_id>?key=[your API key]&section=[your section]

URL Parameters

Attribute Type Required? Description
section string Yes The section in which your collection is defined. Typically, this will be Products.

JSON Parameters

The JSON parameters can be any subset of those listed in the Create collection section

Facets

Facets (also known as filters) refer to the options often provided to the left of search results, which allow users to narrow their result set along common product attributes, such as the items' price or brand.

The facets API is used to configure display and sort options for facets. For example you can set a display name, control sort order, define how numeric ranges should be returned and more.

Keys, values, groups and options

Facet configurations are represented with two related concepts: Facet groups and facet options. Facet groups represent the facet key and facet options represent the facet value. For example, imagining an item with Brand: Nike, brand would be the facet group (or key), while nike would represent the facet option (or value).

Facets don't need to exist in product data to be configured

To allow for creating facet configurations in advance of uploading products referencing these facet configurations, facet configurations can be defined for facet groups and facet options that don't yet exist in the database.

While this behavior isn't yet supported in the customer dashboard, it is supported in the API.

Facets don't require configuration to be displayed

Facets are displayed automatically if they exist for items you've uploaded to your catalog. No configuration is necessary to get them to appear.

Facets are referenced by their value in your catalog

Facets are referenced by the key and value you associate with the items you upload in your catalog via API or feed in the facets object described in the Add an Item documentation.

Protected and hidden facets

Product catalogs often include facets you don't want to display to end users. These may be old, unused, confusing to users or sensitive. Consider a few cases to understand.

Protected Facets The business team wants to incorporate inventory and margins in the ranking formula and in the merchant tools dashboard. However, this is sensitive data: Not only do we want to hide inventory and margins from end users, we also want to prevent them from being displayed for search requests without authentication. We can set the protected: true attribute to facilitate this.

Hidden Facets Other times, a merchant team will want to use an attribute to define merchandizing goals. We don't want to show it to end users, but it's not a problem if it could conceivably be accessed from the API. Imagine there's a season property on items that is used to define a Collection, or that there are some unused facets we don't want to show any more. We can set the hidden: true attribute to facilitate this case.

Create a facet config

To create a configuration for a facet, use the POST method.

Create a facet configuration

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"name": "brand_facet", "display_name": "Brand", "sort_order": "relevance", "type": "multiple", "match_type": "all", "hidden": false, "enable_nlp": false, "data": {"config_key": "config_val"}, "options": [{"value": "nature_valley", "display_name": "Nature Valley", "position": 1, "data": null, "hidden": false}]}'
  -u "[your token]"
  "https://ac.cnstrc.com/v1/facets?key=[your API key]&section=[your section]"

Response

{
    "name": "brand_facet",
    "display_name": "Brand",
    "sort_order": "relevance",
    "sort_descending": false,
    "type": "multiple",
    "range_type": null,
    "range_format": null,
    "range_inclusive": null,
    "bucket_size": null,
    "range_limits": null,
    "match_type": "all",
    "position": null,
    "hidden": false,
    "protected": false,
    "data": {
        "config_key": "config_val"
    },
    "options": [
        {
            "value": "nature_valley",
            "display_name": "Nature Valley",
            "position": 1,
            "data": null,
            "hidden": false
        },
    ]
}

HTTP request

POST https://ac.cnstrc.com/v1/facets?key=[your API key]&section=[your section]

URL Parameters

Attribute Type Required? Description
section string No The section in which your facet is defined. Typically, this will be Products.

JSON Parameters

Attribute Type Required? Description
name string Yes The facet name used to refer to the facet in your catalog - whether your feed or API updates. Must be unique inside the section and key.
display_name string No The name of the facet to present to end users. Default value is null, in which case the name will be presented.
sort_order string No Determines the default criterion by which options of this facet group are sorted. Must be one of relevance, value (to sort facet options alpha-numerically), num_matches (to sort facet options by number of matching results). Default value is relevance. Sort can be overriden by setting the position attribute on facet options.
sort_descending boolean No true if this facet group's options should be sorted in descending order, false to sort ascending. Default value is true if sort_order is relevance and false for other sort orders. Setting sort_order: relevance will set sort_descending: true for POST, PUT, PATCH endpoints if sort_descending is not explicitly set in the request.
type string Yes Type of facet. One of multiple or range. Use multiple to display the facet as categorical values (for example, a Brand facet with values of Nike, Adidas and Puma)and range to display as a numeric range. You must use range when you want to display a slider, as well as when you want to display a list of range buckets.
range_type string Required if facet type is range and range_format is options (i.e: range buckets). Not required otherwise. Specifies whether the range buckets are determined dynamically (based on the values of matching facet options) or statically. One of dynamic, static. If the facet is not configured as a range, value will be null. Default value is null.
range_format string Required for type range, not required otherwise. Format of range facets. Determines whether the facet is configured to display as a slider (in which case the search endpoint will return only min & max values) or as a list of buckets. One of boundaries (for sliders), options (for buckets). Default value is null.
range_inclusive string No Used to create inclusive buckets. For example, for a rating facet, you might want to display options like 1 and above, 2 and above, 3 and above, etc. Values can be either above (options have no upper bound), below (options have no lower bound), or null if range options should not be inclusive. Default value is null
bucket_size float No. Either this or range_limits are required for facet type range, format options and range_type static
range_limits json No Either this or bucket_size are required for facet type range, format options and range_type static
match_type string No Match types specify the behavior of filters when multiple options of the same facet (e.g: color: yellow & blue) are selected. Specifies whether the results must match all options, any of them or none. One of any, all, none. Default value is any.
position integer No Used to slot facet groups to fixed positions. Default value is null.
hidden boolean No Specifies whether the facet is hidden from users. Use this for facet data that you don't want shown to end users, but that isn't sensitive. Default value is false.
protected boolean No Specifies whether the facet is protected from users. Setting this to true will require authentication to view the facet. Default value is false.
options list of Facet options No List of facet option configurations to create and associate with this facet group. Default value is [] (empty list)
data dict No Dictionary with any extra facet data. Default value is {} (empty dictionary)

Get all facet configs

To retrieve all facet configurations, use the GET method.

Get facets

curl -X GET \
  -H "Content-Type: application/json" \
  -u "[your token]"
  "https://ac.cnstrc.com/v1/facets?key=[your API key]&section=[your section]&page=[page number]&num_results_per_page=[number of facet groups per page]"

Response

{
    "facets": [
        {
            "name": "brand_facet",
            "display_name": "Brand",
            "sort_order": "relevance",
            "sort_descending": false,
            "type": "multiple",
            "range_type": null,
            "range_format": null,
            "range_inclusive": null,
            "bucket_size": null,
            "range_limits": null,
            "match_type": "any",
            "position": null,
            "hidden": false,
            "protected": false,
            "data": {}
        },
        {
            "name": "price_facet",
            "display_name": "Price",
            "sort_order": "relevance",
            "sort_descending": false,
            "type": "range",
            "range_type": "dynamic",
            "range_format": "boundaries",
            "range_inclusive": null,
            "bucket_size": null,
            "range_limits": null,
            "match_type": "any",
            "position": null,
            "hidden": false,
            "protected": false,
            "data": {}
        },
        ...
    ],
    "total_count": 10
}

HTTP request

GET https://ac.cnstrc.com/v1/facets?key=[your API key]&section=[your section]&page=[page number]&num_results_per_page=[number of facet groups per page]

URL Parameters

Attribute Type Required? Description
section string No The section in which your facet is defined. Typically, this will be Products.
page integer No Page number you'd like to request. Defaults to 1.
num_results_per_page integer No Number of facets per page in paginated response. Default value is 100.

Get a single facet's config

To retrieve a single facet group's configuration, use the GET method.

Get facet

curl -X GET \
  -H "Content-Type: application/json" \
  -u "[your token]"
  "https://ac.cnstrc.com/v1/facets/<facet_group_name>?key=[your API key]&section=[your section]"

Response

{
    "name": "brand_facet",
    "display_name": "Brand",
    "sort_order": "relevance",
    "sort_descending": false,
    "type": "multiple",
    "range_type": null,
    "range_format": null,
    "range_inclusive": null,
    "bucket_size": null,
    "range_limits": null,
    "match_type": "any",
    "position": null,
    "hidden": false,
    "protected": false,
    "data": {},
    "options": [
        {
            "value": "mccormicks-organics",
            "display_name": "McCormick's Organics",
            "position": 1,
            "data": null,
            "hidden": false
        },
        {
            "value": "nature-valley",
            "display_name": "Nature Valley",
            "position": 2,
            "data": null,
            "hidden": false
        },
        ...
    ]
}

HTTP request

GET https://ac.cnstrc.com/v1/facets/<facet_group_name>?key=[your API key]&section=[your section]

URL Parameters

Attribute Type Required? Description
section string No The section in which your facet is defined. Typically, this will be Products.

Update facet configs (partial)

To update multiple facet configurations partially at once, use the PATCH method.

This will avoid overwriting configurations and should be used if you only want to update configurations for a few fields in a facet group configuration.

Batch update facets

curl -X PATCH \
  -H "Content-Type: application/json" \
  -d '[{"name": "brand_facet", "display_name": "Brand"}, {"name": "color_facet", "hidden": true, "position": 1}]'
  -u "[your token]"
  "https://ac.cnstrc.com/v1/facets?key=[your API key]&section=[your section]"

Response

[
    {
        "name": "brand_facet",
        "display_name": "Brand",
        "sort_order": "relevance",
        "sort_descending": false,
        "type": "multiple",
        "range_type": null,
        "range_format": null,
        "range_inclusive": null,
        "bucket_size": null,
        "range_limits": null,
        "match_type": "all",
        "position": null,
        "hidden": false,
        "protected": false,
        "data": {}
    },
    {
        "name": "color_facet",
        "display_name": "Color",
        "sort_order": "relevance",
        "sort_descending": false,
        "type": "multiple",
        "range_type": null,
        "range_format": null,
        "range_inclusive": null,
        "bucket_size": null,
        "range_limits": null,
        "match_type": "all",
        "position": 1,
        "hidden": true,
        "protected": false,
        "data": {}
    },
]

HTTP request

PATCH https://ac.cnstrc.com/v1/facets?key=[your API key]&section=[your section]

URL Parameters

Attribute Type Required? Description
section string No The section in which your facet is defined. Typically, this will be Products.

JSON Parameters

Batch update endpoint expects a list of item updates. Each item parameters can be any subset of those listed in the Create a facet configuration section, except that options parameter is not allowed and name parameter is required (to identify which facets to update).

Update a facet config (total)

To update the configuration of a facet completely (replace), use the PUT method.

IMPORTANT WARNING: This will overwrite all other configurations you may have defined for the facet group, resetting them to their defaults. This includes all facet option configurations you may have defined.

Replace facet

curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{"name": "some name", "type": "multiple", "hidden": true}' \
  -u "[your token]"
  "https://ac.cnstrc.com/v1/facets/<facet_group_name>?key=[your API key]&section=[your section]"

Response

{
    "name": "some name",
    "display_name": null,
    "sort_order": "relevance",
    "sort_descending": false,
    "type": "multiple",
    "range_type": null,
    "range_format": null,
    "range_inclusive": null,
    "bucket_size": null,
    "range_limits": null,
    "match_type": "any",
    "position": null,
    "hidden": true,
    "protected": false,
    "data": {},
    "options": []
}

HTTP request

PUT https://ac.cnstrc.com/v1/facets/<facet_group_name>?key=[your API key]&section=[your section]

URL Parameters

Attribute Type Required? Description
section string No The section in which your facet is defined. Typically, this will be Products.

JSON Parameters

The JSON parameters are the same as those in the Create a facet configuration section

Update a facet config (partial)

To update the configuration of a facet partially (change only some attributes), use the PATCH method.

Modify facet

curl -X PATCH \
  -H "Content-Type: application/json" \
  -d '{"match_type": "any"}' \
  -u "[your token]"
  "https://ac.cnstrc.com/v1/facets/<facet_group_name>?key=[your API key]&section=[your section]"

Response

{
    "name": "brand_facet",
    "display_name": "Brand",
    "sort_order": "relevance",
    "sort_descending": false,
    "type": "multiple",
    "range_type": null,
    "range_format": null,
    "range_inclusive": null,
    "bucket_size": null,
    "range_limits": null,
    "match_type": "any",
    "position": null,
    "hidden": false,
    "protected": false,
    "data": {},
    "options": [
        {
            "value": "nature_valley",
            "display_name": "Nature Valley",
            "position": 1,
            "data": null,
            "hidden": false
        },
    ]
}

HTTP request

PATCH https://ac.cnstrc.com/v1/facets/<facet_group_name>?key=[your API key]&section=[your section]

URL Parameters

Attribute Type Required? Description
section string No The section in which your facet is defined. Typically, this will be Products.

JSON Parameters

The JSON parameters can be any subset of those listed in the Create a facet configuration section

Delete a facet config

To delete the configuration of a facet use the DELETE method. This does not delete the facet from items in your index you may have uploaded previously - if you wish to stop showing a facet to a user, configure it as hidden.

IMPORTANT WARNING Once a facet group's configuration is deleted, all configurations will return to their default values. This includes all facet option configurations (display name, position, etc) you may have defined for the facet group.

Delete a facet configuration

curl -X DELETE \
  -H "Content-Type: application/json" \
  -u "[your token]"
  "https://ac.cnstrc.com/v1/facets/<facet_group_name>?key=[your API key]&section=[your section]"

Response

{
    "name": "brand_facet",
    "display_name": "Brand",
    "sort_order": "relevance",
    "sort_descending": false,
    "type": "multiple",
    "range_type": null,
    "range_format": null,
    "range_inclusive": null,
    "bucket_size": null,
    "range_limits": null,
    "match_type": "all",
    "position": null,
    "hidden": false,
    "protected": false,
    "data": {},
    "options": [
        {
            "value": "nature_valley",
            "display_name": "Nature Valley",
            "position": 1,
            "data": null,
            "hidden": false,
        },
    ]
}

HTTP request

DELETE https://ac.cnstrc.com/v1/facets/<facet_group_name>?key=[your API key]&section=[your section]

URL Parameters

Attribute Type Required? Description
section string No The section in which your facet is defined. Typically, this will be Products.

Facet config examples

The following examples on the right side describe facet configuration requests you'd make (per Create a facet configuration) to fulfill different use-cases.

Brand facet with alphabetically sorted options and display name configuration for 3 facet options.

{
    "name": "brand",
    "display_name": "Brand",
    "sort_order": "value",
    "type": "multiple",
    "data": {},
    "options": [
        {
            "value": "nike",
            "display_name": "Nike"
        },
        {
            "value": "adidas",
            "display_name": "Adidas"
        },
        {
            "value": "under_armor"
            "display_name": "Under Armor"
        }
    ]
}

Price facet configured to be returned as a slider, allowing filtering of products by a price between two values.

{
    "name": "price",
    "display_name": "Price",
    "type": "range",
    "range_format": "boundaries"
}

Price facet as a list of buckets of size 100, allowing you to create a filter as a list of price buckets, like $0-100, $100-200, etc.

{
    "name": "Price",
    "type": "range",
    "range_type": "static",
    "range_format": "options",
    "bucket_size": 100
}

Rating facet with overlapping buckets, for instance if you want to create a rating filter with options "1 and above", "2 and above", "3 and above", etc.

{
    "name": "Rating",
    "type": "range",
    "range_type": "static",
    "range_format": "options",
    "range_inclusive": "above",
    "range_limits": [1, 2, 3, 4]
}

Facet options

Facet options represent the "values" for Facets. For a Brand facet, these would be Nike, Adidas or Puma.

The facet options API may be used to configure the way facet options are displayed. Using this set of endpoints, you may slot options to specific positions, change their display names, hide them, etc)

Create a facet option config

To add a new facet option configuration to a facet group, use the POST method.

Create a facet option configuration

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"value": "nature_valley", "display_name": "Nature Valley", "position": 1, "data": null, "hidden": false}'
  -u "[your token]"
  "https://ac.cnstrc.com/v1/facets/<facet_group_name>/options?key=[your API key]&section=[your section]"

Response

{
    "value": "nature_valley",
    "display_name": "Nature Valley",
    "position": 1,
    "data": null,
    "hidden": false,
}

HTTP request

POST https://ac.cnstrc.com/v1/facets/<facet_group_name>/options?key=[your API key]&section=[your section]

URL Parameters

Attribute Type Required? Description
section string No The section in which your facet is defined. Typically, this will be Products.

JSON Parameters

Attribute Type Required? Description
value string Yes A value for this facet option. Must be unique for particular facet
display_name string No A display name for this facet option. Default value is null
position integer No Used to order facet options. Default value is null
hidden boolean No Specifies whether the facet option is hidden from users. Default value is false
data dict No Dictionary with any extra facet option data. Default value is null

Get all option configs for facet

To get configurations of all facet options for a particular facet group, use the GET method.

Get facet options

curl -X GET \
  -H "Content-Type: application/json" \
  -u "[your token]"
  "https://ac.cnstrc.com/v1/facets/<facet_group_name>/options?key=[your API key]&section=[your section]&page=[page number]&num_results_per_page=[number of facet options per page]"

Response

{
    "facet_options": [
        {
            "value": "Nature Valley",
            "display_name": "nature_valley",
            "position": 1,
            "data": null,
            "hidden": false,
        },
        {
            "value": "McCormick's Organics",
            "display_name": "mccormicks-organics",
            "position": 2,
            "data": null,
            "hidden": false,
        },
        ...
    ],
    "total_count": 10,
}

HTTP request

GET https://ac.cnstrc.com/v1/facets/<facet_group_name>/options?key=[your API key]&section=[your section]&page=[page number]&num_results_per_page=[number of facet options per page]

URL Parameters

Attribute Type Required? Description
section string No The section in which your facet is defined. Typically, this will be Products.
page integer No Page number you'd like to request. Defaults to 1.
num_results_per_page integer No Number of facet options per page in paginated response. Default value is 100.

Batch update or create facet options configs

To update or create multiple facet options, use the PATCH method. If a facet option config with provided value already exists it is updated partially, otherwise it is created.

Batch update or create facets options configs

curl -X PATCH \
  -H "Content-Type: application/json" \
  -u "[your token]" \
  -d '[{"value": "nature_valley", "display_name": "New display name"}, {"display_name": "McCormick Organics", "value": "mccormicks-organics", "position": 2, "hidden": false}]'
  "https://ac.cnstrc.com/v1/facets/<facet_group_name>/options?key=[your API key]&section=[your section]"

Response

[
    {
        "value": "nature_valley",
        "display_name": "New display name",
        "position": 1,
        "data": null,
        "hidden": false,
    },
    {
        "value": "mccormicks-organics",
        "display_name": "McCormick Organics",
        "position": 2,
        "data": null,
        "hidden": false,
    }
]

HTTP request

PATCH https://ac.cnstrc.com/v1/facets/<facet_group_name>/options?key=[your API key]&section=[your section]

URL Parameters

Attribute Type Required? Description
section string No The section in which your facet is defined. Typically, this will be Products.

JSON Parameters

Batch update endpoint expects a list of item updates. Each item parameters can be any subset of those listed in the Create a facet option configuration section, except that value parameter is required (to identify which facet options config to update).

Get a single facet option config

To retrieve the configuration of a single facet option, use the GET method.

Get facet option

curl -X GET \
  -H "Content-Type: application/json" \
  -u "[your token]"
  "https://ac.cnstrc.com/v1/facets/<facet_group_name>/options/<facet_option_value>?key=[your API key]&section=[your section]"

Response

{
    "value": "nature_valley",
    "display_name": "Nature Valley",
    "position": 1,
    "data": null,
    "hidden": false,
}

HTTP request

GET https://ac.cnstrc.com/v1/facets/<facet_group_name>/options/<facet_option_value>?key=[your API key]&section=[your section]

URL Parameters

Attribute Type Required? Description
section string No The section in which your facet is defined. Typically, this will be Products.

Update facet option (total)

To update the configuration of a facet option completely (replace), use the PUT method.

WARNING: This will overwrite all other configurations you may have defined for the facet option, resetting them to their defaults.

Replace facet option's configurations

curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{"value": "nature_valley", "display_name": "Nature Valley", "position": 1, "data": null, "hidden": false}' \
  -u "[your token]"
  "https://ac.cnstrc.com/v1/facets/<facet_group_name>/options/<facet_option_value>?key=[your API key]&section=[your section]"

Response

{
    "value": "nature_valley",
    "display_name": "Nature Valley",
    "position": 1,
    "data": null,
    "hidden": false,
}

HTTP request

PUT https://ac.cnstrc.com/v1/facets/<facet_group_name>/options/<facet_option_value>?key=[your API key]&section=[your section]

URL Parameters

Attribute Type Required? Description
section string No The section in which your facet is defined. Typically, this will be Products.

JSON Parameters

The JSON parameters are the same as those in the Create a facet option configuration section.

Update facet option (partial)

To update the configuration of a facet option partially (change only some attributes), use the PATCH method.

Modify facet option

curl -X PATCH \
  -H "Content-Type: application/json" \
  -d '{"display_name": "Nature Valley"}' \
  -u "[your token]"
  "https://ac.cnstrc.com/v1/facets/<facet_group_name>?key=[your API key]&section=[your section]"

Response

{
    "value": "nature_valley",
    "display_name": "Nature Valley",
    "position": 1,
    "data": null,
    "hidden": false,
}

HTTP request

PATCH https://ac.cnstrc.com/v1/facets/<facet_group_name>/options/<facet_option_value>?key=[your API key]&section=[your section]

URL Parameters

Attribute Type Required? Description
section string No The section in which your facet is defined. Typically, this will be Products.

JSON Parameters

The JSON parameters can be any subset of those listed in the Create a facet configuration section.

Delete a facet option config

To delete the configuration of a facet option from the facet, use the DELETE method.

Only do this if you want all configuration options for the facet option to go back to their default values.

Delete a facet option configuration

curl -X DELETE \
  -H "Content-Type: application/json" \
  -u "[your token]"
  "https://ac.cnstrc.com/v1/facets/<facet_group_name>/options/<facet_option_value>?key=[your API key]&section=[your section]"

Response

{
    "value": "nature_valley",
    "display_name": "Nature Valley",
    "position": 1,
    "data": null,
    "hidden": false,
}

HTTP request

DELETE https://ac.cnstrc.com/v1/facets/<facet_group_name>/options/<facet_option_value>?key=[your API key]&section=[your section]

URL Parameters

Attribute Type Required? Description
section string No The section in which your facet is defined. Typically, this will be Products.

Errors

The Constructor.io API uses the following error codes across all requests:

Error Code Meaning
400 Bad Request -- Your request is invalid
401 Unauthorized -- Your API token is wrong
403 Forbidden -- You are not authorized to access the requested resource
404 Not Found -- The specified resource could not be found
405 Method Not Allowed -- You tried to access a resource with an invalid method
429 Too Many Requests -- You're making too many requests
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarially offline for maintanance. Please try again later.

Compliance

CCPA

CCPA (California Consumer Privacy Act) grants California consumers robust data privacy rights and control over their personal information, including the right to know, the right to delete, and the right to opt-out of the sale of personal information that businesses collect, as well as additional protections for minors.

Retrieve all CCPA requests

curl -X GET -H "Content-Type: application/json" \
  -u"[your token]:" "https://ac.cnstrc.com/v1/tasks?key=[your API key]&type=user_data_request"

HTTP Request

GET https://ac.cnstrc.com/v1/tasks?key=[your API key]&type=user_data_request

Response format

{
    "total_count": 1,
    "tasks": [
        {
            "id": 0,
            "type": "user_data_request",
            "status": "QUEUED",
            "submission_time": "2020-04-24T15:06:27Z",
            "last_update": null,
            "action": "request_report",
            "user_id": "user1"
        }
    ],
    "status_counts": {
        "QUEUED": 1,
        "DONE": 0,
        "IN_PROGRESS": 0,
        "FAILED": 0,
    }
}

Query Parameters

Parameter Required? Description
key Yes The key of the index you'd like to to retrieve tasks for.

Retrieve CCPA request by ID

See Retrieve By Specific Task ID for more info.

Submit a CCPA request action

curl -X POST -H "Content-Type: application/json" \
  -d '{"user_id": "user1", "action": "delete", "type": "user_data_request"}' \
  -u"[your token]:"
  "https://ac.cnstrc.com/v1/tasks?key=[your API key]

HTTP Request

POST https://ac.cnstrc.com/v1/tasks?key=[your API key]

Response format

{
    "id": 0,
    "status": "QUEUED",
    "submission_time": "2020-04-24T15:06:27Z",
    "last_update": null,
}

Query Parameters

Parameter Required? Description
key Yes The key of the index you'd like to to retrieve tasks for.

JSON Parameters

Attribute Type Required? Description
user_id string Yes The user_id of the user you would like to request an action for.
action string Yes request_report or delete to specify the action for this request.
type string Yes Specifies the type of task. user_data_request for user data requests.