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": [
            {
              "field": "metadata.my_store",
              "value": "Nantes"
            },
            {
              "field": "metadata.my_date",
              "value": "2017-11"
            }
          ]
        },
        {
          "value": -11.11,
          "volume": 27,
          "dimensions": [
            {
              "field": "metadata.my_store",
              "value": "Nantes"
            },
            {
              "field": "metadata.my_date",
              "value": "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": [
            {
              "field": "metadata.my_store",
              "value": "Nantes"
            },
            {
              "field": "metadata.my_date",
              "value": "2018-01"
            }
          ]
        },
        {
          "value": 11.54,
          "volume": 26,
          "dimensions": [
            {
              "field": "metadata.my_store",
              "value": "Nantes"
            },
            {
              "field": "metadata.my_date",
              "value": "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.

classifier.CLASSIFIER_CODE

Classifier defined by code CLASSIFIER_CODE

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

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

POLARITY_ALL

TERMS, TOPICS

Return a value for each term.topic in each context (neutral, positive, negative)

POLARITY_POSITIVE

TERMS, TOPICS

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

POLARITY_NEGATIVE

TERMS, TOPICS

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

POLARITY_NEUTRAL

TERMS, TOPICS

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": "TOPICS",
    "group": "POLARITY_ALL"
  }
]

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" : [ 
                      { 
                        "field" : "...", 
                        "value" : "..."
                      } 
                      , ...
                    ]
                },
                ...
            ]
        },
        ...
    ]
}
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[].dimensions[*].field

String

Name of the field of the dimension

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

String

Result value of the aggregation for the given field

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

String

In particular case of TERMS and TOPICS aggregation, value will be the label of the term or topic. The id is the corresponding term id or topic id allowing you to perform a query using this id.

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

String (neutral, positive or negative)

In particular case of TERMS and TOPICS aggregation, polarity indicates if the aggregation is only for a given polarity.

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

Number

Volume of documents matching the dimension combination

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

Number

Aggregation value for dimensions combination

Dimensions

Depending on your input, dimensions output will be slightly different. Here are samples replies for each dimensions.

// DISTINCT dimension
//request 
{
 	"field" : "my_field",
  "group" : "DISTINCT"
}
// reply
{
	"field" : "my_field",
  "value" : "value_of_field" // one for each value of my_field
}


// NPS_GROUP dimension
//request 
{
 	"field" : "my_nps_field",
  "group" : "NPS_GROUP"
}
// reply
{
	"field" : "my_nps_field",
  "value" : "promoters" // one for each value promoters, detractors, neutrals
}

// RANGE dimension
//request 
{
 	"field" : "my_field",
  "group" : "RANGE",
  "ranges" : [
    {
      "name" : "first_range",
      "min" : 0.0,
      "max" : 10.0
    }
   ]
}
// reply
{
	"field" : "my_field",
  "value" : "first_range" // one for each provided range
}

// YEAR dimension
//request 
{
 	"field" : "my_date_field",
  "group" : "YEAR"
}
// reply
{
	"field" : "my_date_field",
  "value" : "2018" // one for each year
}

// MONTH dimension
//request 
{
 	"field" : "my_date_field",
  "group" : "MONTH"
}
// reply
{
	"field" : "my_date_field",
  "value" : "2018-01" // one for each month
}

// WEEK dimension
//request 
{
 	"field" : "my_date_field",
  "group" : "WEEK"
}
// reply
{
	"field" : "my_date_field",
  "value" : "2018-W01" // one for each week
}

// DAY dimension
//request 
{
 	"field" : "my_date_field",
  "group" : "DAY"
}
// reply
{
	"field" : "my_date_field",
  "value" : "01" // one for each day of year
}

// POLARITY_ALL dimension
//request 
{
 	"field" : "TERMS",
  "group" : "POLARITY_ALL"
}
// reply
{
	"field" : "TERMS",
  "value" : "my term", // one for each term for each polarity
  "id" : "my_term_id", // can be use to perform a search
  "polarity" "positive" // one for each polarity neutral, positive, negative
}


// POLARITY_POSITIVE dimension
//request 
{
 	"field" : "TERMS",
  "group" : "POLARITY_POSITIVE"
}
// reply
{
	"field" : "TERMS",
  "value" : "my term", // one for each term for each polarity
  "id" : "my_term_id", // can be use to perform a search
  "polarity" "positive"
}

// POLARITY_NEGATIVE dimension
//request 
{
 	"field" : "TOPICS",
  "group" : "POLARITY_NEGATIVE"
}
// reply
{
	"field" : "TOPICS",
  "value" : "my topic", // one for each term for each polarity
  "id" : "my_topic_id", // can be use to perform a search
  "polarity" "negative"
}

// POLARITY_NEUTRAL dimension
//request 
{
 	"field" : "TOPICS",
  "group" : "POLARITY_NEUTRAL"
}
// reply
{
	"field" : "TOPICS",
  "value" : "my topic", // one for each term for each polarity
  "id" : "my_topic_id", // can be use to perform a search
  "polarity" "neutral"
}

Aggregate documents


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.