resources/statistics/aggregations (POST)

To obtain results for one or more aggregations. 

URL

(POST) /resources/statistics/aggregations

PARAMETERS

The parameters are a JSON object included in the request body:

{
   "scope": {....}
   "aggregations": [
		{ "id": "textModified", "interval": "week" },
		{ "id": "textStatus" },
		{ "id": "textModifiedByUser", "perLocale": false }
	]
}

Languages and filters

For any text level aggregations, the system requires the languages to look in (source and target languages).

• If you do not set the query property: The system will do the calculations for ALL languages in the scope.
• If you set the query property: You MUST set the query.languages property and indicate the exact languages you want to analyse.

Example 1: Auto-selects all project languages:

{
	"scope": { "type": "Project", "projectid": 3576 },
	"aggregations": [ { "id": "textModified" } ]
}

Example 2: Specify languages:

{
	"scope": { "type": "Project", "projectid": 3576 },
	"query": { 
		"languages": [ 
			{ "locs": [ "en", "fr" ]  } 
		] 
	},
	"aggregations": [ { "id": "textModified" } ]
}

Example 3: Specify languages and language specific filters. Here we only filter texts with a red status in the French and Spanish target languages.

{
	"scope": { "type": "Project", "projectid": 3576 },
	"query": { 
		"languages": [ 
			{ "locs": [ "en" ]  }, 
			{ "locs": [ "fr" ], "status": [1] },
			{ "locs": [ "es" ], "status": [1] },
		] 
	},
	"aggregations": [ { "id": "textModified" } ]
}

RESULTS

The result is a JSON object:

"aggregations": {
	"textModifiedByUser": { ... },
	"textStatus": { ... },
	"textBookmark": { ... }
}

"users": {
	"1233": { "uid": 1233, "cid": 40, "uname": "Hans Glueck", "cname": "Trans Masters Ltd." },
	"850": { "uid": 850, "cid": 61, "uname": "Javier Manon", "cname": "ABC Productions" }
}

Depending on the type of aggregation, the result may vary.

Segment level aggregation results

A typical result may look like this:

"textModifiedByUser": {
            "buckets": [ 
				{ "key": 1233, "count": 100 },
				{ "key": 850, "count": 350 },
			],
            "total": 450,
            "scanned": 450,
            "scannedErrors": 0
}

• The buckets node shows the count per user ID (key).
• The aggregation is for user IDs and you will thus find the users node (see further up) to get the names of these users.
• total is the total count in the buckets
  
  
• scanned is a technical information and should not be displayed to end users. It indicates the total number of segments that were scanned to calculate the aggregations. 
• scannedErrors is a technical information indicating how accurate scanned is. For example a value of 10 means that the shown total is +/- 10.

Text level aggregation results

Locale level aggregations will contain nodes per each analyzed language.

To rather count all languages together set the perLocale parameter for the aggregation to false. 

"localeBookmark": {
	"de": {
		   "buckets": [
			{ "key": 0, "count": 120, "title": "No bookmark" },
			{ "key": 1, "count": 0, "title": "Blue" },
			{ "key": 2, "count": 15, "title": "Red" }
		],
		"total": 135,
		"scanned": 135,
		"scannedErrors": 0
	},
	"es": {
 		   "buckets": [
			{ "key": 0, "count": 100, "title": "No bookmark" },
			{ "key": 1, "count": 10, "title": "Blue" },
			{ "key": 2, "count": 25, "title": "Red" }
		],
		"total": 135,
		"scanned": 80,
		"scannedErrors": 0
	}
}

• The results are shown for languages en and es
• The buckets node shows the count per numeric bookmark ID (key). For convenience the bookmark title is printed.
• total is the total count in the buckets
  
  
• scanned is a technical information and should not be displayed to end users. It indicates the total number of segments that were scanned to calculate the aggregations. 
• scannedErrors is a technical information indicating how accurate scanned is. For example a value of 10 means that the shown total is +/- 10.

MULTI-LANGUAGE QUERIES - SPECIAL NOTES

Text-level aggregations may yield a-priori unintuitive results when a query defines multiple languages and also has conditions on language properties. Example:

"query": {
        "languages": [
            {
                "locs": ["en-GB","de-CH","fr-CH","it-IT"],
                "updateDate": { "min": "2020-12-14T00:00:00", "max": "2020-12-14T23:59:59" }
            }
        ]
    }

In fact, this query selects segments where at least 1 language matches the conditions (on the last update date in the example above). 1 language in a segment might match the condition but maybe the other 2 languages do not.  Now, if you requested a text-level aggregation then you should be aware that all the 3 languages will be aggregated - whether they matched the condition above or not.

A typical example would be the "textModified" aggregation. If "en-GB" was modified on 2020-12-14 in a segment it will be aggregated for that date. If the other languages in the same segment were aggregated on 2020-12-01 then these will be aggregated into this date bucket.  The result is correct but you probably did not expect date buckets outside the requested range.

If this is problematic for your use case then please specify a single language in the query (or run separate aggregations per each language).

EXAMPLES

See here:

• Aggregation Example: Counts by status
• Aggregation Example: Counts by users
• Aggregation Example: Counts by date