• Introduction
• General Information
• HTTP Headers
  • Security
  • Input Type
  • Output Format
• HTTP Body
  • Objects
    • Root Object
    • Profile Id
    • Profile Object
    • Profile Options Object
    • English Vocabulary Object
    • French Vocabulary Object
    • Vocabulary Item Object
    • Chart Object
    • Input Chart Object
    • Output Param Object
    • Dimension Info Object
    • Measure Info Object
    • Fact Object
    • Dimension Value Object
    • Measure Value Object
    • Selection Object
  • Enums
    • Chart Type Enum
    • Multi Series Enum
    • Lang Enum
    • Projection Enum
    • Meaning Of Up Enum
    • Gender Enum
• Output
  • HTTP Status Error Codes
    • 400: Bad Request
    • 401: Unauthorized
    • 500: Server Error
    • 503: Not Available
  • Complete Body Example
• Support
• Resources
• Release Note
• Algorithm considerations
  • Percentage usage
  • Input sorting check
  • Description of date format

Introduction

Yseop Savvy API provides tools to understand graphs, diagrams and charts, by generating clear and intelligible descriptions. It automatically explains what the charts, data and analysis mean and writes insights like a human being.

All the functionality of Yseop Savvy is accessible with our API. This API is mainly meant for BI purposes but can be used in various sectors, as it is flexible and not semantically bound to a specific domain (for more information, you can visit Yseop Savvy).

For now, it already has been integrated in Yseop Savvy for Qlik (plugin for Qlik Sense Desktop), and Yseop Savvy for Microsoft Excel (add-in for Microsoft Office 2010 and further).

General Information

Yseop Savvy API is a REST API. You can process tests using the Google Chrome Extension Postman (see more here).

For testing purposes, our API is available in a sandbox environment at the following URL: https://savvy-api.yseop-cloud.com/sandbox/api/v1/describe-chart

Please note that this sandbox environment is meant to make some tests with fair use. If you’re sending too many requests too quickly, you will get back a 429 error code.

To further optimize latency, the API is available in 2 regions:

• EU (Ireland, Europe) with domain name https://savvy-eu-api.yseop-cloud.com/sandbox/api/v1/describe-chart

• US (Oregon, USA) with domain name https://savvy-us-api.yseop-cloud.com/sandbox/api/v1/describe-chart

The generic domain savvy-api.yseop-cloud.com is using EU (Ireland, Europe) resources.

To call the API, you have to execute a POST call with HTTP Headers and Body.

HTTP Headers

Security

API calls are protected via HTTP Basic Authentication with an API key. Contact Yseop for getting your API key: Yseop Savvy. Once you’ve got your API key, use it as HTTP Basic username. Leave password empty.

For example, if the API key is ‘fooBar’ then the Authorization Header is formed as follows:

 Authorization="Basic Zm9vQmFyOg=="

(Base64(“fooBar:”) = “Zm9vQmFyOg==”)

For more information on HTTP Basic, you can read this page: https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side

Input Type

You need to indicate the input format, which is always json:

 Content-Type="application/json;charset=UTF-8"

Output Format

The output format has to be set as html:

 Accept="text/html"

HTTP Body

The HTTP Body contains a json document (charts information).

Objects

Root Object

Top-level object that provides all the necessary information to the application. There can be several charts descriptions, but one is mandatory.

{
    "extensionVersion": "2",
     "profile" : {
        "id" : "xx007xx"
    },
    "charts": [ ... ]
}

Profile Id

Contains the id of the currently used profile.

{
    "id" : "xx007xx"
}

Profile Object

Contains the raw profile to use with Savvy.

{
    "options" : {...},
    "vocabulary_en" : {...},
    "vocabulary_fr" : {...},
}

Profile Options Object

A Profile Options Object allows you to override some thresholds or default values use by Savvy. None of them are mandatory. You will find more explanations on each of this options in this file.

{
    "rangeDisplay" : true,
    "numberDecimalsCount" : 2,
    ...
}

English Vocabulary Object

This object allows you to override some English words or expressions used by Savvy when generating text in English. Using only one VocabularyItemObject in an array will just replace the word or expression, while an array of more than one element will allow you to add synonyms.

{
    "value": [ { "root": "value"}, { "root": "amount" }, ... ],
    "size": [ { "root": "length"} ],
    [...]
}

French Vocabulary Object

