BA statistics for multiple documents

Description

This method retrieves BA (Business Analytics) statistics for multiple documents in a single call.

It provides information on:

Who edited how many texts
Time spent on translations and edits
Quality metrics and scores

URL

CODE

(POST) /resources/statistics/ba/batch

PARAMETERS

The body must contain a JSON object.

Example request

CODE

{
  "scope": { "projectId": 123 },
  "locale": "fr-FR",
  "dids": [1001, 1002, 1003]
}

Another example, retrieving BA statistics for all documents in scope:

CODE

{
  "scope": { "projectId": 123 },
  "locale": "fr-FR"
}

Body properties

Parameter	Description	Required
scope	The Scope (Object). Note that if you use a document set or global search scope, you will receive `"available": false` because these scopes do not support files.	Mandatory
dids	Optional array of document IDs (1–100 distinct integers). If omitted, retrieves statistics for all documents in scope (capped at 100).	Optional
locale	The language to get statistics for.	Mandatory

Validation

locale is required and must be available in the scope.
If dids is provided, it must contain between 1 and 100 distinct integer document IDs.
All document IDs in dids must exist within the project scope.
If any document is not found, an error is returned:
Document {did} not found in the project scope.

RESULTS

The API returns a JSON array of objects, one per document.

Each array item has these properties:

Property	Description
did	Document ID.
name	Document name.
stats	The BA statistics object (same structure as the single BA endpoint result). See resources/statistics/ba.
error	Present and set to `true` if statistics could not be retrieved for this document.

If error is true, stats may be missing or incomplete for that item.

DATA STRUCTURES

Editors node

The editors element is an array of objects with these properties.
The last array element contains the grand totals.

Property	Description
editor	Internal code for the type of editor.
title	Title of editor.
segments	Segment counts: `initial` (when marking for translation), `current`, `unchanged`, `translation`, `postEditing`, `revision`.
words	Word counts: `initial`, `current`, `unchanged`, `translation`, `postEditing`, `revision`.
actions	Total number of interventions.
actionsCorrections	Total number of interventions correcting a previous text.
scores	Array of document-level scores. See Scores node below.

Workers node

The workers element is an array of objects with these properties.
The last array element contains the grand totals.

Property	Description
pid	Person ID. `null` if the current user is not authorized to see this.
cid	Company ID. `null` if the current user is not authorized to see this.
pname	Person name. `null` if the current user is not authorized to see this.
pcode	Person code. `null` if the current user is not authorized to see this.
cname	Company name. `null` if the current user is not authorized to see this.
segments	Object with various segment counts: `total`, `corrected`, `translation`, `postEditing`, `revision`.
words	Object with various word counts: `total`, `corrected`, `translation`, `postEditing`, `revision`.
dtfirst	First edit date in document.
dtfirstt	First edit date as a string.
dtlast	Last edit date in document.
dtlastt	Last edit date as a string.
scores	Array of document-level scores. See Scores node below.

Scores node

Each scores element is an array of objects with these properties:

Property	Description
title	Print title for the score.
value	Decimal value of the score. Can be `null` if the score could not be calculated (lack of data).
unit	`null` or the unit of the score, for example `%` for percentages.
desc	Description of the score and its purpose. This text adapts to the actual score value.
max	Maximum value the score can have.

ACCESS CONTROL

The logged user must have access to BA data.

See Rights (Object), property canViewBA which must be true.

EXAMPLES

Example request

CODE

{
  "scope": { "projectId": 123 },
  "locale": "fr-FR",
  "dids": [1001, 1002, 1003]
}

Example response (batch documents – simple)

CODE

[
  {
    "did": 1001,
    "name": "Document1.docx",
    "stats": {
      "segments": { "error": 0, "ok": 0, "missing": 0, "filled": 4, "total": 4 },
      "words": { "error": 0, "ok": 0, "missing": 0, "filled": 8, "total": 8 },
      "dtfirst": "2017-02-06T07:09:09.8944871Z",
      "dtlast": "2017-02-06T07:09:22.4785955Z",
      "dtfirstt": "06/02/2017 08:09 UTC+1",
      "dtlastt": "06/02/2017 08:09 UTC+1",
      "editors": [],
      "workers": [],
      "scores": []
    }
  },
  {
    "did": 1002,
    "name": "Document2.docx",
    "stats": {}
  },
  {
    "did": 1003,
    "name": "Document3.docx",
    "error": true
  }
]

Example response (batch documents – detailed)

CODE

