NAV
shell javascript ruby python php perl java csharp

Introduction

Welcome to the Constructor.io REST API.

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

Installation

# shell usage doesn't require any installation (except curl)
npm install constructorio
gem install constructorio
pip install constructor-io
composer require constructor-io/constructor-io
cpanm WebService::ConstructorIO
/*
If using Maven, include in your pom.xml:

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

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

If using Gradle, include this:
compile 'com.cnstrc.client:constructorio-client:0.0.1'
*/
/*
Run in the Package Manager Console:

Install-Package constructor.io

Or, if using nuget on the command line:

nuget install constructor.io
*/

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

Authentication

API Token

To authorize, use this code:

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

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

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

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

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

Verification

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

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

HTTP Request

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

Autocomplete Items

Suggestions that are shown in the autocomplete 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

curl -X POST -H "Content-Type: application/json" \
  -d '{"items": [ {"item_name": "power drill"}, {"item_name": "hammer"} ],
    "autocomplete_section":"Search Suggestions"}' \
  -u"[your token]:" "https://ac.cnstrc.com/v1/batch_items?autocomplete_key=[your autocomplete key]"
constructorio.add_batch(
  {
    items: [
      { item_name: "power drill" },
      { item_name: "hammer" }
    ],
    autocomplete_section: "Search Suggestions"
  },
  function(error, response) {
    if (error) {
      console.log(error);
    }
  }
);
response = constructorio.add_batch(
  {
    items: [
      { item_name: "power drill" },
      { item_name: "hammer" }
    ],
    autocomplete_section: "Search Suggestions"
  }
);
items = [
  {"item_name": "power drill"},
  {"item_name": "hammer"}
]
response = constructor_instance.add_batch(
  items=items,
  autocomplete_section="Search Suggestions"
)

toolBox = [
  {"item_name": "power drill 1000", "url": "/products/power-drill-1000", "id": "42"},
  {"item_name": "hammer of thor", "url": "/products/hammer-of-thor"}
]
response = constructor_instance.add_batch(
    items=toolBox,
    autocomplete_section="Products"
)
<?php
$response = $constructor->addBatch(
  array("power drill", "hammer"),
  "Search Suggestions"
);

$toolBox = array(
   array("item_name" => "power drill", "url" => "/products/power-drill", "image_url" => "/images/power-drill.jpg"),
   array("item_name" => "hammer", "url" => "/products/hammer", "image_url" => "/images/hammer.jpg")
);
$response = $constructor->addBatch($toolBox, "Products");
my $response = $constructorio->add_batch(
  items => [ { item_name => "power drill" }, { item_name => "hammer" } ],
  autocomplete_section => "Search Suggestions"
);
boolean success = constructorio.addBatch("Search Suggestions", "power drill", "hammer");
// "Search Suggestions" is an autocomplete section name
// power drill is an item name
// hammer is an item name
List<ListItem> itemList = new List<ListItem>();

itemList.Add(new ListItem(
  Name: "Power drill",
  Description: "Like a drill, with power.",
  URL: "http://constructor.io/power-drill",
  ImageURL: "http://constructor.io/power-drill.jpg"
));

itemList.Add(new ListItem(
  Name: "Hammer",
  Description: "When everything looks like a nail.",
  URL: "http://constructor.io/hammer"
));

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

// itemList is a List<ListItem> composed of key / value pairs as specified in parameters below.
// "Products" is the  autocomplete section to which you'd like to add the items contained in itemList

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.

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

curl -X PUT -H "Content-Type: application/json" \
  -d '{"items": [ {"item_name": "power drill"}, {"item_name": "hammer"} ],
    "autocomplete_section":"Search Suggestions"}' \
  -u"[your token]:" "https://ac.cnstrc.com/v1/batch_items?force=1&autocomplete_key=[your autocomplete key]"
constructorio.add_or_update_batch(
  {
    items: [
      { item_name: "power drill" },
      { item_name: "hammer" }
    ],
    autocomplete_section: "Search Suggestions"
  },
  function(error, response) {
    if (error) {
      console.log(error);
    }
  }
);
response = constructorio.add_or_update_batch(
  {
    items: [
      { item_name: "power drill" },
      { item_name: "hammer" }
    ],
    autocomplete_section: "Search Suggestions"
  }
);
items = [
  {"item_name": "power drill"},
  {"item_name": "hammer"}
]
response = constructor_instance.add_or_update_batch(
  items=items,
  autocomplete_section="Search Suggestions"
)

toolBox = [
  {"item_name": "power drill 1000", "url": "/products/power-drill-1000", "id": "42"},
  {"item_name": "hammer of thor", "url": "/products/hammer-of-thor"}
]
response = constructor_instance.add_or_update_batch(
    items=toolBox,
    autocomplete_section="Products"
)
<?php
$response = $constructor->addOrUpdateBatch(
  array("power drill", "hammer"),
  "Search Suggestions"
);