This object allows you to override some French words or expressions used by Savvy when generating text in French. Using only one VocabularyItemObject in an array will just replace the word or expression, while an array of more than one element will allow you to add synonyms.

{
    "valeur": [ { "root": "valeur", "gender": "FEMININE"}, { "root": "montant" }, ... ],
    "taille": [ { "root": "longueur", "gender": "FEMININE"} ],
    [...]
}

Vocabulary Item Object

Describes a vocabulary element.

{
    "root": "grandeur",
    "gender": "FEMININE"
}

Chart Object

Chart Information about dimensions, measures and facts.

{
    "inputChart":
    {
        "type": "LINE_CHART",
        "multiSeriesType": "UNRELATED"
    },
    "outputText":
    {
        "levelOfDetail":7,
        "lang":"en"
    },
    "dimensions":
    [{
        "label": "serie",
        "cardinal": 3
    }],
    "measures":
    [{
        "label": "sales",
        "defaultValue": "0",
        "meaningOfUp": "GOOD"
    }],
    "facts": [...]
}

Input Chart Object

Semantic information about the chart. Those meta-data are used to understand the relations between data.

{
    "type": "LINE_CHART",
    "mainDimensionIndex": 0,
    "multiSeriesType": "UNRELATED"
}

Output Param Object

Information about the expected output text.

{
    "levelOfDetail": 7,
    "lang": "en",
    "modeleProjection":"linear",
    "sizeTrend":2,
    "sizeProjection":2
}

{
    "levelOfDetail": 7,
    "lang": "en",
    "modeleProjection":external,
    "externalProjection":
        [1,
        2,
        3..]
}

Dimension Info Object

This object describes one of the dimensions of the chart. It is a part of the chart definition here.

Dimensions are the basis on which all calculations are performed. They are descriptive attributes, e.g. text fields, dates or discrete numbers. There can be several dimensions if charts aggregate several calculations.

{
    "label": "month",
    "othersLabel": "Others",
    "cardinal": 12
}

Measure Info Object

This object describes one of the measures of the chart. It is a part of the chart definition here.

Measures are the data computed for each dimension. They represent what will be visible in the chart.

{
    "label": "sales",
    "technicalLabel": false,
    "defaultValue": "0",
    "meaningOfUp": "GOOD",
    "unit": "$"
}

Fact Object

The Facts represent all the points of the chart: it is a matrix between the different dimensions, where values are measures.

{
    "dimensions":[
        { "index": 0, "label": "01/01/2015", "position": 0 },
        { "index": 1, "label": "United Kingdom", "position": 0 }
    ],
    "measures":[
        { "index": 0, "value": "150" }
    ]
}

Dimension Value Object

For each point, specify the value of one of the dimensions (used in Fact declaration, here).

{
    "index": 0,
    "label": "01/01/2015",
    "position": 0
}

In the case of data describing Sankey Charts, the Dimension Value Object format is the following:

{
    "index": 0,
    "label": "start, middle, end",
    "position": 0
}

Measure Value Object

For each point, specify the value of one of the measures (used in Fact declaration, here).

{
    "index": 0,
    "value": "150"
}

Selection Object

This object is used to describe the current selection (on other dimensions than the one of the data). Eg: the commented chart displays the sales by month, but only for the United Kingdom.

Note: It is not necessary to indicate selections for dimension(s) of the chart. Actually, they will be ignored.

{
    "field": "Region",
    "values": ["United Kingdom", "France"],
    "selectedElementCount": 15
}

Enums

Chart Type Enum

Currently, there are three main types of charts handled by the application. However, some more complicated charts (like points charts) can fit in one of those categories.

Multi Series Enum

Indicates if the measures are related to each other. For value vs reference, the value should be first and the reference second in the measure order.

Lang Enum

Output language for generated text. For now, English and French are available. Other languages are coming soon.

Projection Enum

Methods used for calculating the projection. For now the projected points follow a linear trend, additional methods are planned for future release.

Meaning Of Up Enum

Semantic information about the measures values. Specifies if high values should be interpreted with a positive or negative meaning.

Gender Enum

Information on the gender of a word used by the profiles.

Output

When all went well, the server returns the HTTP status code 200:

The ouput is returned in a HTML document. Here is an example of returned output:

