NAV
shell javascript ruby python php perl java csharp

Introduction

Welcome to the Constructor.io REST API.

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
gem install constructorio
pip install constructor-io
composer require constructor-io/constructor-io
cpanm WebService::ConstructorIO
/*
If using Maven, include in your pom.xml:

<dependency>
  <groupId>com.cnstrc.client</groupId>
  <artifactId>constructorio-client</artifactId>
  <version>0.0.1</version>
</dependency>

If using Ivy, include this:
<dependency org="com.cnstrc.client" name="constructorio-client" rev="0.0.1" />

If using Gradle, include this:
compile 'com.cnstrc.client:constructorio-client:0.0.1'
*/
/*
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');
var constructorio = new ConstructorIO({
  apiToken: "[your API token]",
  autocompleteKey: "[your autocomplete key]",
});

require('constructorio')
ConstructorIO.configure do |config|
  config.api_token = "[your API token]"
  config.autocomplete_key = "[your autocomplete key]"
end
constructorio = ConstructorIO::Client.new
from constructor_io import ConstructorIO
constructor_instance = ConstructorIO(
    api_token="[your api token]",
    autocomplete_key="[your autocomplete key]")
<?php
// if using Composer autoloading:
// require_once "vendor/autoload.php";
use ConstructorIO\ConstructorIO;
$constructorio = new ConstructorIO("[your API token]","[your autocomplete key]");
use WebService::ConstructorIO;
my $constructorio = new WebService::ConstructorIO->new(
  api_token => "[your API token]",
  autocomplete_key => "[your autocomplete key]"
);
import com.cnstrc.client.ConstructorIO;
ConstructorIO constructorClient = new ConstructorIO("[your API token]", "[your autocomplete key]", true, null);
using ConstructorIO;
var ConstructorIOAPI = new ConstructorIOAPI("[your API token]", "[your autocomplete 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?autocomplete_key=[your autocomplete 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 = $constructor->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?autocomplete_key=[your autocomplete 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"} ],
    "autocomplete_section":"Search Suggestions"}' \
  -u"[your token]:" "https://ac.cnstrc.com/v1/batch_items?autocomplete_key=[your autocomplete key]"

# products
curl -X POST -H "Content-Type: application/json" \
  -d '{
        "autocomplete_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?autocomplete_key=[your autocomplete key]"
// search suggestions
constructorio.add_batch(
  {
    autocomplete_section: "Search Suggestions",
    items: [
      { item_name: "Golden Retriever" },
      { item_name: "Poodle" }
    ]
  },
  function(error, response) {
    if (error) {
      console.log(error);
    }
  }
);

// products
constructorio.add_batch(
  {
    autocomplete_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" ]
      }
    ]
  },
  function(error, response) {
    if (error) {
      console.log(error);
    }
  }
);
# search suggestions
response = constructorio.add_batch(
  {
    autocomplete_section: "Search Suggestions",
    items: [
      { item_name: "Golden Retriever" },
      { item_name: "Poodle" }
    ],
  }
)

# products
response = constructorio.add_batch(
  {
    autocomplete_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_batch(
  autocomplete_section="Search Suggestions",
  items=[
    {"item_name": "Golden Retriever"},
    {"item_name": "Poodle"}
  ]
)

# products
response = constructor_instance.add_batch(
    autocomplete_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 = $constructor->addBatch(
  array("Golden Retriever", "Poodle"),
  "Search Suggestions"
);

// products
$response = $constructor->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(
  autocomplete_section => "Search Suggestions",
  items => [
    { item_name => "Golden Retriever" },
    { item_name => "Poodle" }
  ]
);

# products
my $response = $constructorio->add_batch(
  autocomplete_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
ConstructorItem[] items = {
  new ConstructorItem("Golden Retriever"),
  new ConstructorItem("Poodle")
}
boolean success = constructorio.addBatch(items, "Search Suggestions")

// products
HashMap<String, Object> item1params = new HashMap<String, Object>();
item1params.put("url", "http://www.mydogs.com/labradoodle");
item1params.put("image_url", "https://images.mydogs.com/labradoodle.jpg");
item1paramas.put("description", "A crossbreed dog created by crossing the Labrador Retriever and the Poodle");
ConstructorItem item1 = new ConstructorItem("Labradoodle", item1params)
    .setSuggestedScore(360)
    .setKeywords("poodle","labrador","retriever");

HashMap<String, Object> item2params = new HashMap<String, Object>();
item2params.put("url", "http://www.mydogs.com/australian_shepherd");
item2params.put("image_url", "https://images.mydogs.com/australian_shepherd.jpg");
item2paramas.put("description", "A medium-sized breed of dog developed on ranches in the Western United States");
ConstructorItem item2 = new ConstructorItem("Australian Shepherd", item2params)
    .setSuggestedScore(130)
    .setKeywords("aussie")

ConstructorItem[] items = { item1, item2 };
boolean success = constructorio.addBatch(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 autocomplete 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 autocomplete 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 autocomplete_section parameter.

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

HTTP Request

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

JSON Parameters

Parameter Required? Description
items Yes A list of items with the same attributes as defined in the Add an Item resource
autocomplete_section Yes Your autocomplete suggestions 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"} ],
    "autocomplete_section":"Search Suggestions"}' \
  -u"[your token]:" "https://ac.cnstrc.com/v1/batch_items?force=1&autocomplete_key=[your autocomplete key]"

# products
curl -X PUT -H "Content-Type: application/json" \
  -d '{
        "autocomplete_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&autocomplete_key=[your autocomplete key]"
// search suggestions
constructorio.add_or_update_batch(
  {
    autocomplete_section: "Search Suggestions",
    items: [
      { item_name: "Golden Retriever" },
      { item_name: "Poodle" }
    ]
  },
  function(error, response) {
    if (error) {
      console.log(error);
    }
  }
);

// products
constructorio.add_or_update_batch(
  {
    autocomplete_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" ]
      }
    ]
  },
  function(error, response) {
    if (error) {
      console.log(error);
    }
  }
);
# search suggestions
response = constructorio.add_or_update_batch(
  {
    autocomplete_section: "Search Suggestions",
    items: [
      { item_name: "Golden Retriever" },
      { item_name: "Poodle" }
    ],
  }
)

# products
response = constructorio.add_or_update_batch(
  {
    autocomplete_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(
  autocomplete_section="Search Suggestions",
  items=[
    {"item_name": "Golden Retriever"},
    {"item_name": "Poodle"}
  ]
)

# products
response = constructor_instance.add_or_update_batch(
    autocomplete_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 = $constructor->addOrUpdateBatch(
  array("Golden Retriever", "Poodle"),
  "Search Suggestions"
);

// products
$response = $constructor->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(
  autocomplete_section => "Search Suggestions",
  items => [
    { item_name => "Golden Retriever" },
    { item_name => "Poodle" }
  ]
);

# products
my $response = $constructorio->add_or_update_batch(
  autocomplete_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
ConstructorItem[] items = {
  new ConstructorItem("Golden Retriever"),
  new ConstructorItem("Poodle")
}
boolean success = constructorio.addOrUpdateBatch(items, "Search Suggestions")

// products
HashMap<String, Object> item1params = new HashMap<String, Object>();
item1params.put("url", "http://www.mydogs.com/labradoodle");
item1params.put("image_url", "https://images.mydogs.com/labradoodle.jpg");
item1paramas.put("description", "A crossbreed dog created by crossing the Labrador Retriever and the Poodle");
ConstructorItem item1 = new ConstructorItem("Labradoodle", item1params)
    .setSuggestedScore(360)
    .setKeywords("poodle","labrador","retriever");

HashMap<String, Object> item2params = new HashMap<String, Object>();
item2params.put("url", "http://www.mydogs.com/australian_shepherd");
item2params.put("image_url", "https://images.mydogs.com/australian_shepherd.jpg");
item2paramas.put("description", "A medium-sized breed of dog developed on ranches in the Western United States");
ConstructorItem item2 = new ConstructorItem("Australian Shepherd", item2params)
    .setSuggestedScore(130)
    .setKeywords("aussie")

ConstructorItem[] items = { item1, item2 };
boolean success = constructorio.addOrUpdateBatch(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 autocomplete 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 autocomplete 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 autocomplete_section are required and all other parameters are optional.

We determine whether items already exist based on the item_name and autocomplete_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&autocomplete_key=[your autocomplete key]

JSON Parameters

Parameter Required? Description
autocomplete_section Yes Your autocomplete suggestions 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 Remove Items

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

response = constructorio.remove_batch(
  {
    autocomplete_section: "Products",
    items: [
      { item_name: "Labradoodle" },
      { id: "D26" }
    ],
  }
);
response = constructor_instance.remove_batch(
  autocomplete_section="Products",
  items=[
    {"item_name": "Labradoodle"},
    {"id": "D26"}
  ]
)
<?php
$items = array(
  array("item_name" => "Labradoodle"),
  array("id" => "D26")
);
$response = $constructor->removeBatch($items, "Products");
# This method is not currently supported in our perl client.
ConstructorItem[] items = {
  new ConstructorItem("Labradoodle"),
  new ConstructorItem("Poodle")
}
boolean success = constructorio.removeBatch(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 autocomplete 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. If your autocomplete has multiple sections (i.e. products, categories, and search suggestions), you must specify the name of the autocomplete 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?autocomplete_key=[your autocomplete key]

JSON Parameters

Parameter Required? Description
items Yes A list of items with the same attributes as defined in the Remove an Item resource.
autocomplete_section Yes Your autocomplete suggestions 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",
       "autocomplete_section": "Search Suggestions"}' \
  -u"[your token]:" "https://ac.cnstrc.com/v1/item?autocomplete_key=[your autocomplete key]"

# product
curl -X POST -H "Content-Type: application/json" \
  -d '{"item_name": "Labradoodle",
       "autocomplete_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": {
           "Color": "Brown",
           "Personality": ["Friendly", "Playful"],
       }
       "metadata": { "animal": "dog" },
       "group_ids": [ "23", "45" ]}'\
  -u"[your token]:" "https://ac.cnstrc.com/v1/item?autocomplete_key=[your autocomplete key]"
// search suggestion
constructorio.add(
  {
    item_name: "Golden Retriever",
    autocomplete_section: "Search Suggestions"
  },
  function(error, response) {
    if (error) {
      console.log(error);
    }
  }
);

// product
constructorio.add(
  {
    item_name: "Labradoodle",
    autocomplete_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: {
        "Color": "Brown",
        "Personality": ["Friendly", "Playful"],
    },
    metadata: { "animal": "dog" },
    group_ids: [ "23", "45" ]
  },
  function(error, response) {
    if (error) {
      console.log(error);
    }
  }
);
# search suggestion
response = constructorio.add(
  {
    item_name: "Golden Retriever",
    autocomplete_section: "Search Suggestions"
  }
);

# product
response = constructorio.add(
  {
    item_name: "Labradoodle",
    autocomplete_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: {
        "Color": "Brown",
        "Personality": ["Friendly", "Playful"]
    },
    metadata: { "animal": "dog" },
    group_ids: [ "23", "45" ]
  }
);
# search suggestion
response = constructor_instance.add(
    item_name="Golden Retriever",
    autocomplete_section="Search Suggestions")

# product
response = constructor_instance.add(
    item_name="Labradoodle",
    autocomplete_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={
        "Color": "Brown",
        "Personality": ["Friendly", "Playful"]
    },
    metadata={ "animal": "dog" },
    group_ids=["23", "45"])
<?php
// search suggestion
$response = $constructorio->add(
  "Golden Retriever", // item name
  "Search Suggestions" // autocomplete section name
);

// product
$response = $constructorio->add(
  "Labradoodle", // item name
  "Products", // autocomplete 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",
  autocomplete_section => "Search Suggestions"
);

# product
my $response = $constructorio->add(
  item_name => "Labradoodle",
  autocomplete_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 => {
      "Color" => "Brown",
      "Personality" => ["Friendly", "Playful"]
  },
  metadata => { "animal" => "dog" },
  group_ids => ["23", "45"]
);
// search suggestion
boolean success = constructorio.add("Golden Retriever", "Search Suggestions");
// "Golden Retriever" is an item name
// "Search Suggestions" is an autocomplete section name

// product
HashMap<String, Object> params = new HashMap<String, Object>();
params.put("suggested_score", 360);
params.put("url", "http://www.mydogs.com/labradoodle");
params.put("image_url", "https://images.mydogs.com/labradoodle.jpg");
params.put("description", "A crossbreed dog created by crossing the Labrador Retriever and the Poodle");

ConstructorItem item = new ConstructorItem("Labradoodle", params);
item.setKeywords("poodle","labrador","retriever");

boolean success = constructorio.add(
  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 autocomplete 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 autocomplete 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 autocomplete_section parameter.

HTTP Request

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

JSON Parameters

Parameter Required? Description
item_name Yes The name of the item, as it will appear in the autocomplete suggestions
autocomplete_section Yes Your autocomplete suggestions 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 iteslf.
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 a /search and /autocomplete 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.
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 the /search and /autocomplete calls

Add or Update an Item

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

# product
curl -X PUT -H "Content-Type: application/json" \
  -d '{"item_name": "Labradoodle",
       "autocomplete_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?autocomplete_key=[your autocomplete key]"
// search suggestion
constructorio.add_or_update(
  {
    item_name: "Golden Retriever",
    autocomplete_section: "Search Suggestions"
  },
  function(error, response) {
    if (error) {
      console.log(error);
    }
  }
);

// product
constructorio.add_or_update(
  {
    item_name: "Labradoodle",
    autocomplete_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" ]
  },
  function(error, response) {
    if (error) {
      console.log(error);
    }
  }
);
# search suggestion
response = constructorio.add_or_update(
  {
    item_name: "Golden Retriever",
    autocomplete_section: "Search Suggestions"
  }
);

# product
response = constructorio.add_or_update(
  {
    item_name: "Labradoodle",
    autocomplete_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",
    autocomplete_section="Search Suggestions")

# product
response = constructor_instance.add_or_update(
    item_name="Labradoodle",
    autocomplete_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" // autocomplete section name
);

// product
$response = $constructorio->addOrUpdate(
  "Labradoodle", // item name
  "Products", // autocomplete 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",
  autocomplete_section => "Search Suggestions"
);

# product
my $response = $constructorio->add_or_update(
  item_name => "Labradoodle",
  autocomplete_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
boolean success = constructorio.addOrUpdate("Golden Retriever", "Search Suggestions");
// "Golden Retriever" is an item name
// "Search Suggestions" is an autocomplete section name

// product
HashMap<String, Object> params = new HashMap<String, Object>();
params.put("suggested_score", 360);
params.put("url", "http://www.mydogs.com/labradoodle");
params.put("image_url", "https://images.mydogs.com/labradoodle.jpg");
params.put("description", "A crossbreed dog created by crossing the Labrador Retriever and the Poodle");

ConstructorItem item = new ConstructorItem("Labradoodle", params);
item.setKeywords("poodle","labrador","retriever");

boolean success = constructorio.addOrUpdate(
  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 autocomplete 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 autocomplete index, use the PUT /item call, with ?force=1. Options are the same as for the standard Add an Item call: item_name and autocomplete_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 autocomplete_section.

HTTP Request

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

JSON Parameters

Parameter Required? Description
item_name Yes The name of the item, as it will appear in the autocomplete suggestions
autocomplete_section Yes Your autocomplete suggestions 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 iteslf.
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.
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 autocomplete key and section, paginated by num_results_per_page. If item id is specified, returns the item with that item id.

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

curl -X GET -H "Content-Type: application/json" \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/item/123?autocomplete_key=[your autocomplete 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?autocomplete_key=[your autocomplete key]

GET https://ac.cnstrc.com/v1/item/[item id]?autocomplete_key=[your autocomplete key]

Response format

{
  "items": [{
    "name": "[item_name]",
    "score": "[item_score]",
    "metadata_json": "[item_metadata_json]",
    "id": "[item_id]"
  }, {
    "name": "[another_item_name]",
    "score": "[another_item_score]",
    "metadata_json": "[another_item_metadata_json]",
    "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
autocomplete_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 items to return. Defaults to 20.
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",
       "autocomplete_section": "Search Suggestions"}' \
  -u "[your token]:" "https://ac.cnstrc.com/v1/item?autocomplete_key=[your autocomplete key]"

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

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

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

# remove by ID
my $response = $constructorio->remove(
  id => "D26",
  autocomplete_section => "Search Suggestions"
);
// remove by name
boolean success = constructorio.remove(
  "Golden Retriever", // item name
  "Search Suggestions" // autocomplete section
);
// 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 autocomplete 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. If your autocomplete has multiple sections (i.e. products, categories, and search suggestions), you must specify the name of the autocomplete section from which you’re removing an item.

HTTP Request

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

JSON Parameters

Parameter Required? Description
item_name Yes The name of the item, as it will appear in the autocomplete suggestions
autocomplete_section Yes Your autocomplete suggestions 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 No An arbitrary ID you optionally specified when adding the item. If passed in, you don’t need to pass in item_name.

Modify an Item

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

# product
curl -X PUT -H "Content-Type: application/json" \
  -d '{"item_name": "Labradoodle",
       "new_item_name": "Breed: Labradoodle",
       "autocomplete_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?autocomplete_key=[your autocomplete key]"
// search suggestion
constructorio.modify(
  {
    item_name: "Golden Retriever",
    new_item_name: "Breed: Golden Retriever",
    autocomplete_section: "Search Suggestions"
  },
  function(error, response) {
    if (error) {
      console.log(error);
    }
  }
);

// product
constructorio.modify(
  {
    item_name: "Labradoodle",
    new_item_name: "Breed: Labradoodle",
    autocomplete_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" }
  },
  function(error, response) {
    if (error) {
      console.log(error);
    }
  }
);
# search suggestion
response = constructorio.modify(
  {
    item_name: "Golden Retriever",
    new_item_name: "Breed: Golden Retriever",
    autocomplete_section: "Search Suggestions"
  }
);

# product
response = constructorio.modify(
  {
    item_name: "Labradoodle",
    new_item_name: "Breed: Labradoodle",
    autocomplete_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",
    autocomplete_section="Search Suggestions")

# product
response = constructor_instance.modify(
    item_name="Labradoodle",
    new_item_name="Breed: Labradoodle",
    autocomplete_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" // autocomplete section name
);

// product
$response = $constructorio->modify(
  "Labradoodle", // item name
  "Breed: Labradoodle", // new item name
  "Products", // autocomplete 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",
  autocomplete_section => "Search Suggestions"
);

# product
my $response = $constructorio->modify(
  item_name => "Labradoodle",
  new_item_name => "Breed: Labradoodle",
  autocomplete_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"]
);
boolean success = constructorio.modify("power drill", "super power drill", "Search Suggestions", paramMap);
// power drill is an item name
// super power drill is an item name
// Search Suggestions is an autocomplete section name
// paramMap is a Map<String, Object> you filled beforehand with the other properties you want to modify. Optional.

// search suggestion
boolean success = constructorio.modify(
  "Golden Retriever", // item name
  "Breed: Golden Retriever", // new item name
  "Search Suggestions" // autocomplete section
);

// product
HashMap<String, Object> params = new HashMap<String, Object>();
params.put("suggested_score", 360);
params.put("url", "http://www.mydogs.com/labradoodle");
params.put("image_url", "https://images.mydogs.com/labradoodle.jpg");
params.put("description", "A crossbreed dog created by crossing the Labrador Retriever and the Poodle");

ConstructorItem item = new ConstructorItem("Breed: Labradoodle", params);
item.setKeywords("poodle","labrador","retriever");

boolean success = constructorio.modify(
  "Labradoodle", // old item name
  item, // item with new name
  "Products"
);
// 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 autocomplete 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 autocomplete 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 autocomplete_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?autocomplete_key=[your autocomplete key]

JSON Parameters

Parameter Required? Description
item_name Yes The name of the item, as it currently appears in the autocomplete suggestions
new_item_name Yes The name of the item, as it you’d like it to appear in the autocomplete suggestions
autocomplete_section Yes Your autocomplete suggestions 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 iteslf.
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.
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 = $constructor->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.

Item Groups

Introduction

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 and parent_id (the id of the parent item group if any).

Add item group

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

Response

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

HTTP request

PUT https://ac.cnstrc.com/v1/item_groups/[item_group_id]?autocomplete_key=[your autocomplete 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.

Update item group

An item group can be updated by passing its id, name and parent_id (the id of the parent item group if any). When only one of name and parent_id 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>"}' \
  -u "[your token]:" \
  "https://ac.cnstrc.com/v1/item_groups/<item_group_id>?autocomplete_key=[your autocomplete key]"

Response

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

HTTP request

PUT https://ac.cnstrc.com/v1/item_groups/[item_group_id]?autocomplete_key=[your autocomplete 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.

Add multiple item groups

Item groups can be added to an autocomplete 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.
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>",
          },
          {
            "id": "<group_id_2>",
            "name": "<group_name_2>"
          }
        ]
      }' \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/item_groups?autocomplete_key=[your autocomplete 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>"
              }
            ]
          }
        ]
      }' \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/item_groups?autocomplete_key=[your autocomplete 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?autocomplete_key=[your autocomplete 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?autocomplete_key=[your autocomplete 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?autocomplete_key=[your autocomplete 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?autocomplete_key=[your autocomplete key]

JSON parameters

Parameter Required? Description
item_groups Yes A list of item groups

Get item groups

Retrieves item groups for a given autocomplete 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?autocomplete_key=[your autocomplete key]"

curl -X GET -H "Content-Type: application/json" \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/item_groups/123?autocomplete_key=[your autocomplete 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?autocomplete_key=[your autocomplete key]

GET https://ac.cnstrc.com/v1/item_groups/[group id]?autocomplete_key=[your autocomplete 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?autocomplete_key=[your autocomplete key]"

Response example #1

{
  "item_groups": [{
    "id": "1",
    "name": "group 1",
    "children": [{
      "id": "3",
      "name": "group 3",
      "children": []
    }]
  }, {
    "id": "2",
    "name": "group 2",
    "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?autocomplete_key=[your autocomplete key]"

Response example #2

{
  "item_groups": [{
    "id": "2",
    "name": "group 2",
    "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
autocomplete_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?autocomplete_key=[your autocomplete 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 autocomplete key.

HTTP request

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

Autocomplete

Autocomplete Queries

curl -X GET -H "Content-Type: application/json" \
"https://ac.cnstrc.com/autocomplete/[query]?autocomplete_key=[your autocomplete key]" \
"&filters[group_id]=123"

# for the demo list of dog breeds on our homepage
curl -X GET -H "Content-Type: application/json" \
"https://ac.cnstrc.com/autocomplete/australian?autocomplete_key=pAFl6rReRSI0uXckcxZS&num_results_Search%20Suggestions=3"
// 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.
# 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.
// 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.

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]?autocomplete_key=[your autocomplete key], replacing [query] with the query you’d like to make, and [your autocomplete key] with your autocomplete 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]?autocomplete_key=[your autocomplete key]

Parameters

Parameter Required? Description
query Yes The URL-encoded autocomplete query.
autocomplete_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.

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

The above command returns a 200 Success response on success.

HTTP Request

GET https://ac.cnstrc.com/search/[query]?key=[your key]&filters[group_id]=123&filters[Color]=Brown&filters[Color]=White&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.
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.

Search Responses

Constructor.io’s search engine returns easy-to-process JSON responses.

The response format is as follows:

Response structure overview

{
    "response": {
        "facets": [
            ...
        ],
        "groups": [
            ...
        ],
        "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, results

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

The three groups are described below:

Responses: Result structure

{
    "response": {
        "facets": [
            ...
        ],
        "groups": [
            ...
        ],
        "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"
            },
            "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.

Responses: 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

{
    "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": []
            },
        ],
        "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

{
    "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": []
            },
        ],
        "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.

Responses: Facets structure

{
    "response": {
        "facets": [
            {
                "name": "Brand",
                "options": [
                        {
                            "value": "Natural Balance",
                            "count": 8
                        },
                        {
                            "value": "WholeHearted",
                            "count": 10
                        }
                ]
            },
            {
                "name": "Rating",
                "options": [
                        {
                                "value": 5,
                                "count": 13,
                        },
                        {
                                "value": 4,
                                "count": 5
                        }
                ]
            }
        ],
        "groups": [
            ...
        ],
        "results": [
            ...
        ],
        "total_num_results": 10
    }
}

Facets fields

field_name Always present? Description
name Yes The name of the facet.
options Yes The list of possible facet values matching this search, along with their respective match counts.

Behavioral Data

To improve your autocomplete suggestions, you can send three types of behavioral data to Constructor.io: search, click_through, and conversion.

curl -X POST -H "Content-Type: application/json" -d '{"term":"xyz", "num_results":302}' \
  -u "[your token]:" "https://ac.cnstrc.com/v1/search?autocomplete_key=[your autocomplete key]"
constructorio.track_search({
  term: "xyz",
  num_results: "302"
});
response = constructorio.track_search({
  term: "xyz",
  num_results: "302"
});
response = constructor_instance.track_search(
    term="xyz",
    num_results=302)
<?php
$response = $constructor->trackSearch(
  "xyz", // term name
  array("num_results" => 302) // array of properties of the search
);
my $response = $constructorio->track_search(
  term => "xyz",
  num_results => 302
);
boolean success = constructorio.trackSearch("xyz", 302);
// "xyz" is the term that was searched
// 302 is the number of results
bool success = ConstructorIOAPI.TrackSearch("xyz");
// "xyz" is the term that was searched

The search resource should be called whenever a search is performed on your site, together with the search term and number of results (num_results).

HTTP Request

POST https://ac.cnstrc.com/v1/search?autocomplete_key=[your autocomplete key]

JSON Parameters

Parameter Required? Description
term Yes The search term the user entered in the search box
num_results No The number of total results returned in the search

Track a click-through

curl -X POST -H "Content-Type: application/json" -d '{"term":"xyz", "item":"Alphabet soup", "autocomplete_section":"Search Suggestions"}' \
  -u "[your token]:" "https://ac.cnstrc.com/v1/click_through?autocomplete_key=[your autocomplete key]"
constructorio.track_click_through({
  term: "xyz",
  item: "Alphabet soup",
  autocomplete_section: "Search Suggestions"
});
response = constructorio.track_click_through({
  term: "xyz",
  item: "Alphabet soup",
  autocomplete_section: "Search Suggestions"
});
response = constructor_instance.track_click_through(
    term="xyz",
    autocomplete_section="Search Suggestions")
<?php
$response = $constructor.trackClickThrough(
  "xyz", // term name
  "Search Suggestions", // autocomplete section name
  array("item" => "power drill") // array of properties of the click through
);
my $response = $constructorio->track_click_through(
  term => "xyz",
  item => "Alphabet soup",
  autocomplete_section => "Search Suggestions"
);
boolean success = constructorio.trackClickThrough("xyz", "alphabet soup", "Search Suggestions");
// xyz is the term
// alphabet soup is the item
// Search Suggestions is the autocomplete section
bool success = ConstructorIOAPI.TrackClickThrough("xyz", "Search Suggestions");
// xyz is the term
// Search Suggestions is the autocomplete section

The click_through resource should be called when a user clicks on a search result (this can often be done from the product detail page). Pass in the search term and, optionally, the item clicked on so we can learn which items are receiving clicks from which terms and increase their ranking in the autocomplete index. Beacuse your autocomplete can have multiple sections, you must also pass in the autocomplete_section parameter with the appropriate section name.

HTTP Request

POST https://ac.cnstrc.com/v1/click_through?autocomplete_key=[your autocomplete key]

JSON Parameters

Parameter Required? Description
term Yes The search term the user entered in the search box
autocomplete_section Yes Your autocomplete suggestions 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.
item No The autocomplete item that the user clicked on
item_id No The id of the item that the user clicked (use ​either​ this or item to designate the item clicked)

Track a conversion

curl -X POST -H "Content-Type: application/json" -d '{"term":"xyz", "autocomplete_section":"Search Suggestions", "item":"Alphabet soup"}' \
  -u "[your token]:" "https://ac.cnstrc.com/v1/conversion?autocomplete_key=[your autocomplete key]"
constructorio.track_conversion({
  term: "xyz",
  autocomplete_section: "Search Suggestions",
  item: "Alphabet soup"
});
response = constructorio.track_conversion({
  term: "xyz",
  autocomplete_section: "Search Suggestions",
  item: "Alphabet soup"
});
response = constructor_instance.track_conversion(
    term="xyz",
    autocomplete_section="Search Suggestions",
    item="Alphabet Soup")
<?php
$response = $constructor.trackConversion(
  "xyz", // term name
  "Search Suggestions", // autocomplete section name
  array("item" => "power drill") // array of properties of the conversion
);
my $response = $constructorio->track_conversion(
  term => "xyz",
  autocomplete_section => "Search Suggestions",
  item => "Alhabet Soup"
);
boolean success = constructorio.trackConversion("xyz", "Search Suggestions");
// xyz is the term
// Search Suggestions is the autocomplete section
bool success = ConstructorIOAPI.TrackConversion("xyz", "Search Suggestions");
// xyz is the term
// Search Suggestions is the autocomplete section

The conversion resource should be called when a user purchases a product (or successfully performs another action important to your site). Pass in the search term so we can learn which items are receiving conversions and increase their ranking in the autocomplete index. You can also pass in an optional item parameter to indicate which item the customer purchased. Because your autocomplete can have multiple sections, you must also pass in the autocomplete_section parameter with the appropriate section name.

HTTP Request

POST https://ac.cnstrc.com/v1/conversion?autocomplete_key=[your autocomplete key]

JSON Parameters

Parameter Required? Description
term Yes The search term the user entered in the search box
autocomplete_section Yes Your autocomplete suggestions 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.
item No The item that the user purchased
item_id No The id of the item that the user purchased (use ​either​ this or item to designate the item purchased)
revenue No The purchase amount in cents (that is, the purchase amount * 100)

Via Javascript

Conversions can also be tracked via Javascript, like so:

<script type="text/javascript" src="//cnstrc.com/js/ac.js"></script> <script>
window['constructorio'] = window['constructorio'] || [];
window['constructorio'].push(["trackEvent", "purchase", {
  "autocomplete_key": "[your autocomplete key]",
  "revenue": [the purchase amount in cents],
  "term": "[the search term the user entered in the search box]",
  "item": "[the item that the user purchased]",
  "autocomplete_section": "[the autocomplete section]"
}]);
</script>

Note that if term, item, and autocomplete_section are ommitted, the Javascript client will populate them with its own tracking information.

Blacklist Terms

Introduction

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?autocomplete_key=[your autocomplete 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?autocomplete_key=[your autocomplete 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?autocomplete_key=[your autocomplete 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?autocomplete_key=[your autocomplete 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?autocomplete_key=[your autocomplete 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?autocomplete_key=[your autocomplete 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?autocomplete_key=[your autocomplete 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?autocomplete_key=[your autocomplete key]

Searchandizing

Constructor.io’s query searchandizing feature allows customers to assign particular products to different positions for a query.

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?autocomplete_key=[your autocomplete 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 the item already exists.

HTTP Request

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

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.
id The id for the item you’d like added to the position and query in question.

JSON Parameters

Parameter Required? Description
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 autocomplete 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 autocomplete 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.
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?autocomplete_key=[your autocomplete key]"

curl -X GET -H "Content-Type: application/json" \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/searchandized_queries/leashes?autocomplete_key=[your autocomplete 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/searchandized_queries?key=[your autocomplete key]

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

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?autocomplete_key=[your autocomplete key]"

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

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?autocomplete_key=[your autocomplete 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 Requests

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

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

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

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.

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.