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
/*
 * Please follow the directions at Jitpack.io to add the client to your project
 * https://jitpack.io/#Constructor-io/constructorio-java
 */
/*
Run in the Package Manager Console:

Install-Package constructor.io

Or, if using nuget on the command line:

nuget install constructor.io
*/

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

Authentication

API Token

To authorize, use this code:

# with curl, there's no need to authorize separately -- just pass your API token in with every call
curl -X POST -H "Content-Type: application/json" \
  -d '{"item_name":"xyz","keywords":["k1","k2"]}' \
  -u "[your API token]:" https://ac.cnstrc.com/v1/item
var ConstructorIO = require('constructorio');
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 io.constructor.client.*;

String apiToken = "[your API token]";
String apiKey = "[your API key]";
ConstructorIO constructorio = new ConstructorIO(apiToken, apiKey, true, null);
using ConstructorIO;
var ConstructorIOAPI = new ConstructorIOAPI("[your API token]", "[your 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"]
    }
  ]
)
ConstructorItem item1 = new ConstructorItem("Labradoodle");
item1.setSuggestedScore(360);
item1.setUrl("http://www.mydogs.com/labradoodle");
item1.setImageUrl("https://images.mydogs.com/labradoodle.jpg");
item1.setDescription("A crossbreed dog created by crossing the Labrador Retriever and the Poodle");
item1.setKeywords(new ArrayList<>(Arrays.asList("poodle","labrador","retriever")));

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

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

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

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

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

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

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

To add multiple items to your 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"]
    }
  ]
)
ConstructorItem item1 = new ConstructorItem("Labradoodle");
item1.setSuggestedScore(360);
item1.setUrl("http://www.mydogs.com/labradawdle");
item1.setImageUrl("https://images.mydogs.com/labradawdle.jpg");
item1.setDescription("A crossbreed dog created by crossing the Labrador Retriever and the Pawdle");
item1.setKeywords(new ArrayList<>(Arrays.asList("pawdle","labrador","retriever")));

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

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

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

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

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

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

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

A batch add or update allows you to add a group of items to your 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("Australian Shepherd")
}
boolean success = constructorio.removeItemBatch(items, "Products")
List<ListItem> itemList = new List<ListItem>();
itemList.Add(new ListItem(
  Name: "Labradoodle")
);
itemList.Add(new ListItem(
  ID: "D26")
);
bool success = ConstructorIOAPI.RemoveBatch(itemList, "Products");

The above command returns a 204 Success response on success.

To remove multiple items from your 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"]
);
ConstructorItem item = new ConstructorItem("Labradoodle");
item.setSuggestedScore(360);
item.setUrl("http://www.mydogs.com/labradoodle");
item.setImageUrl("https://images.mydogs.com/labradoodle.jpg");
item.setDescription("A crossbreed dog created by crossing the Labrador Retriever and the Poodle");
item.setKeywords(new ArrayList<>(Arrays.asList("poodle","labrador","retriever")));
boolean success = constructorio.addItem(item, "Products");
// search suggestion
ListItem item = new ListItem(
  Name: "Golden Retriever",
  AutocompleteSection: "Search Suggestion"
);
bool success = ConstructorIOAPI.Add(item);

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

The above command returns a 204 Success response on success.

To add an item to your 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"]
);
ConstructorItem item = new ConstructorItem("Labradoodle");
item.setSuggestedScore(360);
item.setUrl("http://www.mydogs.com/labradawdle");
item.setImageUrl("https://images.mydogs.com/labradawdle.jpg");
item.setDescription("A crossbreed dog created by crossing the Labrador Retriever and the Pawdle");
item.setKeywords(new ArrayList<>(Arrays.asList("pawdle","labrador","retriever")));
boolean success = constructorio.addOrUpdateItem(item, "Products");
// search suggestion
ListItem item = new ListItem(
  Name: "Golden Retriever",
  AutocompleteSection: "Search Suggestion"
);
bool success = ConstructorIOAPI.AddOrUpdate(item);

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

The above commands return a 204 Success response on success.

