NAV Navbar
Home icon
SAS Viya REST APIs
shell javascript python go

Analytics Insights

Insights

Base URLs:

Terms of service Email: SAS Developers Web: SAS Developers

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

The Insights API provides insights into your data.

Usage Notes

Overview

This API provides endpoints for insights analytics. The explain insight describes a column in a SAS Cloud Analytic Services (CAS) data source in relation to the other columns in the data.

Terminology

Insights service

Refers to this service

CAS server

The controller process providing access to SAS Cloud Analytic Services functionality.

Variable Screening

The process of determining if a variable is suitable for inclusion in the explanation process. Variables are rejected from the analysis when: - The variable is identical to the response variable or to another underlying factor. - The variable is the basis for a geography item that is assigned as an underlying factor. - The variable is a subset of the response variable. - The variable has a large number of missing values. - The variable has high cardinality.

Forecast

The analytical process that uses the statistical trends in your data source to predict future data values.

Error Codes

HTTP Status Code Error Code Description
400 104500 The column {ColumnName} could not be found in the data source.
400 104501 All of the underlying factors are rejected.
400 104502 There is an insufficient number of observations in the data source to reliably determine the characteristics and the relationships of the column {ColumnName}.
400 104503 The column {ColumnName} has too many unique values. An explanation of its characteristics and relationships with other factors would take too much time to determine.
400 104504 The column {ColumnName} is missing more than half of its values. A reliable explanation of its characteristics and relationship with other factors cannot be determined when the data contains this much uncertainty.
400 104505 The column {ColumnName} is a constant variable. An explanation of its characteristics and relationships with other factors needs more than one unique value.
400 104506 The API failed to get a groupby result.
400 104507 The API failed to get a recordcount result.
400 104508 The API failed to get a distinct result.
400 104509 The API failed to get a correlation result.
400 104510 The CAS management call failed.
400 104511 The NLG service call failed.
400 104512 The format {Format} is not a supported time series format.
400 104513 The column {ColumnName} with format the {Format} is a temporal column and is not allowed for the column name.
400 104514 The request body was missing or invalid.
400 104515 The format service call failed.
400 104516 The column is not specified.
400 104517 The cas resource must have a server({Server}), a library({Library}), and a table({Table}) specified.

Operations

Root

Contains the operations for the root resource.

Code samples

# You can also use wget
curl -X GET / \
  -H 'Authorization: Bearer <access-token-goes-here>' \
  -H 'Accept: application/vnd.sas.api+json'



const headers = {
  'Accept':'application/vnd.sas.api+json'
};

fetch('/',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Accept': 'application/vnd.sas.api+json'
}

r = requests.get('/', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/vnd.sas.api+json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "/", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /

Returns a collection of links to the top-level collections.

Example responses

Root response

{
  "version": 1,
  "links": [
    {
      "method": "GET",
      "rel": "self",
      "href": "/insights",
      "uri": "/insights",
      "type": "application/vnd.sas.api"
    },
    {
      "method": "POST",
      "rel": "/explain",
      "href": "/insights/explain",
      "uri": "/insights/explain",
      "type": "application/vnd.sas.api"
    }
  ]
}

{
  "version": 1,
  "links": [
    {
      "method": "GET",
      "rel": "self",
      "href": "/insights",
      "uri": "/insights",
      "type": "application/vnd.sas.api"
    },
    {
      "method": "POST",
      "rel": "/explain",
      "href": "/insights/explain",
      "uri": "/insights/explain",
      "type": "application/vnd.sas.api"
    }
  ]
}

404 Error

{
  "message": "An error occurred.",
  "errorCode": 104501,
  "httpStatusCode": 404,
  "details": [
    "An error occurred."
  ],
  "errors": [
    "An error occurred."
  ],
  "version": 1
}

{
  "message": "An error occurred.",
  "errorCode": 104501,
  "httpStatusCode": 404,
  "details": [
    "An error occurred."
  ],
  "errors": [
    "An error occurred."
  ],
  "version": 1
}
Status Meaning Description Schema
200 OK The version information for the API, as well as the top-level API entry points. api
404 Not Found The service is not available error2

Explain

Contains the operations for the explain resource.

Explains the column in the data source

Code samples

# You can also use wget
curl -X POST /explain \
  -H 'Authorization: Bearer <access-token-goes-here>' \
  -H 'Content-Type: application/vnd.sas.insights.explain.definition' \
  -H 'Accept: application/vnd.sas.insights.explain.result' \
  -H 'Accept-Language: string' \
  -H 'Accept-Locale: string'


const inputBody = '{
  "cas": {
    "server": "cas-server-name",
    "library": "caslib",
    "table": "dataTable"
  },
  "columnName": "variableName",
  "includeVariableDescription": true,
  "includeOutlierDescription": true,
  "useMissing": true,
  "dateVariable": "",
  "includeVariableScreeningResults": true
}';
const headers = {
  'Content-Type':'application/vnd.sas.insights.explain.definition',
  'Accept':'application/vnd.sas.insights.explain.result',
  'Accept-Language':'string',
  'Accept-Locale':'string'
};

