ASK ZIGGY
           
               
                                                                                                                   
                           
                       
           
                       

The API

The Ask Ziggy API enables developers to quickly bring voice & natural language functionality to their applications. The Portal allows developers to configure API Applications and train them for Natural Language Understanding (NLU) in the application domain.

Developers simply make REST-based API calls with natural language as input and get back output in a format they can process to serve their app.

API Portal Video Demo

Code Samples

Read and download various code examples of how to bring the Ask Ziggy Natural Language Understanding technology into your applications in different programming languages.

Code Samples

Create New App

For purposes of this tutorial we will create a sample application for a music player called “Music App”. This app also comes as a free demo sample when you create a new account on the portal.

To create an application, login with your registered account first. Once logged in, click ‘Manage Applications’ as shown below. Then, click ‘Create New Application’.

Set the application name and description and click ‘Create’.

Application Details

The application details page provides important information that developers need to develop applications that consume the Ask Ziggy API.

app details

Production NLU Model: This indicates the model that is going to be used when you make API calls from your own apps.

API KEY ID: The ‘API Key ID’ is the unique identifier of the application. The 'Secret Key’ is used for HMAC hashing. Every API call includes the ‘API Key ID’ and a ‘Signature’ token which is calculated by HMAC hashing of the input URL using the ‘Secret Key’. More details are provided in the Making API Calls section of this document.

Application Plans: Ask Ziggy provides various API plans depending on feature and traffic requirements of applications. The statistics section provides information on limits and current usage of the application API.

Entity List

In order to use the Ask Ziggy API for your application, you need to setup various parameters and then train the NLU Model.

For our sample app, let’s create some file entity lists for various lists need for a music app. For example, let’s create a file Entity List for the ‘Song’ list.

The content of the file has items like:

  • Beautiful Day
  • Paper Planes
  • Crazy!
  • 99 Problems
  • Crazy In Love
  • Hey, Ya
  • Seven Nation Army
  • Maps
  • Rehab
  • Stan

To upload the Entity List, click the ‘Entity List’ menu item and then “Add New List”.

Similarly, upload files for Artist, Band, Genre & Song.

Sample

Sample is a list of tagged sentences which the trainer uses to train the model based on input from real world usage. First we need to create ‘developer actions’. These are action names the API returns back to the developer which he understands. For our sample app, let’s create following developer actions.

  • Play
  • NextSong
  • PreviousSong
  • Shuffle
sample

Once all Developer Actions have been created, start adding samples and select appropriate Developer Action for them. The system will attempt to Auto-Tag the sample based on knowledge from the Entity List. But, the developer must review these and override or add more tags if needed.

sample

Below is an example of the Samples input.

sample

NLU Model Training

Once all the parameters have been setup for the application, it is ready for training. Click the ‘Start Training NLU Model’ to start training. Depending on complexity of the application, the training can take a few seconds to several minutes.

Depending on your plan, there is support for versioning, wherein you could have multiple Model versions and choose a model to deploy to production.

Test Console

The Test Console provides a quick way to make API calls to the trained application. It allows the developer to type in natural language text as input and see the return value from the API Call. It also provides the exact REST-Based URL call expected to make a successful call.

test console

Model Evaluation Suite

The Model Evaluation Suite helps the developers to evaluate how good the NLU Model is. You set it up just like you created the sample but with different variation of the natural language input that you would like to test. After model is trained you can run this Test Suite and see the accuracy of the model on how it performs compared to expected output.

model evaluation

The Action Score is the percentage of correct Actions identified by the NLU Model. The Entity Score is the percentage of correct Entities identified by the NLU Model. The Confidence Score is the weighted score of Actions & Entities correctly identified. To improve the scores, you will have to improve the quality and variations of Samples used to train the model.

Versioning

The Portal supports a powerful versioning feature. With this, one can easily revert back to previous versions allowing developers to experiment freely. Also, developers have the ability to deploy any model version to production.

*Please note that versioning is not supported on the ‘Base’ plan.

Making API Calls

The REST-based API call expects the URL be prepared a certain way:

https://www.ask-ziggy.net/NLP/api/parse?input=I+want+to+listen+to+Rock&timestamp=2013-03-15+17%3a52%3a30Z&apikey=e8f6c6b3&userid=PortalTestConsole&apiversion=1&signature=d4Fox7xkygjGQfmAb5hPOcBzsZFMDUoZuoSw32QYusE%3d

Where:

  • INPUT = Your natural language query.
  • TIMESTAMP = Current UTC time in the format 'yyyy'-'MM'-'d.d':'mm':'ss'Z"
  • APIKEY = The unique API Key ID of the application.
  • USER ID = Optional variable which could be how you identify your end user. No validations are done on this value.
  • APIVERSION = Set this to the latest version 1.
  • SIGNATURE = The HMAC hash of the input using the secret key. Please replace all ‘spaces’ before computing hash. This means, replace all ‘ ‘, ‘%20’ & ‘+’ with empty string.

So, for example above, you would generate the Hash using HMAC-SHA256 for the below string using your secret key:

input=IwanttolistentoRock&timestamp=2013-03-15+17%3a52%3a30Z&apikey=e8f6c6b3&userid=PortalTestConsole&apiversion=1&secretkey=REPLACEWITHMYSUPERSECRETKEY