#5 : Result and Response

  • Updated
Follow

The response is in JSON format and contains the following fields:

 

RESPONSE (DEFAULT)

It contains the status of the API request and the analysis result.

 

STATUS

PARAMETER KEY/FIELD VALUE/RESPONSE DESCRIPTION
status
  • message
  • code
  • type
  • "message" = system message
  • "code" = status code
  • "type" = string, value is:
    • "No data" yet: URL is not known yet by hyScore, needs to be analyzed.
    • "Ok": request was successful, all seems well.
    • "Error": an error occurred, see status codes, e.g. 404 - URL not found.
    • "Incomplete": the analysis is not completed yet, the reason might be e.g. a categorization issue. try again or come back later. 

Example:

  "status": {
        "message": "All seems well.",
        "code": 1,
        "type": "Ok"
    },
 
Please take a look at chapter #5.1 Result and Response: Status messages & codes for more information.
 

 

RESULT

Categories "hyScore"

PARAMETER KEY/FIELD VALUE/RESPONSE DESCRIPTION
result
  • categories
    • hyscore
  • "hyscore" = hyscore categories; the weighted categories of a URL or Text. 
  • Max. weight: 100
  • The category with the highest weight is more valid as the one with the lower weight.

 

Categories "IAB"

PARAMETER KEY/FIELD VALUE/RESPONSE DESCRIPTION
result
  • categories
    • iab
  • "iab" = Categories in official IAB taxonomy; the weighted IAB Codes of a URL or Text. 
  • "category": Topic, just for better manual debugging.
  • "v1" - IAB Code in IAB Taxonomy v1
  • "v2" - Unique IAB Code of the IAB Taxonomy v2 (Tier1 to Tier 4)
  • "v2-parent" - IAB Code category Tier1 of the IAB Taxonomy v2
  • "weight" - Max. weight: 100 - Usually a weight value of 18 to 20 plus is valid. 
  • The category with the highest weight is more valid as the one with the lower weight.

Example:

 "iab": [
         {
          "category": "Law, ...",
          "v1": "IAB11-4",
          "v2": 386,
          "v2-parent": 379,
          "weight": 22.679
                },
                {
          "category": "Education",
          "v1": "IAB5",
          "v2": 132,
          "v2-parent": 132,
          "weight": 22.455
                }
]

 

"customData"

PARAMETER KEY/FIELD VALUE/RESPONSE DESCRIPTION
result
  • customData

  • "customData": is an additional custom field. The key/value appears if the customData input field is used in the POST request.

    Any format allowed (numeric, strings), e.g. “23D-XZ-2300” or “user@domain.com”; values can be separated by commas. 

  •  Note: the information is just looped through the system. hyScore do not store or cache this information elsewhere. Depending on specific use cases it is possible in agreement with the customer.

Example:

"customData": "UserA,$1234",

 

 "debug"

PARAMETER KEY/FIELD VALUE/RESPONSE DESCRIPTION
result
  • debug

  • "debug": is just for debug information. Occurs if the parameter "getText":"True" is not set in the POST request. See the response description for "text". 

Example:

"debug": "Text field deactivated. ",

 

"description"

PARAMETER KEY/FIELD VALUE/RESPONSE DESCRIPTION
result
  • description

  • "description": contains the meta description set by the publisher for the specific content URL.

Example:

"description": "Breaking News...",

  

"headings"

PARAMETER KEY/FIELD VALUE/RESPONSE DESCRIPTION
result
  • headings

  • "content": extracted Headline(s) from the content single URL in order the <h> tag.

  • "tag": <h1> to <h4> tag

Example:

"headings": [
    {"content": "Breaking News...",
     "tag": "h1" },
    {"content": "Subheadline...",
     "tag": "h2" }]

 

"image"

PARAMETER KEY/FIELD VALUE/RESPONSE DESCRIPTION
result
  • image
  • "image": image URL of the main article image - if available. Either chosen automatically via the POST request "imageDiv" - parameter.

Example:

"image": "https://www.123.de/001.jpg"

 

"language"

PARAMETER KEY/FIELD VALUE/RESPONSE DESCRIPTION
result
  • language
  • "language": the language of the given content/text is determined automatically by the system:
     
    • "cn": Chinese (CN)
    • "cz": Czech (CZ)
    • "de": German (DE)
    • "da": Dansk (DK)
    • "en": English (EN)
    • "es": Spanish (ES)
    • "fi": Finish (FI)
    • "fr": French (FR)
    • "hu": Hungarian (HU)
    • "in": Hindi (IN)
    • "it" : Italien (IT)
    • "nl": Dutch (NL)
    • "no": Norway (NO)
    • "pl": Polish (PL)
    • "pt" : Portuguese (PT)
    • "ru": Russian (RU)
    • "se": Swedish (SE)
    • "tr": Turkish (TR)
  • full list of supported languages. 
  • Other languages might be recognized by the system, but we don't support the categorization and/or the keyword analysis for them yet.
  • Please get in touch with hyScore, if you are looking for additional language(s).
  • Note: If a publisher sets a language value in the header information of the website, the analysis will be performed in the provided language. 

