Tabular API Quick Start

In this guide we'll use the Nyckel Api to create, train, and invoke a tabular function which predicts whether a customer is likely to purchase a premium subscription based on their demographic and usage behavior.

Authenticate Your App

1. Sign up / sign in

   If you haven't already, sign up or log in to Nyckel by clicking 'Get Started' in the upper right corner.

2. Get client credentials for your application

   Navigate to the Api Keys page and store the credentials in your application's config. Note that in production you should take care to ensure that at the Client Secret is stored securely.

3. Create an access token

   Using your credentials, call the connect/token endpoint to create an access token:

   • curl
   • python

   curl -X POST \
     -H 'Content-Type: application/x-www-form-urlencoded' \
     -d 'client_id=<clientId>&client_secret=<clientSecret>&grant_type=client_credentials' \
     <authority>/connect/token
   

   import requests
   
   token_url = '<authority>/connect/token'
   data = {'client_id': '<clientId>', 'client_secret': '<clientSecret>', 'grant_type': 'client_credentials'}
   
   result = requests.post(token_url, data = data)
   print(result.text)

Set Up Your Function

1. Create the function

   First we need to create a function which we'll train using our usage data. Use the accessToken you created in the previous step.

   • curl
   • python

   curl -X POST \
     -H 'Authorization: Bearer <accessToken>' \
     -H 'Content-Type: application/json' \
     -d '{"name":"Likelihood to go Premium","inputModality":"Tabular"}' \
     https://www.nyckel.com/v0.9/functions
   

   import requests
   
   url = 'https://www.nyckel.com/v0.9/functions'
   headers = {
       'Authorization': 'Bearer ' + '<accessToken>',
   }
   
   result = requests.post(url, headers=headers, json={"name":"Likelihood to go Premium","inputModality":"Tabular"})
   print(result.text)
   

   Note: the v1/functions endpoint is still in private beta; so we use v0.9 here.

2. Create the fields

   For tabular data, we must specify which fields we'll be sending to Nyckel along with their data types. For this example, we'll create three fields: country, loginType, and avgTimeOnSite

   • curl
   • python

   curl -X POST \
     -H 'Authorization: Bearer <accessToken>' \
     -H 'Content-Type: application/json' \
     -d '{"name":"country","type":"Text"}' \
     https://www.nyckel.com/v1/functions/<functionId>/fields
   

   import requests
   
   url = 'https://www.nyckel.com/v1/functions/<functionId>/fields'
   headers = {
       'Authorization': 'Bearer ' + '<accessToken>',
   }
   
   result = requests.post(url, headers=headers, json={"name":"country","type":"Text"})
   print(result.text)
   

   • curl
   • python

   curl -X POST \
     -H 'Authorization: Bearer <accessToken>' \
     -H 'Content-Type: application/json' \
     -d '{"name":"loginType","type":"Text"}' \
     https://www.nyckel.com/v1/functions/<functionId>/fields
   

   import requests
   
   url = 'https://www.nyckel.com/v1/functions/<functionId>/fields'
   headers = {
       'Authorization': 'Bearer ' + '<accessToken>',
   }
   
   result = requests.post(url, headers=headers, json={"name":"loginType","type":"Text"})
   print(result.text)
   

   • curl
   • python

   curl -X POST \
     -H 'Authorization: Bearer <accessToken>' \
     -H 'Content-Type: application/json' \
     -d '{"name":"avgTimeOnSite","type":"Text"}' \
     https://www.nyckel.com/v1/functions/<functionId>/fields
   

   import requests
   
   url = 'https://www.nyckel.com/v1/functions/<functionId>/fields'
   headers = {
       'Authorization': 'Bearer ' + '<accessToken>',
   }
   
   result = requests.post(url, headers=headers, json={"name":"avgTimeOnSite","type":"Text"})
   print(result.text)
   

3. Create the labels

   We also need to provide the list of possible categories our function can return. For this example we'll use Will go Premium and Won't go Premium

   • curl
   • python

   curl -X POST \
     -H 'Authorization: Bearer <accessToken>' \
     -H 'Content-Type: application/json' \
     -d '{"name":"Will go Premium"}' \
     https://www.nyckel.com/v1/functions/<functionId>/labels
   

   import requests
   
   url = 'https://www.nyckel.com/v1/functions/<functionId>/labels'
   headers = {
       'Authorization': 'Bearer ' + '<accessToken>',
   }
   
   result = requests.post(url, headers=headers, json={"name":"Will go Premium"})
   print(result.text)
   

   • curl
   • python

   curl -X POST \
     -H 'Authorization: Bearer <accessToken>' \
     -H 'Content-Type: application/json' \
     -d '{"name":"Won't go Premium"}' \
     https://www.nyckel.com/v1/functions/<functionId>/labels
   

   import requests
   
   url = 'https://www.nyckel.com/v1/functions/<functionId>/labels'
   headers = {
       'Authorization': 'Bearer ' + '<accessToken>',
   }
   
   result = requests.post(url, headers=headers, json={"name":"Won't go Premium"})
   print(result.text)
   