An add or update operation (also known as an UPSERT) updates an item in your 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"
);
ConstructorItem item = new ConstructorItem("Golden Retriever");
boolean success = constructorio.removeItem(item, "Products");
// remove by name
ListItem itemByName = new ListItem(
  Name: "Golden Retriever",
  AutocompleteSection: "Search Suggestions"
);

bool success = ConstructorIOAPI.Remove(itemByName);

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

bool success = ConstructorIOAPI.Remove(itemByID);

The above command returns a 204 Success response on success.

To remove an item from your 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"]
);
String oldItemName = "Australian Shepard";
ConstructorItem item = new ConstructorItem("Australian Awesome Shepherd");
item.setSuggestedScore(130);
item.setUrl("http://www.mydogs.com/australian_shepherd");
item.setImageUrl("hhttps://images.mydogs.com/australian_shepherd.jpg");
item.setDescription("A medium-sized breed of dog developed on ranches in the Western United States");
item.setKeywords(new ArrayList<>(Arrays.asList("aussie")));
boolean success = constructorio.modifyItem(item, "Products", oldItemName);
// search suggestion
ListItem item = new ListItem(
  Name: "Golden Retriever", // old item name
  AutocompleteSection: "Search Suggestion"
);
item.Name = "Breed: Golden Retriever" // new item name
bool success = ConstructorIOAPI.Modify(item);

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

The above command returns a 204 Success response on success.

To modify an item already in your 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.
AutocompleteResponse result = constructorio.autocomplete("Pood");
// The autocomplete query endpoint is not implemented for backend libraries.
// Please refer to shell documentation or our Javascript (front-end) client.

The above command returns a 200 Success response on success.

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

You can try out an autocomplete query on your dataset by typing the following URL into a web browser: https://ac.cnstrc.com/autocomplete/[query]?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.

Autocomplete Responses: Overview

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

Response structure: Sections

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

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

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

Response structure: Request object

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

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

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

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

Response structure: Value & matched terms

All autosuggest responses will include at least two fields:

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

Autocomplete Responses: Search Suggestions

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

Search Suggestions: Groups

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

User types shirt

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

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

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

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

Autocomplete Responses: Products

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

Products: Common fields

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

Additional Data (may not be present)

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

Search

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

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

Search Queries

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

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

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

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

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

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&filters[Price]=100-200&fmt_options[groups_start]=current&fmt_options[groups_max_depth]=1

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

Search Responses

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

The response format is as follows:

Response structure overview

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

    "request": {
        "page": 10,
        "num_results_per_page": 50,
        "term": "labrador",
        ...
    }
}

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:

Response structure: Request object

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

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

Example: For the query ’/search/food?key=[your key]&num_results_per_page=75’ we might get the following request info: { "request": { "page": 1 "num_results_per_page": 75 "term": "food" } }

Responses: Result structure

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

Facets fields

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

Facet option fields

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

Response: Redirect structure

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

Redirect structure

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

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

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", "Search Suggestions", "alphabet soup");
// xyz is the term
// Search Suggestions is the autocomplete section
// alphabet soup is the item
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", "alphabet soup", "$1.99");
// xyz is the term
// Search Suggestions is the autocomplete section
// alphabet soup is the item
// $1.99 is the revenue
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]

Redirect Rules

Introduction

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

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

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

Redirect objects

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

Redirect rule object

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

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

Redirect rule match object

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

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

where:

Create redirect rule

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

Create redirect rule

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

Response

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

HTTP request

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

JSON body

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

Read all redirect rules

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

Read all redirect rules

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

Response

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

HTTP request

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

Read redirect rule

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

Read redirect rule

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

Response

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

HTTP request

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

Update redirect rule (completely)

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

Update redirect rule (completely)

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

Response

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

HTTP request

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

JSON body

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

Update redirect rule (partially)

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

Update redirect rule (partially)

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

Response

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

HTTP request

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

JSON body

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

Delete redirect rule

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

Delete redirect rule

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

Response

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

HTTP request

DELETE https://ac.cnstrc.com/v1/redirect_rules/<redirect_rule_id>?key=[your 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.