Recommend

Runs the prediction model on the provided data, and provides desired recommendations.

Haven OnDemand contains Predictive Analytics APIs to classify, predict, and analyze data. For more information about Predictive Analytics, see Introduction to Predictive Analytics.

The Recommend API recommends changes to a data set to achieve a required result. After you create a prediction model by using the Train Prediction API, and predict new data by using the Predict API, you might want to achieve a result different from the prediction. You can use the Recommend API to try and change the outcome of the predicted data by specifying which features can be changed, and asking for a specific result. The model returns a changed dataset to comply with the required result.

For example: a salesperson who wanted to predict the outcome of sales pipeline could train a prediction model using past data and classify future data based on this model. Some of the sale opportunities might be predicted as 'fail', when ideally you want 'success'. The salesperson can use the Recommend API to receive further insight about the features to change (and to which values) to increase the chances of a successful sale.

The recommendation data set must have the same structure as the training data set.

Note: The Recommend API can recommend changes only for classification prediction models, not regression models.

Quick Start

The Recommend API uses an input file to run a recommendation job against a previously trained classification model. For example:

/1/api/[async|sync]/recommend/v2?model_name=model_name&required_label=required_label&recommendations_amount=recommendations_amount&modifiable_features=modifiable_features&fields=fields_metadata&json= or file= or url= or reference=

This call processes the input data and calculates the changes needed in the dataset to achieve the prediction that you specify in the required_label parameter. The API modifies only the features listed in the modifiable_features parameter.

The Recommend API works only with JSON input files. You cannot call the Recommend API against a regression prediction model.

You must set the model_name parameter to the name of an existing prediction model that you want to use for recommendation.

The JSON data that you submit must contain the fields for your data, in a dataset object. It must use the same structure and order as the data you used in the Train Prediction API. For example:

{
   "dataset": [
      {
         "sepal length":4.9,
         "sepal width":3,
	     "petal length":1.4,
	     "petal width":0.2,
	     "class":"Iris-setosa"
      },
      {
         "sepal length":4.7,
	     "sepal width":3.2,
	     "petal length":1.3,
         "petal width":0.2,
         "class":"Iris-setosa"
      },
      {
         "sepal length":4.6,
         "sepal width":3.4,
         "petal length":1.4,
         "petal width":0.3,
         "class":"Iris-setosa"
      },
      {
         "sepal length":4.4,
         "sepal width":2.9,
         "petal length":1.4,
         "petal width":0.2,
         "class":"Iris-setosa"
      },
      {
         "sepal length":6.5,
         "sepal width":3,
         "petal length":5.2,
         "petal width":2,
         "class":"Iris-virginica"
      }
   ]
}

You set the required_label parameter to the value of the prediction field that you want (the prediction field name is defined by the prediction model that you use). You also set the modifiable_features parameter to a list of field names that the Recommend API can update to produce the requested result.

You must also set the fields parameter to a JSON object that defines the types of each of the fields in your data. For example, the following JSON object defines the fields metadata for the example JSON data above.

{
   "fields": [
      {
	     "name":"sepal length",
		 "type":"NUMERIC"
      },
	  {
	     "name":"sepal width",
		 "type":"NUMERIC"
	  },
	  {
	     "name":"petal length",
		 "type":"NUMERIC"
	  },
	  {
	     "name":"petal width",
		 "type":"NUMERIC"
	  },
	  {
	     "name":"class",
		 "type":"STRING"
	  }
   ]
}

The recommendation_amount parameter allows you to set the number of recommendations options you want to provide for each entry in your data.

The API response is in JSON format, and includes the original data set, with recommendations added as new records.

Synchronous
https://api.havenondemand.com/1/api/sync/recommend/v2
Asynchronous
https://api.havenondemand.com/1/api/async/recommend/v2
Authentication

This API requires an authentication token to be supplied in the following parameter:

Parameter Description
apikey The API key to use to authenticate the API request.
Parameters

This API accepts the following parameters:

