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
Read and download various code examples of how to bring the Ask Ziggy Natural Language Understanding technology into your applications in different programming languages.
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’.
The application details page provides important information that developers need to develop applications that consume the Ask Ziggy API.
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.
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.
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 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.
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.
Below is an example of the Samples input.
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.
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.
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.
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.
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.
The REST-based API call expects the URL be prepared a certain way:
So, for example above, you would generate the Hash using HMAC-SHA256 for the below string using your secret key: