Dictanova Developer Portal

Empower your data with semantic analysis. Integrate new features of customer feedback analysis with the Dictanova API.

Get Started

Aggregate documents

This endpoint is use to perform powerful aggregations in the documents of a dataset. document.

Check out API Reference for this endpoint.

Also check out samples.

Request

Query Parameters

Query parameter
Description

q

This parameter is used as a full text criteria. The request will target only terms matching this criteria (exemple : q=product)

When this parameter is used, TERMS criteria in request body are ignored (query field).

This parameter works only with a minimum of 2 characters (except for Chinese where 1 character is enough)

Body

This sample body targets only documents related to stores in Paris, Nantes and Orléans and request NPS value for each month during periods 2017 and 2018. See the following section for full explanation on how to create a request.

curl -X POST \
/aggregation/datasets/DATASET_ID/documents \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "type" : "NPS",
    "field" : "metadata.npsscore",
    "query" : {
    	"field" : "metadata.magasin",
    	"operator" : "IN", 
    	"value" : ["Nantes", "Paris", "Orléans"]
    },
    "periods" : [
    	{
    		"field": "metadata.my_date",
        	"from": "2017-01-01T00:00:00Z",
        	"to": "2017-12-31T23:59:59Z"
    	},
    	{
    		"field": "metadata.my_date",
        	"from": "2018-01-01T00:00:00Z",
        	"to": "2018-12-31T23:59:59Z"
    	}
    ],
    "dimensions" : [
    	 {
            "field" : "metadata.magasin",
            "group" : "DISTINCT"
        },
        {
            "field" : "metadata.my_date",
            "group" : "MONTH"
        }
    ]
}
'

Reply

The reply contains an aggregated value for each of the periods and the dimensions requested. See section below to understand how the reply is built.

{
    "field": "metadata.npsscore",
    "type": "NPS",
    "periods": [
        {
            "period": {
                "field": "metadata.my_date",
                "from": "2017-01-01T00:00:00Z",
                "to": "2017-12-31T23:59:59Z"
            },
            "total": {
                "value": -14.16,
                "volume": 113
            },
            "values": [
                {
                    "value": 0,
                    "volume": 12,
                    "dimensions": [
                        "Nantes",
                        "2017-11"
                    ]
                },
                {
                    "value": -11.11,
                    "volume": 27,
                    "dimensions": [
                        "Nantes",
                        "2017-12"
                    ]
                },
                ...
            ]
        },
        {
            "period": {
                "field": "metadata.my_date",
                "from": "2018-01-01T00:00:00Z",
                "to": "2018-12-31T23:59:59Z"
            },
            "total": {
                "value": -7.42,
                "volume": 391
            },
            "values": [
                {
                    "value": -29.63,
                    "volume": 27,
                    "dimensions": [
                        "Nantes",
                        "2018-01"
                    ]
                },
                {
                    "value": 11.54,
                    "volume": 26,
                    "dimensions": [
                        "Nantes",
                        "2018-02"
                    ]
                },
                ...
            ]
        }
    ]
}

Build a request

Aggregation

The aggregation section defines the end result you are looking for. It is a composed of

  • a given field on which the aggregation will be done
  • an aggregation operation
Field
Description

createdAt

Creation date of document

updatedAt

Last update date of document

metadata.MTD_CODE

Metadata defined by code MTD_CODE in the dataset model.

externalId

Unique identifier

type

Type of document in predefined list

lang

Lang of document in list supported by Dictanova API

TERMS

List of terms contained in document (enriched by Dictanova Engine)

TOPICS

List of topics matching the document (enriched by Dictanova Engine)

Operations are detailed below

Operation
Description
Available for fields of type

COUNT
(default aggregation)

Count the number of documents having this field

NPS, CES, CSAT, Number, Datetime, LatLng, TERMS, TOPICS

Partial support for field of type String as it is mandatory to have an allowed values list to use this operation.

SUM

Simple sum of the values

NPS, CES, CSAT, Number

AVG

Calculate average of the values

NPS, CES, CSAT, Number

MAX

Return the maximum value (natural compare)

