## Uncovr API – Documentation

- April 23, 2022
- Posted by: FOYI
- Category: 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

Contact Us for an introductory call to understand how we can help you.