[
  {
    "did": 1001,
    "name": "Document1.docx",
    "stats": {
      "segments": {
        "error": 0,
        "ok": 0,
        "missing": 0,
        "filled": 4,
        "total": 4
      },
      "words": {
        "error": 0,
        "ok": 0,
        "missing": 0,
        "filled": 8,
        "total": 8
      },
      "dtfirst": "2017-02-06T07:09:09.8944871Z",
      "dtlast": "2017-02-06T07:09:22.4785955Z",
      "dtfirstt": "06/02/2017 08:09 UTC+1",
      "dtlastt": "06/02/2017 08:09 UTC+1",
      "editors": [
        {
          "editor": "None",
          "title": "Not translated",
          "segments": {
            "initial": 4,
            "unchanged": 0,
            "translation": 4,
            "postEditing": 0,
            "revision": 0,
            "current": 0
          },
          "words": {
            "initial": 8,
            "unchanged": 0,
            "translation": 8,
            "postEditing": 0,
            "revision": 0,
            "current": 0
          },
          "actions": 4,
          "actionsCorrections": 0,
          "scores": [
            {
              "title": "Work quality",
              "value": 10.0,
              "unit": null,
              "desc": null,
              "max": 10.0
            }
          ]
        },
        {
          "editor": null,
          "title": "TOTAL",
          "segments": {
            "initial": 4,
            "unchanged": 0,
            "translation": 4,
            "postEditing": 0,
            "revision": 0,
            "current": 4
          },
          "words": {
            "initial": 8,
            "unchanged": 0,
            "translation": 8,
            "postEditing": 0,
            "revision": 0,
            "current": 8
          },
          "actions": 4,
          "actionsCorrections": 0,
          "scores": [
            {
              "title": "Work quality",
              "value": 10.0,
              "unit": null,
              "desc": null,
              "max": 10.0
            }
          ]
        }
      ],
      "workers": [
        {
          "pid": 7,
          "cid": 1,
          "pname": "Stephan Bohmig",
          "pcode": "SB",
          "cname": "Pons",
          "segments": {
            "total": 4,
            "translation": 4,
            "postEditing": 0,
            "revision": 0,
            "corrected": 0
          },
          "words": {
            "total": 8,
            "translation": 8,
            "postEditing": 0,
            "revision": 0,
            "corrected": 0
          },
          "dtfirst": "2017-02-06T07:09:09.8944871Z",
          "dtlast": "2017-02-06T07:09:22.4785955Z",
          "dtfirstt": "06/02/2017 08:09 UTC+1",
          "dtlastt": "06/02/2017 08:09 UTC+1",
          "scores": [
            {
              "title": "Work quality",
              "value": 10.0,
              "unit": null,
              "desc": null,
              "max": 10.0
            }
          ]
        },
        {
          "pid": 0,
          "cid": 0,
          "pname": "TOTAL",
          "pcode": "TOTAL",
          "cname": null,
          "segments": {
            "total": 4,
            "translation": 4,
            "postEditing": 0,
            "revision": 0,
            "corrected": 0
          },
          "words": {
            "total": 8,
            "translation": 8,
            "postEditing": 0,
            "revision": 0,
            "corrected": 0
          },
          "dtfirst": "2017-02-06T07:09:09.8944871Z",
          "dtlast": "2017-02-06T07:09:22.4785955Z",
          "dtfirstt": "06/02/2017 08:09 UTC+1",
          "dtlastt": "06/02/2017 08:09 UTC+1",
          "scores": [
            {
              "title": "Work quality",
              "value": 10.0,
              "unit": null,
              "desc": null,
              "max": 10.0
            }
          ]
        }
      ],
      "scores": [
        {
          "title": "Completed",
          "value": 100.0,
          "unit": "%",
          "desc": "Percentage translations supplied and not marked errorneous.",
          "max": 0.0
        },
        {
          "title": "Human translation quality",
          "value": 10.0,
          "unit": null,
          "desc": "0 out of 4 human translated or post-edited segments required correction.",
          "max": 10.0
        },
        {
          "title": "Overall Efficiency",
          "value": 5.0,
          "unit": null,
          "desc": "4 segments required a total of 4 human interventions.",
          "max": 10.0
        }
      ]
    }
  },
  {
    "did": 1002,
    "name": "Document2.docx",
    "stats": {
      "segments": {
        "error": 0,
        "ok": 2,
        "missing": 1,
        "filled": 2,
        "total": 3
      },
      "words": {
        "error": 0,
        "ok": 5,
        "missing": 2,
        "filled": 5,
        "total": 7
      },
      "dtfirst": "2017-02-07T10:15:00.0000000Z",
      "dtlast": "2017-02-07T11:30:00.0000000Z",
      "dtfirstt": "07/02/2017 11:15 UTC+1",
      "dtlastt": "07/02/2017 12:30 UTC+1",
      "editors": [],
      "workers": [],
      "scores": []
    }
  },
  {
    "did": 1003,
    "name": "Document3.docx",
    "error": true
  }
]