<html xmlns:y="http://www.yseop.com/engine/3"
      xmlns:yt="http://www.yseop.com/text/2"
      xmlns:yp="http://www.yseop.com/profiling/1">
    <body>
        <div id="yseop-text">
            <div class="yseop-result">
                <div class="text-result">
                    This chart shows the Revenue for the following Product Sub Group Descs: Fresh Vegetables, Hot Dogs, Fresh Fruit, Frozen Vegetables, Sugar, Bologna, Coffee and 63 others.
                    <p></p><p></p>
                    What stands out in this situation is that a few Product Sub Group Descs account for
                    more than half of the total. There is obviously a dominant group of Product Sub Group Descs. This group is composed of six Product Sub Group Descs: Fresh Vegetables with
                    11.57 %, Hot Dogs with 9.51 %, Fresh Fruit with 8.60 %, Frozen Vegetables with 7.50
                    %, Sugar with 7.01 % and Bologna with 6.09 %.
                    <p></p><p></p>
                    Combined, the 64 other Product Sub Group Descs account for the rest of the list, accounting for 49.72 % of the total.
                    <p></p>
                    When taken together, the 70 Product Sub Group Descs amount to a total value of 67,119,290. The average is 958,847.
                    <p></p>
                </div>
                <span class="errors-and-warnings"></span>
            </div>
            <div class="technical-info">
                <div id="engineErrors"> Engine errors :<br></div>
                <div> Engine process time: <span id="processingTime">132.96</span>ms</div>
                <div> Timestamp: <span id="timestamp">2016-04-11T08:05:20:209</span></div>
                <div> Engine PID: <span id="enginePID">71D6</span></div>
                <div> KB Version: <span id="kbVersion">1.0.9</span></div>
            </div>
        </div>
    </body>
</html>

HTTP Status Error Codes

Here is a list of all the error messages you can receive if the text generation failed:

400: Bad Request

[
    {
        "level": "error",
        "schema": {
            "loadingURI": "#",
            "pointer": "/properties/charts/items/properties/inputChart"
        },
        "instance": {
            "pointer": "/charts/0/inputChart"
        },
        "domain": "validation",
        "keyword": "type",
        "message": "instance type (string) does not match any allowed primitive type (allowed: [\"object\"])",
        "found": "string",
        "expected": [
            "object"
        ]
    }
]

401: Unauthorized

<html>
    <head>
        <title>Apache Tomcat/7.0.52 (Ubuntu) - Error report</title>
        <style> ...</style>
    </head>
    <body>
        <h1>Etat HTTP 401 - </h1>
        <HR size="1" noshade="noshade">
        <p>
            <b>type</b> Status report
        </p>
        <p>
            <b>message</b>
            <u></u>
        </p>
        <p>
            <b>description</b>
            <u>This request requires HTTP authentication.</u>
        </p>
        <HR size="1" noshade="noshade">
        <h3>Apache Tomcat/7.0.52 (Ubuntu)</h3>
    </body>
</html>

500: Server Error

<?xml version="1.0" encoding="ISO-8859-1"?>
<y:output xmlns:y="http://www.yseop.com/engine/3">
    <y:data-end>
        <y:logging>
            <y:log level="error">
                <y:message>
                  JsonParseException Unexpected close marker ']':
                  expected '}' (starting at ... line: 1, column: 2434])
                  at ... line: 1, column: 2473]
                </y:message>
                <y:source name="yseop-manager"></y:source>
                <y:owner name="yseop-manager"></y:owner>
            </y:log>
        </y:logging>
    </y:data-end>
</y:output>

503: Not Available

Complete Body Example

