Uncovr API – Documentation
- April 23, 2022
- Posted by: FOYI
- Categories: Blog, Technical Documentation
API Subscription
The first step to accessing the API is to get the subscription key. The steps to sourcing the subscription key are as follows.
1. Head over to the API developer portal at https://foyi.developer.azure-api.net.
2. Click on the Sign up button on the home page.
3. Enter your details such as email, password etc.
4. You will receive an email to verify your email id.
5. Once you verify your email, please head over to the Products section of the developer portal. You can find it on the menu at the top right hand corner of the web page.
6. Please select the product Starter by clicking it. It will take you to the product page where you will find the section Your subscriptions. Please enter a name for your subscription and hit Subscribe.
7. Post subscribing, on your profile page, under the subscriptions section, click on show next to the Primary key. That is the subscription key you will need to access the API. Congratulations!!, you now can access the API.
8. If you have any issues with the signup, please email support@foyi.co.nz
API Reference
indepAndDep
Generates independent and dependent variables.
The components of this function are as follows.
1. API end point: The end point that responds to the call.
2. Key: The subscription key to the API.
3. Parameters: The name of the function at the API that is called.
4. Body: The json file that needs to be posted to the API end point.
The first level of the json has two elements namely iv i.e. independent variable(s) and dv i.e. dependent variable.
The element iv has one entry per independent variable. The example code below has a request for three independent variables and therefore has 3 elements namely iv1, iv2 and iv3. Each of these elements has the following key-value pairs where the key is the parameter for the function and the value is its corresponding value.
noOfpoints corresponds to the number of observations i.e the number of rows of data requested.
lowerBound and upperBound represents the range of values from which random values will be chosen for each of the independent variable.
dataType defines the type of data. In the current version of the product, this can take one of the two values namely continuous and discrete. Please note that if you would like to request a categorical variable, the current work around is that you can specify discrete as dataType and give a numeric range of numbers by using lowerBound and upperBound. The resultant values can be later replaced with your own class values.
slope is an optional element and is not mandatory like the rest of them. If you would like to have a coefficient of your choice to be used for the independent variable, you can place it here. If this key is not provided, the API would generate the coefficients randomly. Please note that either all or none of the independent variables must have a slope.
The element dv corresponds to the dependent variable. Currently, there is only one parameter for this element namely, dataType. The only value this can take currently is continuous. An example of calling the function is displayed below.
from requests import post
from json import dumps
apiEndPoint = "https://foyi.azure-api.net/uncovr/uncovr/"
key="<insert the subscription key here>"
# Function to call uncovr API
def uncovrApi(body, key, params):
headers = {"Content-Type":"application/json", "Ocp-Apim-Subscription-Key" : key}
response = post(apiEndPoint, params = params, data = dumps(body), headers=headers)
return response
body = {
"iv" : {
"iv1" : {
"noOfpoints" : 100,
"lowerBound" : 1,
"upperBound" : 6,
"slope" : 1.23,
"dataType" : "discrete"
},
"iv2" : {
"noOfpoints" : 100,
"lowerBound" : 1,
"upperBound" : 6,
"slope" : 4.56,
"dataType" : "discrete"
},
"iv3" : {
"noOfpoints" : 100,
"lowerBound" : 1,
"upperBound" : 6,
"slope" : 7.89,
"dataType" : "discrete"
}
},
"dv" : {
"dataType" : "continuous"
}
}
params = {"funcName" : "indepAndDep"}
resp = uncovrApi(body=body, key=key, params=params)
Results
1. The output of the POST action will have the following elements.
depVar is a list of values corresponding to the dependendent variable.
slope prefixed elements are the corresponding slope i.e. the coefficient of the independent variable. For example, if there are 3 independent variables in the POST request, then there will be 3 corresponding slopes for them.
indepVars is a list of independent variables that are requested. For example, if there are 3 independent variables in the POST request, then there will be 3 corresponding elements in the list. Furthermore, it must be noted that the length of each element of the list i.e. the independent variable will be equal to the parameter noOfpoints in the the POST request.
error is a list of errors for every observation.
Besides the above data, model performance measurements such as mae(mean absolute error), me(mean error) and rmse(root mean squared error) are also provided.
An example output of calling the function directly using postman is displayed below.
2. The output can be interpreted as follows.
The dependent variable can be computed as a linear function of the intercept, independent variables, slopes and error.
If there are 3 independent variables in the POST request, then the dependent variable can be computed as follows.
depVar = intercept + (slope1 * iv1) + (slope2 * iv2) + (slope3 * iv3) + error