fetch('/explain',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Content-Type': 'application/vnd.sas.insights.explain.definition',
  'Accept': 'application/vnd.sas.insights.explain.result',
  'Accept-Language': 'string',
  'Accept-Locale': 'string'
}

r = requests.post('/explain', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/vnd.sas.insights.explain.definition"},
        "Accept": []string{"application/vnd.sas.insights.explain.result"},
        "Accept-Language": []string{"string"},
        "Accept-Locale": []string{"string"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "/explain", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /explain

Explains the specified column in relation to the other columns in the data. The data is processed into human friendly sentences. This call is a GET via POST.

Body parameter

Example request body for explain

{
  "cas": {
    "server": "cas-server-name",
    "library": "caslib",
    "table": "dataTable"
  },
  "columnName": "variableName",
  "includeVariableDescription": true,
  "includeOutlierDescription": true,
  "useMissing": true,
  "dateVariable": "",
  "includeVariableScreeningResults": true
}
Parameters
Name In Type Required Description
Accept-Language header string false The user's language, which is used to create the description strings. If this header is not set, the language will be the default language of the service.
Accept-Locale header string false A "format locale" that is distinct from the user's language (Accept-Language). Its syntax is similar to Accept-Language. It is used to format numeric values and provides a way for the numeric formatting to be different than the typical numeric formatting of the language. If this header is not set, the language locale will be used.
body body explainDefinition false Explain definition information

Example responses

Explain result

{
  "version": 1,
  "variableDescription": "A string that describes the specified column.",
  "outlierDescription": "A string that describes the outliers of the specified column.",
  "forecastDescription": "A string that describes the forecast of the specified column.",
  "variableScreeningResults": [
    {
      "columnName": "columnName",
      "label": "label",
      "actionTaken": "The factor was rejected because it has too many missing values.",
      "actionsTaken": [
        "The measure was converted to category because relatively few distinct levels were detected.",
        "The factor was rejected because it has too many missing values."
      ],
      "reasons": [
        "MeasureLevelsDetected",
        "TooManyMissingValues"
      ]
    }
  ],
  "warnings": [
    {
      "code": "NewEventLevelChosen",
      "message": "The selected event level is no longer available. A new event level has been chosen."
    }
  ]
}

400 Error

{
  "message": "An error occurred.",
  "errorCode": 104501,
  "httpStatusCode": 400,
  "details": [
    "An error occurred."
  ],
  "errors": [
    "An error occurred."
  ],
  "version": 1
}

{
  "message": "An error occurred.",
  "errorCode": 104501,
  "httpStatusCode": 400,
  "details": [
    "An error occurred."
  ],
  "errors": [
    "An error occurred."
  ],
  "version": 1
}
Responses
Status Meaning Description Schema
200 OK The explanation of the column in relation to the other columns in the data. explainResult
400 Bad Request Bad Request. The request body is not properly formed. This can happen for a variety of reasons including missing required fields in the body, troubles accessing the specified CAS table, and the specified column name is not in the CAS data source. error2

Schemas

explainDefinition

{
  "version": 1,
  "cas": {
    "server": "cas-shared-default",
    "library": "Public",
    "table": "tableName",
    "sessionId": "4ad6e49d-7997-7b40-aee6-5d0d57b1e81e"
  },
  "columnName": "columnName",
  "showVariableDescription": true,
  "showOutlierDescription": false,
  "includeMissing": false,
  "timeSeriesColumnName": "Date"
}

The definition of the explanation that you want to perform.

Properties
Name Type Required Restrictions Description
version integer false none The version of the schema.
cas cas true none The CAS resource specification.
columnName string true none The column name in the CAS table that you want to explain.
showVariableDescription boolean false none An optional flag to generate the variable description. One of these variables must be true: showVariableDescription or showOutlierDescription. The default value is true.
showOutlierDescription boolean false none An optional flag to generate the outlier description. One of these variables must be true: showVariableDescription or showOutlierDescription. The default value is false.
includeMissing boolean false none An optional flag to tell you if missing values should be included in (true) or ignored by (false) the analysis. The default value is false.
timeSeriesColumnName string false none The name of the time series column. When present, the time series column is used to generate forecast insights.

explainResult

{
  "version": 1,
  "variableDescription": "A string that describes the specified column.",
  "outlierDescription": "A string that describes the outliers of the specified column.",
  "forecastDescription": "A string that describes the forecast of the specified column.",
  "screeningResults": [
    {
      "columnName": "columnName",
      "label": "label",
      "actionTaken": "The factor was rejected because it has too many missing values."
    }
  ]
}

The explanation results.

Properties
Name Type Required Restrictions Description
version integer false none The version of the schema.
variableDescription string false none A description of the specified column in relation to the other columns in the data. This value is filled only if the showVariableDescription variable is true.
outlierDescription string false none A description of the outliers for the specified column in relation to the other columns in the data. This value is filled only if the showOutlierDescription variable is true.
forecastDescription string false none A description of the forecast for the specified column in relation to the other columns in the data. This value is filled only if the showForecastDescription variable is true.
screeningResults [screeningResult] false none The results of variable screening. There will be an item for each column in the CAS data source that is not the specified column or time series column.

cas

{
  "server": "cas-shared-default",
  "library": "Public",
  "table": "tableName",
  "sessionId": "4ad6e49d-7997-7b40-aee6-5d0d57b1e81e"
}

The CAS resource specification.

Properties
Name Type Required Restrictions Description
server string true none The server name for the CAS resource.
library string true none The library for the CAS resource.
table string true none The table for the CAS resource.
sessionId string(uuid) false none An optional CAS session ID. If no session ID is specified, a new CAS session will be created, used, and then destroyed.

screeningResult

{
  "columnName": "columnName",
  "label": "label",
  "actionTaken": "The factor was rejected because it has too many missing values."
}

The variable screening result for a column in the CAS table.

Properties
Name Type Required Restrictions Description
columnName string true none The name of the column in the CAS data source.
label string true none The label of the column in the CAS data source.
actionTaken string true none The field will be blank when the variable screening does nothing for this column. Otherwise, the string will describe what the variable screening did (such as reject, convert, and so on.)

error2

{
  "message": "string",
  "id": "string",
  "errorCode": 0,
  "httpStatusCode": 0,
  "details": [
    "string"
  ],
  "remediation": "string",
  "errors": [
    null
  ],
  "links": [
    {
      "method": "string",
      "rel": "string",
      "uri": "string",
      "href": "string",
      "title": "string",
      "type": "string",
      "itemType": "string",
      "responseType": "string",
      "responseItemType": "string"
    }
  ],
  "version": 0
}

Error

Properties
Name Type Required Restrictions Description
message string false none The message for the error.
id string false none The string ID for the error.
errorCode integer false none The numeric ID for the error.
httpStatusCode integer true none The HTTP status code for the error.
details [string] false none Messages that provide additional details about the cause of the error.
remediation string false none A message that describes how to resolve the error.
errors [error2] false none Any additional errors that occurred.
links [link] false none The links that apply to the error.
version integer true none The version number of the error representation. This representation is version 2.

api

{
  "version": 1,
  "links": [
    {
      "method": "string",
      "rel": "string",
      "uri": "string",
      "href": "string",
      "title": "string",
      "type": "string",
      "itemType": "string",
      "responseType": "string",
      "responseItemType": "string"
    }
  ]
}

API

Properties
Name Type Required Restrictions Description
version integer true none The version number of the API representation. This is version 1.
links [link] true none The API's top-level links. 

{
  "method": "string",
  "rel": "string",
  "uri": "string",
  "href": "string",
  "title": "string",
  "type": "string",
  "itemType": "string",
  "responseType": "string",
  "responseItemType": "string"
}

Link

Properties
Name Type Required Restrictions Description
method string false none The HTTP method for the link.
rel string true none The relationship of the link to the resource.
uri string false none The relative URI for the link.
href string false none The URL for the link.
title string false none The title for the link.
type string false none The media type or link type for the link.
itemType string false none If this is a link to a container, itemType is the media type or link type for the items in the container.
responseType string false none The media type or link type of the response body for a PUT, POST, or PATCH operation.
responseItemType string false none The media type or link type of the items in the response body for a PUT, POST, or PATCH operation.
shell javascript python go