Example:

"language": "en"

  

"metaKeywords"

PARAMETER KEY/FIELD VALUE/RESPONSE DESCRIPTION
result
  • metaKeywords
  • "metaKeywords": the given meta keywords - if exists - of the content URL set by its publisher (not weighted).

Example:

"metaKeywords": "Trump, Washington"

   

"readTime"

PARAMETER KEY/FIELD VALUE/RESPONSE DESCRIPTION
result
  • readTime
  • "readTime": it will take the average reader to read the extracted text/article in MM:SS format. 

Example:

"readTime": "01:42"

 

"segments" (Add-On)

PARAMETER KEY/FIELD VALUE/RESPONSE DESCRIPTION
result
  • segments
  • "segments": hyScore|segment is an add-on function of hyScore|analyze that allows you to create and manage individual keyword segments in over 20 languages via hyScore|cockpit-Frontend. The segments you set up are taken into account in the content analysis and, if applicable (match), are listed separately in the analysis results. Contact us to activate it for you.

Example:

 "segments": [
         {
          "match_count": 9,
          "segmentid": "segment_CA",
          "match_unique": 3,
          "iab-v2": 297,
          "matched": true,
          "keywords_in_segment": 65
           }
        ],

 

 

 "sentiment"

PARAMETER KEY/FIELD VALUE/RESPONSE DESCRIPTION
result
  • sentiment
  • "sentiment": By default, hyScore analyze the sentiment/tonality of the whole content of the URL/text. 
  • Sentiment has a value between +1 (positive), 0 (neutral) and -1 (poor, negative).
  • Remark: the default hyScore|analyze core solution is optimized on editorial content. If needed, we can offer additional products/analysis to determine the sentiment of the keywords and phrases too (add-on).
  • The value for editorial content is often in a range between -0.2 and +0.2 (neutral). Depending on the use case it's up to the client which values are used to mark a text either positive, neutral or negative.

Best practice: 

  • 1 to 0.5 = super positive
  • 0.49 to 0.21 = positive
  • 0.2 to -0.2 = neutral
  • -0.21 to -0.49 = negative
  • 0.5 to 1 = super negative

Example:

"sentiment": 0.30833333333333335,

 

"text"

PARAMETER KEY/FIELD VALUE/RESPONSE DESCRIPTION
result
  • text
  • "text": the article text that was extracted and analyzed (if parameter “getText=True” is set in the POST request). 
  • Parameter "getText" is set by default to "False". Instead of "text" you'll get the key/value "debug" - see above.

Example:

"text": "In 2020 the market..."

 

"textlength"

PARAMETER KEY/FIELD VALUE/RESPONSE DESCRIPTION
result
  • textlength
  • "textlength": number of chars in the analyzed text.
  • An image/picture gallery has often less text and lower keyword scores.
  • An article with more text and much more chars provide a higher ranked keyword score.
  • You can use the text length as an on factor/indicator for your e.g. decision engine (e.g. use cases: site quality, etc.)

Example:

"textlength": 4321,

 

"weightedKeywords"

PARAMETER KEY/FIELD VALUE/RESPONSE DESCRIPTION
result
  • weightedKeywords
  • Contains the keywords/entities extracted from the input. Keywords are displayed in their normalized form. Each entry consists of: 

    • "type": The type of the keyword/entity if determined, e.g. “Keyword, Country, VideoGame, Person, …”
    • "name": The actual keyword (normalized). 
    • "surface_form": the actual keyword how it is written on the website/text and a user would see/read it.

      The surface_form is a list element in the JSON response.
    • "weight": the weight of the keyword. The higher this value is, the more relevant the entry is to the given content (max. weight: 10).
    • "frequency": the number of times the keyword/entity appears in the text. List is sorted by weight.

Example:

"weightedKeywords": [
    {
    "surface_form": [
    "Trump",
    "Donald Trump"
    ],
    "frequency": 4,
    "type": "President",
    "name": "Donald Trump",
    "weight": 5.017921146953405
    },
    {
    "surface_form": [
    "Corona"     
    "coronavirus",
    "Coronavirus"
     ],
    "frequency": 3,
    "type": "Keyword",
    "name": "Coronavirus",
    "weight": 4.014336917562725
     }


"tld"

PARAMETER KEY/FIELD VALUE/RESPONSE DESCRIPTION
result
  • tld
  • "tld": the Top Level Domain (tld) of the analyzed URL

Example:

"tld": "www.hyscore.io"

 

"url"

PARAMETER KEY/FIELD VALUE/RESPONSE DESCRIPTION
result
  • url
  • "url": origin/full URI of the site analyzed and received by the initial POST request. hyScore's unique identifier for URL analysis.

Example:

"url":"https://domain.com/folder/article001.html"

 

 

 

 

 

 

 

 

 

 

 

 

 

Related articles

Comments

0 comments

Article is closed for comments.