#4.1 - Text analysis

REQUEST BODY SCHEMA 

application/json

Input POST body should either be application/x-www-form-urlencoded or raw JSON.

hyScore|analyze Endpoint: https://api.hyscore.io/v3/text  

 

POST BODY: v3/text ENDPOINT 

PARAMETER

DESCRIPTION

text

Required!

(added 20th April 2018)

Required! The text you want to be analyzed. Use instead of "url" parameter (see the example below!)
This field has a character limit of 50.000 characters. If you need to analyse larger texts, please split them up.

Only use with API endpoint:

https://api.hyscore.io/v3/text

Example (raw JSON):

{"text":"Your text", "lang":"en"}

---

confidence

Optional

(added 31st July 2019)

Type = Float 

Optional parameter.

Defines the minimum confidence that an entity is mentioned in a text. 

Value = in between '0.01' (low confidence) and '1' (high confidence), default value is '0.812'.

Example (raw JSON):

{"text":"Your text", "lang":"en",
"confidence":"0.812"}

Remark: As lower you set the confidence value as more possible entities will be recognized. Means you get more "keywords with a lower setting, but also more false/positive results. Depending on your use case and content to analyze you can adjust this value for your needs.

---

customData

Optional

Type = String

Optional parameter.

Can contain any custom information, identifier, etc. We don't save this information but return it in the response so that you e.g. can match the result, enrich your user-profiles and enhance data sets.

Example (raw JSON):

{"text":"Your text", "lang":"en",
"customData":"article0477-2019"}

{"text":"Your text", "lang":"de",
"customData":"&§!232-dsds_ASHDAS_9923?!!"}

{"text":"Your text", "lang":"en",
"customData":"[e-mail]"}

{"text":"Your text", "lang":"en",
"customData":"book1, topic2, page01"}

---

getText

Optional

Type = Boolean 

Optional parameter.

Defines if the API should return the text being analyzed. 

Value = True/False, default value is "False".

Example (raw JSON):

{"text":"Your text", "lang":"en",
"getText":"True"}

---

headings

Optional

(added 8th November 2018)

Type = String (Unicode)

Optional parameter.

Separator "," (Comma) 

You can send existing headings that should be considered in the analysis.

Example (raw JSON):

{"text":"Your text", "lang":"en",
"headings":"text headline h1, 
text headline h2", headline h3"}

---

lang Optional (recommended)

Type = String (Unicode) Optional parameter. Value = <country code>  "de" = German "en" = English Remark: We recommend sending the language setting with each text to be analyzed as a default setting. If, for example, a short German text contains a lot of anglicisms, it is possible that it will be classified as "en" (English) in the automatic speech recognition and the results may be suboptimal. Link: full list of supported languages and codes by hyscore. Examples (raw JSON): {"text":"Your text", "lang":"en"} {"text":"Dein Text", "lang":"de"} {"text":"Su texto", "lang":"es"} {"text":"Ваш текст", "lang":"ru"}

---

metaKeywords

Optional

(added 8th November 2018)

Type = String (Unicode)

Optional parameter.

You can send existing meta keywords which should be considered in the analysis.

Separator "," (Comma)

Example (raw JSON):

{"text":"Your text", "lang":"en", 
"metakeywords":"president, united States,
election"}

---

typelist

Optional

(added 31st July 2019)

Type = Boolean 

Optional parameter.

Value = True/False, default value is "False".

Example (raw JSON):

{"text":"Your text", "lang":"en", 
"typelist":"True"}

Example result:

"typelist": [
"Chancellor",
"Politician",
"Person",
"Agent"
]

Link: The possible entity type list is included as txt-file here.

---

wikitypes

Optional

(added 31st July 2019)

Type = Boolean 

Optional parameter.

Value = True/False, default value is "False".

Provides the wikidata type identifier for the entity (if possible).

You'll get the wikidata type "Q486972" (human settlement), e.g. https://www.wikidata.org/wiki/Q486972

Example request (raw JSON):

{"text":"Your text", "lang":"en", 
"wikitypes":"True"}

Example result:

"wikitypes": [
    "Q386724",
    "Q234460"
 ]

"wikitypes": [
 "None",
 ]

Optional: segments - please take a look at hyScore|segments documentation.

---

Example 

curl request example

curl -X POST \

  https://api.hyscore.io/v3/text \

  -H 'Authorization: Basic Og==' \

  -H 'Content-Type: application/json' \

  -H 'x-api-key: YOUR_API_KEY:_HERE' \

  -d '{"text": "TEXT TO BE ANALYZED", 
   "lang":"en",
      "metaKeywords":"METAKEYWORDS", 
      "headings":"HEADINGS1, HEADING2"}'

---