$toolBox = array(
   array("item_name" => "power drill", "url" => "/products/power-drill", "image_url" => "/images/power-drill.jpg"),
   array("item_name" => "hammer", "url" => "/products/hammer", "image_url" => "/images/hammer.jpg")
);
$response = $constructor->addOrUpdateBatch($toolBox, "Products");
my $response = $constructorio->add_or_update_batch(
  items => [ { item_name => "power drill" }, { item_name => "hammer" } ],
  autocomplete_section => "Search Suggestions"
);
boolean success = constructorio.addOrUpdateBatch("Search Suggestions", "power drill", "hammer");
// power drill is an item name
// hammer is an item name
// Search Suggestions is an autocomplete section name
List<ListItem> itemList = new List<ListItem>();

itemList.Add(new ListItem(
  Name: "Power drill",
  Description: "Like a drill, with power.",
  URL: "http://constructor.io/power-drill",
  ImageURL: "http://constructor.io/power-drill.jpg"
));

itemList.Add(new ListItem(
  Name: "Hammer",
  Description: "When everything looks like a nail.",
  URL: "http://constructor.io/hammer"
));

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

// itemList is a List<ListItem> composed of key / value pairs as specified in parameters below. If "Power drill" or "Hammer" already exist, their metadata will be updated as above. Otherwise new items will be created with these values.
// "Products" is the  autocomplete section to which you'd like to add the items contained in itemList

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.

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": "power drill"}, {"item_name": "hammer"} ],
    "autocomplete_section":"Search Suggestions"}' \
  -u "[your token]:" "https://ac.cnstrc.com/v1/batch_items?autocomplete_key=[your autocomplete key]"
// This method is not currently supported in our javascript client.
response = constructorio.remove_batch(
  {
    items: [
      { item_name: "power drill" },
      { item_name: "hammer" },
      { id: "3" }
    ],
    autocomplete_section: "Products"
  }
);

# Here we've removed a batch of items by item_name and id.
items = [
  {"item_name": "power drill"},
  {"item_name": "hammer"}
]
response = constructor_instance.remove_batch(
  items=items,
  autocomplete_section="Search Suggestions"
)

toolBox = [
  {"item_name": "power drill 1000"},
  {"id": "132"}
]
response = constructor_instance.remove_batch(
    items=toolBox,
    autocomplete_section="Products"
)
<?php
// 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.
List<ListItem> itemList = new List<ListItem>();

itemList.Add(new ListItem(Name: "Power drill"));
itemList.Add(new ListItem(ID: "245"));

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

// itemList is a List<ListItem> with the IDs and/or Names of the items you'd like to remove.
// "Products" is an autocomplete section name.

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.

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

curl -X POST -H "Content-Type: application/json" \
  -d '{"item_name":"power drill","keywords":["battery-powered","drills","drywall"],
  "suggested_score":36,"url":"http://www.mysite.com/power_drill","autocomplete_section":"Search Suggestions"}' \
  -u"[your token]:" "https://ac.cnstrc.com/v1/item?autocomplete_key=[your autocomplete key]"
constructorio.add(
  { item_name: "power drill", autocomplete_section: "Search Suggestions" },
  function(error, response) {
    if (error) {
      console.log(error);
    }
  }
);
response = constructorio.add(
  { item_name: "power drill", autocomplete_section: "Search Suggestions" }
);
response = constructor_instance.add(
    item_name="power drill",
    autocomplete_section="Search Suggestions")
<?php
$response = $constructor->add(
  "power drill", // item name
  "Search Suggestions" // autocomplete section name
);
my $response = $constructorio->add(
  item_name => "power drill",
  autocomplete_section => "Search Suggestions"
);
boolean success = constructorio.add("power drill", "Search Suggestions");
// power drill is an item name
// Search Suggestions is an autocomplete section name
ListItem item = new ListItem(
  Name: "Power drill",
  Description: "Like a drill, with power.",
  URL: "http://constructor.io/power-drill",
  ImageURL: "http://constructor.io/power-drill.jpg",
  AutocompleteSection: "Products"
);

bool success = ConstructorIOAPI.Add(item);

// "item" is a ListItem containing key / value pairs as specified in parameters below.

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-100, 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.

Add or Update an Item

curl -X PUT -H "Content-Type: application/json" \
  -d '{"item_name":"power drill","keywords":["battery-powered","drills","drywall"],
  "suggested_score":36,"url":"http://www.mysite.com/power_drill","autocomplete_section":"Search Suggestions"}' \
  -u"[your token]:" "https://ac.cnstrc.com/v1/item?force=1&autocomplete_key=[your autocomplete key]"
