Start analyze using TQL

Create a granular dataset in a secure web server for multiple Entities defined with a TQL query

This route allows a client to launch an analysis for data relevant to a list of entities using Textreveal query language (TQL).

The TextReveal Query Language (TQL) is a simple text-based query language for filtering data. It is composed with a field on which a value is applied: e.g, site_type: "news". Each filter can be combined to create a boolean expression with AND, OR and NOT operators.
Example: (text:"Apple TV" OR title:"Steve Jobs") AND NOT text:"apple tree"

The news site type groups standard_news, premium_news and licensed_news. Moreover, the workers are implicitly enabled if the associated parameter is used. For example, the quality score worker will be enabled if the qscore parameter is used.

premium_news and licensed_news site type might not be available for your account. Contact your account manager if this is not correct.

Valid TQL fields are:

site_type: the type of site (blogs, discussions, premium_news, licensed_news, standard_news, news) — NOT operator is not supported for this field
- news site_type groups standard_news, premium_news and licensed_news. This behavior is distinct from the news site type used in the dataset route.
text: the text content of the document
title: the title of the document
ner: Enable ner worker and annotate a keyword

Valid TQL operators are:

AND: logical AND
OR: logical OR
NOT: logical NOT
(): grouping

POST

https://api.textreveal.com/api/2.0/analyze/tql

Request Body

conceptsMap<string, string[]>
A dictionary containing the concepts with the concept as key and list of keywords as value. Commas are not allowed inside.
concepts_filterMap<string, string[]>
Same as concepts, but also used as filters.
end_date*date
The date when the analysis should end.
Example: "2019-02-01"
entities*object[]
languageanalyze-language-code
Language used for analysis (only one language allowed with TQL query)
Default: englishExample: "french"
min_matchnumber
At least min_match given keywords should be present in the resulted text.
Default: 1Example: 1
min_repeatnumber
The minimum number of time a keyword should be present in a text.
Default: 1Example: 1
qscorefloat
Quality score number.
Range: [0, 100]
sentiments_filterobject
Filter documents based on sentiment.
similarity_thresholdfloat
Similarity score threshold for recognized or matched entities. Filters out documents containing entities with a similarity score lesser than the threshold.
Range: [0, 1]
start_date*date
The date when the analysis should start.
Example: "2019-01-31"

Request

{
  "concepts": {
    "environment": [
      "environmental impact",
      "environmental controversy",
      "pesticide"
    ],
    "governance": [
      "offshore transaction",
      "dupery",
      "humbug"
    ],
    "pollution": [
      "fuel leakage",
      "greenhouse gases"
    ],
    "social": [
      "unscrupulous",
      "inequality",
      "malfeasance",
      "workplace violence"
    ]
  },
  "end_date": "2019-02-01",
  "entities": [
    {
      "annotate_keywords": [
        "Apple Inc.",
        "Steve Wozniak",
        "Apple Computer",
        "Ron Wayne",
        "AC Wellness",
        "FileMaker",
        "Braeburn Capital",
        "David Pakman",
        "AAPL",
        "Apple",
        "Steve Jobs",
        "apple.com"
      ],
      "context": "Apple is a technology company that designs, manufactures, and markets consumer electronics, personal computers, and software.",
      "entity_of_interest": "apple",
      "query": "((title:\"Apple Inc.\" AND text:\"Apple Inc.\") OR (title:\"Apple\" AND text:\"Apple\")) AND ner:\"Apple\""
    }
  ],
  "language": "english",
  "min_match": 2,
  "qscore": 90,
  "sentiments_filter": {
    "positive": {
      "min": 0.5
    }
  },
  "similarity_threshold": 0.5,
  "start_date": "2019-01-31"
}

{
  "concepts": {
    "environment": [
      "environmental impact",
      "environmental controversy",
      "pesticide"
    ],
    "governance": [
      "offshore transaction",
      "dupery",
      "humbug"
    ],
    "pollution": [
      "fuel leakage",
      "greenhouse gases"
    ],
    "social": [
      "unscrupulous",
      "inequality",
      "malfeasance",
      "workplace violence"
    ]
  },
  "end_date": "2019-02-01",
  "entities": [
    {
      "annotate_keywords": [
        "Apple Inc.",
        "Steve Wozniak",
        "Apple Computer",
        "Ron Wayne",
        "AC Wellness",
        "FileMaker",
        "Braeburn Capital",
        "David Pakman",
        "AAPL",
        "Apple",
        "Steve Jobs",
        "apple.com"
      ],
      "context": "Apple is a technology company that designs, manufactures, and markets consumer electronics, personal computers, and software.",
      "entity_of_interest": "apple",
      "query": "((title:\"Apple Inc.\" AND text:\"Apple Inc.\") OR (title:\"Apple\" AND text:\"Apple\")) AND ner:\"Apple\""
    }
  ],
  "language": "english",
  "min_match": 2,
  "qscore": 90,
  "sentiments_filter": {
    "positive": {
      "min": 0.5
    }
  },
  "similarity_threshold": 0.5,
  "start_date": "2019-01-31"
}

Response - 200

An identifier of the analysis to retrieve results

instanceuuid
The identifier of an analysis. This identifier have to be used to get results.
Example: "a62caf56-5961-4fff-ba2e-6d4dcf98960f"

Response

{
  "instance": "a62caf56-5961-4fff-ba2e-6d4dcf98960f"
}

{
  "instance": "a62caf56-5961-4fff-ba2e-6d4dcf98960f"
}

Error - 400

Bad request

_schemastring[]
The field where the error happened.
Example: "the field is required"

Response

{
  "_schema": [
    "the field is required"
  ]
}

{
  "_schema": [
    "the field is required"
  ]
}

Error - 404

Not Found

valuestring

Response

{
  "value": "string"
}

{
  "value": "string"
}

Error - 429

Too Many Requests

valuestring

Response

{
  "value": "string"
}

{
  "value": "string"
}

Generic errors are not shown, see Errors for more details.