Required
Name Type Description
file
binary A file containing the JSON document that contains the data for recommendation.
json
json The JSON document that contains the data for recommendation.
reference
string A Haven OnDemand reference obtained from either the Expand Container or Store Object API. The corresponding JSON document is passed to the API.
url
string A publicly accessible HTTP URL from which the JSON document can be retrieved.
model_name
resource The name of the prediction model to use for recommendation.
required_label
string The label that you want the prediction to return.
modifiable_features
array<string> The names of the fields that contain values that the service can modify.
Optional
Name Type Description
recommendations_amount
number The number of recommendations to produce for each record. Default value: 1.
fields
json The list of fields in the dataset.

This API returns a JSON response that is described by the model below. This single model is presented both as an easy to read abstract definition and as the formal JSON schema.

Asynchronous Use

Additional requests are required to get the result if this API is invoked asynchronously.

You can use /1/job/status/<job-id> to get the status of the job, including results if the job is finished.

You can also use /1/job/result/<job-id>, which waits until the job has finished and then returns the result.

Model
This is an abstract definition of the response that describes each of the properties that might be returned.
Recommend Response {
dataset ( array[Dataset] ) An array of records with their predicted values
}
Recommend Response:Dataset {
row ( object ) An object that shows the original record values, in the same order as the original dataset.
prediction ( ) The predicted field result according to prediction model.
recommendations ( array[Recommendations] ) An array of recommended records.
}
Recommend Response:Dataset:Recommendations {
confidence ( number ) The confidence that the specified changes will result in the required label.
distance ( number ) The distance between the original record and the recommended record.
prediction ( ) The predicted field result according to prediction model.
recommendation ( object ) An object of recommended record values, ordered in correlation to the list of fields metadata.
}
Model Schema
This is a JSON schema that describes the syntax of the response. See json-schema.org for a complete reference.
{
    "properties": {
        "dataset": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "row": {
                        "type": "object"
                    },
                    "prediction": {
                        "type": [
                            "number",
                            "string"
                        ]
                    },
                    "recommendations": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "confidence": {
                                    "type": "number"
                                },
                                "distance": {
                                    "type": "number"
                                },
                                "prediction": {
                                    "type": [
                                        "number",
                                        "string"
                                    ]
                                },
                                "recommendation": {
                                    "type": "object"
                                }
                            },
                            "required": [
                                "confidence",
                                "distance",
                                "prediction",
                                "recommendation"
                            ]
                        }
                    }
                },
                "required": [
                    "row",
                    "prediction",
                    "recommendations"
                ]
            }
        }
    },
    "required": [
        "dataset"
    ]
}
https://api.havenondemand.com/1/api/sync/recommend/v2
/api/api-example/1/api/sync/recommend/v2
Examples
See this API for yourself - select one of our examples below.
JSON Format
Recommend changes of data based on model with JSON data format.
Parameters
Required
Select file Change Remove
Name Type Value
model_name
resource
required_label
string
modifiable_features
array
Add another value
Optional
Name Type Value
recommendations_amount
number
fields
json


ASync – Response An error occurred making the API request
Response Code:
Response Body

	
Making API Request…
Checking result of job

To try this API with your own data and use it in your own applications, you need an API Key. You can create an API Key from your account page - API Keys.

Output Refresh An error occurred making the API request View Input
Rendered RawHtml Response
Result Display
Response Code:
Response Body:

			
Make this call with curl

Version 2 (2016-07-25)

This page outlines the changes to the Recommend API from the previous version.

  • Prediction services are now called prediction models. The service_name parameter has been renamed to model_name. Similarly, service is now named model in the API response.
  • The accepted prediction data format has changed. Fields in the data must now have the type NUMERIC or STRING. For JSON input data, you must set the fields parameter to specify the details of the fields in your input data. For recommendation, the data format is now the same as for the Train Prediction and Predict APIs. You must set the modifiable_features parameter to define the fields in the data that can be changed in the recommendation.
  • The response format has been simplified and improved. Prediction results are now returned with the row object that describes the record, and the recommendations are provided as part of this object.


If you would like to provide us with more information then please use the box below:

We will use your submission to help improve our product.