constructorio.add_or_update(
  { item_name: "power drill", autocomplete_section: "Search Suggestions" },
  function(error, response) {
    if (error) {
      console.log(error);
    }
  }
);
response = constructorio.add_or_update(
  { item_name: "power drill", autocomplete_section: "Search Suggestions" }
);
response = constructor_instance.add_or_update(
    item_name="power drill",
    autocomplete_section="Search Suggestions")
<?php
$response = $constructor->addOrUpdate(
  "power drill", // item name
  "Search Suggestions" // autocomplete section name
);
my $response = $constructorio->add_or_update(
  item_name => "power drill",
  autocomplete_section => "Search Suggestions"
);
boolean success = constructorio.addOrUpdate("power drill", "Search Suggestions");
// power drill is an item name
// Search Suggestions is an autocomplete section name
ListItem item = new ListItem(
  Name: "Power drill",
  Description: "Like a drill, with power.",
  URL: "http://constructor.io/power-drill",
  ImageURL: "http://constructor.io/power-drill.jpg",
  AutocompleteSection: "Products"
);

bool success = ConstructorIOAPI.AddOrUpdate(item);

// "item" is a ListItem containing key / value pairs as specified in parameters below. If an item with the name "Power drill" already exists, its Description, Url and ImageUrl will be updated as indicated. Otherwise a new item will be created with these values.

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.

Remove an Item

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]"
constructorio.remove(
  { item_name: "power drill", autocomplete_section: "Search Suggestions" },
  function(error, response) {
    if (error) {
      console.log(error);
    }
  }
);
response = constructorio.remove(
  { item_name: "power drill", autocomplete_section: "Search Suggestions" }
);
response = constructor_instance.remove(
  item_name="power drill", 
  autocomplete_section="Search Suggestions")
<?php
$response = $constructor->remove(
  "power drill", // item name
  "Search Suggestions" // autocomplete section name
);
my $response = $constructorio->remove(
  item_name => "power drill",
  autocomplete_section => "Search Suggestions"
);
boolean success = constructorio.remove("power drill", "Search Suggestions");
// power drill is an item name
// Search Suggestions is an autocomplete section name
ListItem item = new ListItem(
  Name: "Power drill",
  AutocompleteSection: "Products"
);

bool success = ConstructorIOAPI.Remove(item);

// "item" is a ListItem with the Name or ID for the item you'd like to remove

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

curl -X PUT -H "Content-Type: application/json" -d '{"item_name":"power drill","new_item_name":"super power drill","keywords":["concrete","power tools","drills","drywall"],"suggested_score":20,"url":"http://www.mysite.com/power_drill","autocomplete_section":"products_autocomplete"}' \
  -u "[your token]:" "https://ac.cnstrc.com/v1/item?autocomplete_key=[your autocomplete key]"
constructorio.modify(
  {
    item_name: "power drill",
    new_item_name: "super power drill",
    autocomplete_section: "Search Suggestions",
    url: "http://www.mysite.com/power_drill",
  },
  function(error, response) {
    if (error) {
      console.log(error);
    }
  }
);
response = constructorio.modify(
  {
    item_name: "power drill",
    new_item_name: "super power drill",
    autocomplete_section: "Search Suggestions",
    url: "http://www.mysite.com/power_drill",
  }
);
response = constructor_instance.modify(
    item_name="power drill",
    new_item_name="better power drill",
    autocomplete_section="Search Suggestions",
    url="http://www.mysite.com/power_drill")
<?php
$response = $constructor->modify(
  "power drill", // item name
  "super power drill", // new item name (this is required)
  "Search Suggestions", // autocomplete section name
  array("suggested_score" => 100) // array of item properties to modify
);
my $response = $constructorio->modify(
  item_name => "power drill",
  new_item_name => "super power drill",
  autocomplete_section => "Search Suggestions",
  url => "http://www.mysite.com/power_drill"
);
boolean success = constructorio.modify("power drill", "super power drill", "Search Suggestions", paramMap);
// power drill is an item name
// super power drill is an item name
// Search Suggestions is an autocomplete section name
// paramMap is a Map<String, Object> you filled beforehand with the other properties you want to modify. Optional.
ListItem item = new ListItem(
  Name: "Drill",
  URL: "http://constructor.io/drill",
  AutocompleteSection: "Products"
);

item.Name = "Power drill";
item.Description = "Like a drill, with power."

bool success = ConstructorIOAPI.Modify(item);
// "Drill" is the original item name as you previously saved it in our system
// "Power drill" is the new item name
// "Description" is a new description to add for the 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-100, 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.

Autocomplete Queries

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