NPS, CES, CSAT, Number, Datetime

MIN

Return the minimum value (natural compare)

NPS, CES, CSAT, Number, Datetime

NPS

Return the NPS value (% of promoters - % of detractors)

NPS

CSAT

Return the CSAT value

CSAT (note that this is a synonym of AVG for this kind of fields)

CES

Return the CES value

CES (note that this is a synonym of AVG for this kind of fields)

Periods

If no period is provided, an implicit period is added on field createdAt with MIN and MAX values.

A period is composed of :

  • a field of Datetime type (createdAt, updatedAt or a metadata)
  • a lower bound (from)
  • an upper bound (to)

Values will be calculated for each period.

Dimensions

When no dimension is provided, the endpoint will return a single value for each period provided. This value is the global aggregation of all documents. In some cases, you may want to segment your data to retrieve multiple values (one for each segment). In this case, you have to provide dimensions.

Dimensions are composed of :

  • a field defining the dimension
  • a group defining an operation to group values of the field (see table below)
  • a limit defining how many values you want to get (default is 20, max is 100)
  • a range definition in case of a group = RANGE
Group
Available for fields of type
Description

DISTINCT

NPS, CSAT, CES, Number, String, TERMS, TOPICS, TERMS_POLARITY

Return a value for each distinct value of the field

For TERMS_POLARITY it means POSITIVE, NEGATIVE and NEUTRAL

RANGE

Number, CSAT, CES

Return a value for each range defined in the "ranges" field

NPS_GROUP

NPS

Predefined ranges corresponding to Promoters, Detractors and Passives groups

YEAR

Datetime

Return a value for each year of the given period

MONTH

Datetime

Return a value for each month of the given period

WEEK

Datetime

Return a value for each week of the given period

DAY

Datetime

Return a value for each day of the given period

POSITIVE

TERMS_POLARITY

Return a value for each term/topic in a positive context

NEGATIVE

TERMS_POLARITY

Return a value for each term/topic in a negative context

NEUTRAL

TERMS_POLARITY

Return a value for each term/topic in a neutral context

Dimensions samples :

[
  {
    "field": "...",
    "group": "DISTINCT",
    "limit": 5
  },
  {
    "field": "...",
    "group": "RANGE",
    "ranges": [
      {
        "name": "0 to 5",
        "min": 0,
        "max": 5
      }
    ]
  },
  {
    "field": "...",
    "group": "NPS_GROUP"
  },
  {
    "field": "...",
    "group": "MONTH"
  },
  {
    "field": "...",
    "group": "WEEK"
  },
  {
    "field": "...",
    "group": "DAY"
  },
  {
    "field": "TERMS",
    "group": "DISTINCT"
  },
  {
    "field": "TERMS_POLARITY",
    "group": "NEUTRAL"
  }
]

Read the reply

Let's detail each part of the the reply which is composed as followed :

{
    "type" : "...", 
    "field" : "...", 
    "periods" : 
    [
        {
            "period" : { ... },
            "total" : {...},
            "values" : 
            [
                {
                    "value" : "...",
                    "volume" : "...",
                    "dimensions" : [ "..." ]
                },
                ...
            ]
        },
        ...
    ]
}
Path
Contains

$.field

String

Echo the value of aggregation field of the request

$.type

String

Echo the value of aggregation type of the request

$.periods

Array

For each period requested, an element is added in the periods array of the reply. There is at least one period which is the default period if nothing was requested

$.periods[*].period

Period object

Echo the requested period from the request

$.periods[*].total.value

Number

Aggregation value for the whole period

$.periods[*].total.volume

Number

Volume of documents in the period

$.periods[*].total.values

Array

Aggregation values. This array contains one item for each combination of dimension value. If you have one dimension, there are as much items as there are values in the dimension. If you have 2 dimensions, the number of items is the size of the combination of values from dimension 1 and dimension 2, etc.

$.periods[].total.values[].dimensions

Array

Contains dimensions values in the same order as they are provided in the request

$.periods[].total.values[].volume

Number

Volume of documents matching the dimension combination

$.periods[].total.values[].value

Number

Aggregation value for dimensions combination