Introduction

What is the Twiggle API?

The Twiggle API supplies natural language understanding and a deep knowledge of consumer products to e-commerce search engines. It enhances search engine recall and relevance, leveraging its deep natural language understanding and knowledge graph for consumer products to translate search queries and raw catalog data into structured representations. This solution complements your existing search engine, adding a semantic layer and granular understanding to current search logic.

By leveraging structured, deep semantic understanding of both raw catalog data and search queries, the Twiggle API ensures your site displays search results to your users that best match their expressed intent.

Integration with Your Search Engine

To use the Twiggle API, you need to integrate it into your search engine indexing and querying processes:

  1. As part of your indexing process, the Twiggle API performs semantic analysis of raw product data from your catalog and extracts structured product specifications to be indexed in your search engine. This will enable your search engine to match products based on Twiggle’s natural language interpretation of your shoppers’ search queries.
  2. As part of your querying process, the Twiggle API performs semantic analysis of your shoppers' search queries and produces interpretations with structured search specifications. The API then translates these interpretations to your search engine's query language and returns a ready-to-use query that enables your search engine to return matching products.

Thus, the API provides your search engine with a semantic search signal to enable the retrieval of relevant results based on the shopper's query. This signal can be combined with any of your preexisting search signals to create a holistic search logic that is tailored to your business.

Semantic Engine & API Versioning

Twiggle’s API is the interface to Twiggle’s Semantic Engine. The Semantic Engine combines deep language analysis capabilities with a rich knowledge graph which models the world of consumer products. These are the technological foundations which enable it to extract structured semantic data from raw product data and search queries.

Twiggle regularly enhances its Semantic Engine and the API with new capabilities and features to better understand new product types, cover more product attributes and improve recall and precision. Unlike API updates, updates to the Semantic Engine do not require code adaptations on your end. Therefore, Twiggle maintains two version sets: Engine versions and API versions. To ensure you benefit from enhancements and updates, always use the latest Engine version when indexing a full catalog.

Whenever you send a request to the Twiggle API, you need to declare which Engine version you are using (through a query parameter). To ensure consistency between the API's operation as part of your indexing and querying processes, you must always make sure to perform query interpretations with the Engine version used when creating the index you use in production. Detailed instructions are provided in the querying and indexing integration sections.

User Interactions

Twiggle's API includes proprietary algorithms to analyze key user interactions, e.g. product views, add-to-cart events and purchases. With our Interactions Reporting tool, Twiggle's API can examine your shoppers' unique search patterns and trains the Twiggle API to produce refined results for your specific audience.

Before You Start

To access the Twiggle API, you will need your Twiggle partner ID. This is a parameter which should be embedded into the Twiggle API's base URI and is unique for your account with Twiggle. This ID will ensure that the Twiggle API operates with the system configuration set up by Twiggle to specifically suit your business needs and technical specifications.

The Twiggle API uses Basic Authentication over SSL. All requests require an Authorization Header. Your username and password will be provided by Twiggle prior to integration.

The Twiggle API's base URI is https://<your_partner_id>.api.twiggle.com/v1.6.


Implement Twiggle's API in 3 steps:

  1. Integrate the Twiggle API in your indexing process
  2. Integrate the Twiggle API in your querying process
  3. Add the Twiggle Analytics library to your layout template