{
    "extensionVersion": "2",
    "charts":
    [{
        "inputChart":
        {
            "type": "LINE_CHART",
            "mainDimensionIndex": 0,
            "mainDimensionOrdered": true,
            "multiSeriesType": "UNRELATED",
            "disableInterpolation": true,
            "disableAggregation" : false,
            "currentSelection":
            [{
                "field": "Region",
                "values": ["United Kingdom", "France"],
                "selectedElementCount": 15
            }]
        },
        "outputText":
        {
            "levelOfDetail":7,
            "persona":"MANAGER",
            "lang":"en",
            "modelProjection":"linear",
            "sizeTrend":2,
            "sizeProjection":2
        },
        "dimensions":
        [{
            "label": "month",
            "othersLabel": "Others",
            "cardinal": 24
        }],
        "measures":
        [{
            "label": "number of laser swords on Earth",
            "technicalLabel": false,
            "defaultValue": "0",
            "meaningOfUp": "GOOD",
            "unit":""
        }],
        "facts":
        [{
            "dimensions":[{ "index":0, "label":"01/01/2015", "position":0 }],
            "measures":[{ "index":0, "value":"150" }]
        },
        {
            "dimensions":[{ "index":0, "label":"01/02/2015", "position":1 }],
            "measures":[{ "index":0, "value":"124.5"}]
        },
        {
            "dimensions":[{ "index":0, "label":"01/03/2015", "position":2 }],
            "measures":[{ "index":0, "value":"150.64499999999998" }]
        },
        {
            "dimensions":[{ "index":0, "label":"01/03/2015", "position":3 }],
            "measures":[{ "index":0, "value":"150.64499999999998" }]
        },
        {
            "dimensions":[{ "index":0, "label":"01/04/2015", "position":4 }],
            "measures":[{ "index":0, "value":"150.64499999999998" }]
        },
        {
            "dimensions":[{ "index":0, "label":"01/05/2015", "position":5 }],
            "measures":[{ "index":0, "value":"150.64499999999998" }]
        },
        {
            "dimensions":[{ "index":0, "label":"01/06/2015", "position":6 }],
            "measures":[{ "index":0, "value":"150.64499999999998" }]
        },
        {
            "dimensions":[{ "index":0, "label":"01/07/2015", "position":7 }],
            "measures":[{ "index":0, "value":"54" }]
        },
        {
            "dimensions":[{ "index":0, "label":"01/08/2015", "position":8 }],
            "measures":[{ "index":0, "value":"150.64499999999998" }]
        },
        {
            "dimensions":[{ "index":0, "label":"01/09/2015", "position":9 }],
            "measures":[{ "index":0, "value":"40" }]
        },
        {
            "dimensions":[{ "index":0, "label":"01/10/2015", "position":10 }],
            "measures":[{ "index":0, "value":"30" }]
        },
        {
            "dimensions":[{ "index":0, "label":"01/11/2015", "position":11 }],
            "measures":[{ "index":0, "value":"20" }]
        },
        {
            "dimensions":[{ "index":0, "label":"01/12/2015", "position":12 }],
            "measures":[{ "index":0, "value":"1" }]
        }]
    }]
}

Support

If you encounter any trouble using this API, please contact us: Savvy.

Resources

Please find some files you can use for testing the API:

• the swagger file for this API
• the input schema file (you can use this file to check your input)
• an example of an input json file
• an example of a postman json file. Please note that you have to update the Authorization header with your key. This postman collection gives you access to three kind of examples:
  • A simple example
  • An example using a profile id
  • An other one using a profile object
• the description file of all values used by Savvy Profiles.

Release Note

Please find the Release Note here.

Algorithm considerations

Percentage usage

When the value "%" is used as unit in a measure definition, an automatic scale is applied to the data (0.1 will be displayed as 10%).

Input sorting check

The Savvy KB checks if the input is well sorted before starting the analysis. If it succeeds to enrich the dimensions labels and if the enriched objects are comparable (for example, dates are comparable), it uses that. Else, it uses the position specified in each DimensionFact. This sorting is enabled only if the dimension is ordered.

Description of date format

To be understood, a date must conform to the following pattern:

- "<calend>"
- "<calend>T<iso-8601-clock>"
- "<calend>T<iso-8601-clock>Z"
- "<calend>:<clock>"
- "Gmt <calend>:<clock>"

with <calend> conforming to one of the following patterns:
- yyyy/mm/dd (As a norm, you should privilege this format)
- dd/mm/yyyy
- dd/mmm/yyyy
- dd/mmm/yy
- dd month yyyy
- dd month yy
- dd/mm/aa
- yy/mm/dd
- dd/mm

with:
- <mm>: Integer between 1 and 12
- <mmm>: Three first letter of month name (case insensitive). For example apr for April, dec for December.
- <month>: Full name of the month (case insensitive)

and <clock> conforming to one of the following pattern:
- <hour>h<minute>'
- <hour>h<minute>
- <hour>h<minute>'<second>
- <hour>h<minute>'<second>

and <iso-8601-clock> conforming to one of the following pattern:
- <hour>:<minute>:<second>
- <hour>:<minute>

with:
- <hour>: Integer between 1 and 23
- <minute>: Integer between 1 and 59
- <second>: Integer between 1 and 59