4. Upload some samples

   Finally, we need to upload example data where we already know whether the customer converted to Premium. To provide the tabular data, we can specify either the field name or the returned field Id. For annotating the category, however, we'll need to use the label Ids returned from the POST calls.

   • curl
   • python

   curl -X POST \
     -H 'Authorization: Bearer <accessToken>' \
     -H 'Content-Type: application/json' \
     -d '{"data":{"country":"United States","loginType":"Google","avgTimeOnSite":"2h4m"},"annotation":{"labelId":"label_2n5a7za51n329v0l"}}' \
     https://www.nyckel.com/v1/functions/<functionId>/samples
   

   import requests
   
   url = 'https://www.nyckel.com/v1/functions/<functionId>/samples'
   headers = {
       'Authorization': 'Bearer ' + '<accessToken>',
   }
   
   result = requests.post(url, headers=headers, json={"data":{"country":"United States","loginType":"Google","avgTimeOnSite":"2h4m"},"annotation":{"labelId":"label_2n5a7za51n329v0l"}})
   print(result.text)
   

   • curl
   • python

   curl -X POST \
     -H 'Authorization: Bearer <accessToken>' \
     -H 'Content-Type: application/json' \
     -d '{"data":{"country":"India","loginType":"Username / Password","avgTimeOnSite":"3h22m"},"annotation":{"labelId":"label_85osy5xwjcscc08o"}}' \
     https://www.nyckel.com/v1/functions/<functionId>/samples
   

   import requests
   
   url = 'https://www.nyckel.com/v1/functions/<functionId>/samples'
   headers = {
       'Authorization': 'Bearer ' + '<accessToken>',
   }
   
   result = requests.post(url, headers=headers, json={"data":{"country":"India","loginType":"Username / Password","avgTimeOnSite":"3h22m"},"annotation":{"labelId":"label_85osy5xwjcscc08o"}})
   print(result.text)
   

   • curl
   • python

   curl -X POST \
     -H 'Authorization: Bearer <accessToken>' \
     -H 'Content-Type: application/json' \
     -d '{"data":{"country":"United States","loginType":"Username / Password","avgTimeOnSite":"41m"},"annotation":{"labelId":"label_85osy5xwjcscc08o"}}' \
     https://www.nyckel.com/v1/functions/<functionId>/samples
   

   import requests
   
   url = 'https://www.nyckel.com/v1/functions/<functionId>/samples'
   headers = {
       'Authorization': 'Bearer ' + '<accessToken>',
   }
   
   result = requests.post(url, headers=headers, json={"data":{"country":"United States","loginType":"Username / Password","avgTimeOnSite":"41m"},"annotation":{"labelId":"label_85osy5xwjcscc08o"}})
   print(result.text)
   

   • curl
   • python

   curl -X POST \
     -H 'Authorization: Bearer <accessToken>' \
     -H 'Content-Type: application/json' \
     -d '{"data":{"country":"France","loginType":"Google","avgTimeOnSite":"1h53m"},"annotation":{"labelId":"label_2n5a7za51n329v0l"}}' \
     https://www.nyckel.com/v1/functions/<functionId>/samples
   

   import requests
   
   url = 'https://www.nyckel.com/v1/functions/<functionId>/samples'
   headers = {
       'Authorization': 'Bearer ' + '<accessToken>',
   }
   
   result = requests.post(url, headers=headers, json={"data":{"country":"France","loginType":"Google","avgTimeOnSite":"1h53m"},"annotation":{"labelId":"label_2n5a7za51n329v0l"}})
   print(result.text)
   

5. Wait for training to complete

   Wait ~20 seconds for Nyckel to finish training your function.

Use Your Function

1. Call the invoke endpoint

   Now that you have a trained function, you can have it predict whether a new user will convert to premium:

   • curl
   • python

   curl -X POST \
     -H 'Authorization: Bearer <accessToken>' \
     -H 'Content-Type: application/json' \
     -d '{"data":{"country":"United States","loginType":"Google","avgTimeOnSite":"1h25m"}}' \
     https://www.nyckel.com/v1/functions/<functionId>/invoke
   

   import requests
   
   url = 'https://www.nyckel.com/v1/functions/<functionId>/invoke'
   headers = {
       'Authorization': 'Bearer ' + '<accessToken>',
   }
   
   result = requests.post(url, headers=headers, json={"data":{"country":"United States","loginType":"Google","avgTimeOnSite":"1h25m"}})
   print(result.text)
   

Now Try It With Your Data

Congrats! You just trained a function that can predict the likelihood a customer will convert to Premium... for this data at least. Upload your own data to build a custom function that serves your needs!