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	The scope object. The segment must be within the scope. NOTE: This method does not support the Global Search scope.	object, Mandatory
aggregations	An array that contains the aggregation IDs to calculate. Get the available IDs with this API call. Example to obtain results of 3 aggregations: { "scope": {....} "aggregations": [ { "id": "textModified", "interval": "week" }, { "id": "textStatus" }, { "id": "textModifiedByUser", "perLocale": false } ] }	array, Mandatory
query	An optional filter. See query parameter described here: resources/segments/search Important with TextLevel and TextLocaleLevel aggregations: Such aggregations operate on text/term fields and thus need to know the languages to look at. If you do not specify the query property then the system will do the calculations for ALL languages in the scope. If you specify a query then you MUST set the "languages" property and indicate the exact languages you want to analyse. Important: When specifying multiple languages in the query AND conditions on language level: Results are correct bur may appear unintuitive. See chapter MULTI-LANGUAGE QUERIES - SPECIAL NOTES further down this page.	object, Optional
usecache	Optional, default is true. True is performance optimized and caches information about the data of the scope. Set to false for example to make the system be aware of any changes to languages (e.g. languages added to a resource).	bool?, Optional

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	An object with the requested aggregation results. You will find one node per aggregation ID. Example: "aggregations": { "textModifiedByUser": { ... }, "textStatus": { ... }, "textBookmark": { ... } } See details below.	object
users	When an aggregation includes user IDs such as when analyzing total changes by user, then use this object to map user IDs to the user name and company name. Note: Users that are deleted will not show up. If you do not have the right to see user names you will also not get this information. Example: "users": { "1233": { "uid": 1233, "cid": 40, "uname": "Hans Glueck", "cname": "Trans Masters Ltd." }, "850": { "uid": 850, "cid": 61, "uname": "Javier Manon", "cname": "ABC Productions" } }	object?

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:

Browser not supported