Predict

Runs the prediction model on the provided data.

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

The Predict API predicts results by using a classification or regression model created by the Train Prediction API.

The unpredicted data set must have the same structure as the training data set. All columns must exist, except the prediction field column. If the prediction field column does exist, the API ignores any values in this column.

The Predict API generates a data set in the same structure as the unpredicted data, with an additional result field that indicates the predicted values for all records. For classification models, the API also returns a confidence field, which indicates the confidence level of the prediction (between 0 and 1).

Quick Start

The Predict API uses an input file to run a prediction job against a previously trained model. For example:

/1/api/[async|sync]/predict/v2?model_name=model_name&file= or url= or reference= or json=

This call processes the input data and calculates the predicted value for every record in the data set.

You can find a list of your existing prediction models by using the List Resources API. You can retrieve the details of your prediction model by using the Get Prediction Model Details API.

Note: you can use the v2 Predict API only with prediction models that you created with the v2 Train Prediction API.

The Predict API can work either on a CSV or JSON input file.

Note: API input is subject to a maximum size quota. If you upload text or a file that is too large, the API returns an error. For more information, see Rate Limiting, Quotas, Data Expiry, and Maximums.

The CSV input file must contain headers and values, separated by commas (,). You can specify commas in values by using quotation marks (").

The JSON input format and JSON files must use the following schema definition:

{
	"type": "object",
	"properties": {
		"fields": {
			"type": "array",
			"items": {
				"type": "object",
				"properties": {
					"name": {
						"type": "string"
						},
					"order": {
						"type": "integer"
						},
					"type": {
						"type": "string",
						"enum": [
							"NUMERIC",
							"STRING"
						]
					}
				},
				"required": [
					"name",
					"order",
					"type"
				]
			}
		},
		"values": {
			"type": "array",
			"items": {
				"type": "object",
				"properties": {
					"row": {
						"type": "array",
						"items": {
							"type": "string"
						}
					}
				}
			}
		}
	},
	"required": [
		"fields",
		"values"
	]
}

The API response includes the original data set, with prediction values added as a new field named results. The response can be either in CSV or JSON format.

JSON response example:

{
	"fields": [ {...}
	],
	"values": [ {...}
	]
}

CSV response example:

{
	"status": 200,
	"file": "..."
}
Synchronous
https://api.havenondemand.com/1/api/sync/predict/v2
Asynchronous
https://api.havenondemand.com/1/api/async/predict/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 or CSV document that contains the data for prediction.
json
json A JSON object containing data for training the prediction model.
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 model to activate on the data.
Optional
Name Type Description
format
enum The format to use to return the results. Default value: json.
fields
json The list of fields in the dataset. This parameter is required if the dataset is in JSON format.
Enumeration Types

This API's parameters use the enumerations described below:

format
The format to use to return the results.
csv CSV
Return results in CSV format.
json JSON
Return results in JSON format.

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.
Predict Response {
dataset ( array[Dataset] ) An array of records with their predicted values and confidence
}
Predict Response:Dataset {
row ( object ) An object indicating the original record values, ordered in correlation to the field of Fields Metadata.
prediction ( ) The predicted field result according to prediction model.
confidence ( number , optional) The confidence that the label will be as required.
}
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"
                        ]
                    },
                    "confidence": {
                        "type": "number"
                    }
                },
                "required": [
                    "row",
                    "prediction"
                ]
            }
        }
    },
    "required": [
        "dataset"
    ]
}
https://api.havenondemand.com/1/api/sync/predict/v2
/api/api-example/1/api/sync/predict/v2
Examples
See this API for yourself - select one of our examples below.
CSV Format
Predict label of new data based on model with CSV data format.
JSON Format
Predict label of new data based on model with JSON data format.
Parameters
Required
Select file Change Remove
Name Type Value
model_name
resource
Optional
Name Type Value
format
enum
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 Predict API from the previous version.

  • Prediction services are now called prediction models. The service_name parameter has been renamed to model_name.
  • The response format has been simplified and improved. Prediction results are now returned with the row object that describes the record.
  • 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.
  • You can now predict values for regression-type prediction models.


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.