Skip to content

Temporal information detector output

Introduction

The Temporal information detector API resource returns a JSON object with this format:

{
    "success": Boolean success flag,
    "data": {
        "content": analyzed text,
        "language": language code,
        "version": technology version info,
        "knowledge": [],
        "paragraphs": [],
        "sentences": [],
        "phrases": [],
        "tokens": [],
        "entities": [],
        "extractions": [],
        "extraData": {}
    }
}

For a description of the contents, language and version properties, see the API resources output overview.

The main output is the extradata object and normally you can ignore all the rest because its only functional to the production of that object.
However, you'll need to consider also the sentences array if you want to create a visualization in which sentences containing temporal information expressions are highlighted in the text.

If you are still interested, consider that output arrays are the product of other API capabilities, so:

extraData object

If you have this input text:

I first traveled to Australia in 2004. I returned seven years later. After that, I lived in New Zealand from February 2013 to November 2014.

this is an example of the extraData object you can obtain:

"extraData": {
    "script-version": "v1.1.0 rev. 2021-07-20T13:58:19.796Z",
    "JSON-LD": {
        "@context": {
            ...
        },
        "@graph": {
            "@id": "TemporalInformation",
            "items": [
                {
                    "@id": "3411a0251418664029e3e2c6cb01f70b",
                    "@type": "schema:PropertyValue",
                    "name": "TimePoint",
                    "value": "2004",
                    "matches": [
                        {
                            "@id": "008743bc89848b9d52537c9b52362e27",
                            "start": 33,
                            "end": 37,
                            "sentence": 0,
                            "text": "2004"
                        }
                    ]
                },
                {
                    "@id": "3a495e7fda460928c1f56a022d519d54",
                    "@type": "schema:PropertyValue",
                    "name": "TimePoint",
                    "value": "2011",
                    "matches": [
                        {
                            "@id": "1fd2bcd8b1f2b96fc4c15e7447e6c634",
                            "start": 50,
                            "end": 67,
                            "sentence": 1,
                            "text": "seven years later",
                            "derived": true,
                            "referenceTimePoint": "008743bc89848b9d52537c9b52362e27",
                            "referenceTimeSpan": "11620a7b84820db2e05f8824fd4b10cd"
                        }
                    ]
                },
                {
                    "@id": "42850d057130d3162cf6f8f0707bcc3e",
                    "@type": "schema:PropertyValue",
                    "name": "TimeInterval",
                    "value": "2013-02/2014-11",
                    "matches": [
                        {
                            "@id": "d745613c4b3b182f73cc0173e26879fd",
                            "start": 104,
                            "end": 139,
                            "sentence": 2,
                            "text": "from February 2013 to November 2014"
                        }
                    ]
                },
                {
                    "@id": "e7d7ffa0181dba4317d6077d873e7675",
                    "@type": "schema:PropertyValue",
                    "name": "TimePoint",
                    "value": "2013-02",
                    "matches": [
                        {
                            "@id": "766fe2f27808dccabba5f7fb065248d8",
                            "start": 104,
                            "end": 122,
                            "sentence": 2,
                            "text": "from February 2013"
                        }
                    ]
                },
                {
                    "@id": "6a5825809662d2ca7d7f851f95349cac",
                    "@type": "schema:PropertyValue",
                    "name": "TimePoint",
                    "value": "2014-11",
                    "matches": [
                        {
                            "@id": "f9cdca3b7b7e5e0614d717a2e03dc2e7",
                            "start": 123,
                            "end": 139,
                            "sentence": 2,
                            "text": "to November 2014"
                        }
                    ]
                },
                {
                    "@id": "a5f53924b0dc85e3f44a02dbf2f2ddc1",
                    "@type": "schema:PropertyValue",
                    "name": "TimeSpan",
                    "value": "+ 7 year",
                    "matches": [
                        {
                            "@id": "11620a7b84820db2e05f8824fd4b10cd",
                            "start": 50,
                            "end": 67,
                            "sentence": 1,
                            "text": "seven years later"
                        }
                    ]
                }
            ]
        }
    }
}

script-version is the version of the scripting engine used by the detector, normally you can ignore it.
JSON-LD is a JSON-LD object. For the description of the JSON-LD format refer to the official documentation.

The @graph property of the JSON-LD object has two properties:

  • @id: object identifier, is always TemporalInformation
  • items: array containing the temporal information

The information items

Detected temporal information is stored in the items array.
Each member of the array represents all the detected instances of a temporal information.
Item properties are:

  • @id: unique identifier
  • @type: schema.org type
  • name: type of time expression, which is:

  • value: normalized information value

  • matches: occurrences of the information in the text. Each array item corresponds to a part of the text and has these properties:

    • @id: unique identifier
    • start: zero-based position of the first character of the portion of text expressing the information
    • end: zero-based position of the character after the last of the portion of text expressing the information
    • sentence: index inside the sentences array of the sentence containing the occurrence
    • text: portion of text expressing the information
    • (Optional, for time points) derived: when this property is present, its value is always true, indicating the match refers to a time point that has been derived from other time expressions
    • (Optional, for time spans) indefiniteQuantity: when present, its value is the portion of text that expresses the indefinite quantity, for example the word some
    • (Optional, for time spans) duration: when present, its value is the portion of text indicating the time span represents a duration, for example the word for in for seven years
    • (Optional, for derived time points) referenceTimePoint: the @id value of the items array member with name equal to TimePoint acting as the base time point from which the match was derived
    • (Optional, for derived time points) referenceTimeSpan: the @id value of the items array member with name equal to TimeSpan acting as the time span added to—or subtracted—from the base time point to derive the match