curl -X GET -H "Content-Type: application/json" \
"https://ac.cnstrc.com/autocomplete/australian?autocomplete_key=pAFl6rReRSI0uXckcxZS&num_results_Search%20Suggestions=3"
// The autocomplete query endpoint is not implemented for backend libraries.
// Please refer to shell documentation or our Javascript (front-end) client. 
# The autocomplete query endpoint is not implemented for backend libraries. 
# Please refer to shell documentation or our Javascript (front-end) client.
# The autocomplete query endpoint is not implemented for backend libraries.
# Please refer to shell documentation or our Javascript (front-end) client.
<?php
// The autocomplete query endpoint is not implemented for backend libraries. 
// Please refer to shell documentation or our Javascript (front-end) client. 
# The autocomplete query endpoint is not implemented for backend libraries.
# Please refer to shell documentation or our Javascript (front-end) client. 
// The autocomplete query endpoint is not implemented for backend libraries. 
// Please refer to shell documentation or our Javascript (front-end) client. 
// The autocomplete query endpoint is not implemented for backend libraries.
// Please refer to shell documentation or our Javascript (front-end) client. 

The above command returns a 200 Success response on success.

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

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

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

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

HTTP Request

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

JSON 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.

Behavioral Data

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

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

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

HTTP Request

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

JSON Parameters

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

Track a click-through

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

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

HTTP Request

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

JSON Parameters

Parameter Required? Description
term Yes The search term the user entered in the search box
autocomplete_section Yes Your autocomplete suggestions can have multiple sections like “Products” and “Search Suggestions”. This indicates which section this item is for. See your dashboard for the section names to use.
item No The autocomplete item that the user clicked on
item_id No The id of the item that the user clicked (use ​either​ this or item to designate the item clicked)

Track a conversion

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

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

HTTP Request

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

JSON Parameters

Parameter Required? Description
term Yes The search term the user entered in the search box
autocomplete_section Yes Your autocomplete suggestions can have multiple sections like “Products” and “Search Suggestions”. This indicates which section this item is for. See your dashboard for the section names to use.
item No The item that the user purchased
item_id No The id of the item that the user purchased (use ​either​ this or item to designate the item purchased)
revenue No The purchase amount in cents (that is, the purchase amount * 100)

Via Javascript

Conversions can also be tracked via Javascript, like so:

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

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

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.

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.

Javascript Client

The Constructor.io javascript client adds autocomplete to your site with two lines of code.

You can install it immediately and it will default to “listening mode” where it will start to learn from your users’ behavior.

After you upload a dataset via our website or API, Constructor.io will start providing your users lightning-fast suggestions!

Install using jQuery

To install with jQuery, use this code:

<script type="text/javascript">
    $.getScript("//cnstrc.com/js/ac.js", function() {
        $('#query').constructorAutocomplete({ key: '[your autocomplete key]' });
    })
</script>

Here, #query is the DOM id of your search box, and your autocomplete key can be found on your dashboard.

Install using requirejs

If you’re using requirejs, you can install our client with this code:

<script type="text/javascript">
    require.config({paths: {constructorAutocomplete: '//cnstrc.com/js/ac'} });
    require(['jquery', 'constructorAutocomplete'], function($) {
        $('#query').constructorAutocomplete({ key: '[your autocomplete key]' });
    });
</script>

Here, #query is the DOM id of your search box, and your autocomplete key can be found on your dashboard.

Style your autocomplete

You may style autocomplete suggestions in any way you’d like.

Autocomplete suggestion HTML

Suggestions are returned with HTML markup as below:

<div class="autocomplete-suggestions">
    <div class="autocomplete-suggestion autocomplete-selected">...</div>
    <div class="autocomplete-suggestion">...</div>
    <div class="autocomplete-suggestion">...</div>
</div>

Example Styling

.autocomplete-suggestions {
    border: 1px solid #999;
    background: #FFF;
    overflow: auto;
}
.autocomplete-suggestion {
    padding: 2px 5px;
    white-space: nowrap;
    overflow: hidden;
}
.autocomplete-selected {
    background: #F0F0F0;
}
.autocomplete-suggestions strong {
    font-weight: normal;
    color: #3399FF;
}

Advanced autocomplete options

We provide a number of options for advanced users. You can enable these options by adding the parameters to the hash that’s passed into the .constructorAutocomplete() method, as below:

<script type="text/javascript">
    $.getScript("//cnstrc.com/js/ac.js", function() {
        $('#query').constructorAutocomplete({ key: '[your autocomplete key]', maxResults: 4, imageWidth: "200px" });
    })
</script>

Option Default Description
boostRecentSearches true Increase ranking of recent user searches.
imageWidth none Specify the width of images displayed in the suggestion list.
maxResults 10 Specify the maximum number of suggestions returned.
sectionOrder order created Set the order in which autocomplete sections appear in suggestion list. Array of autocomplete section names.

Our client is based on the excellent Devbridge autocomplete client, the full documentation for which can be found here.