Skip to main content

Heimdall Read

Convert your text data into structured, tabular datasets ready for modeling.

API Specifications​

Endpoint​

POST https://read.heimdallapp.org/read/v1/api/process

Request Headers​

  • x-api-key - API key that is issued when the endpoint is configured.
  • x-username - Username associated with your account.
tip

All request headers are required.

Lost Key

API Keys are issued one time and cannot be retrieved. If you lose your API key, please disable the endpoint in the read page and reconfigure to get a new API key.

Request Body​

  • text - The text input that you want to analyze.
warning

The text input should not include line breaks or double quotes.

Response Object​

  • length - The number of characters in the text

  • word_count - The number of words in the text

  • oov_ratio - The proportion of words or terms in a given text or dataset that are not found in a predefined vocabulary or dictionary.

  • oov_ratio_2 - The proportion of words or terms in a given text or dataset that are not found in a predefined vocabulary or dictionary. Using another dictionary to add some variety.

  • sentence_count - The number of sentences in the text

  • sentence_count - The number of sentences in the text

  • avg_word_length - The average number of characters in the words in the text.

  • avg_sentence_length - The average number of words in the sentences in the text.

  • noun_count - The number of english nouns in the text.

  • verb_count - The number of english verbs in the text.

  • adjective_count - The number of english adjectives in the text.

  • adverb_count - The number of english adverbs in the text.

  • pronoun_count - The number of english pronouns in the text.

  • stopword_count - The number of stopwords in the text. Stop words are common words which do not add any additional value to the text.

  • tfidf_top1 - The most important term in the entire text based on term frequency - inverse document fequency methodology.

  • tfidf_top2 - The second most important term in the entire text based on term frequency - inverse document fequency methodology.

  • tfidf_top3 - The third most important term in the entire text based on term frequency - inverse document fequency methodology.

  • sentiment - The overall sentiment of the entire text. Possible values: Positive, Negative, Neutral.

  • compound_sentiment_score - The overall degree of sentiment of the entire text. Its value is between -1 (most extreme negative sentiment) and +1 (most extreme positive sentiment).

Read response object
{
    "length": 1755,
    "word_count": 367,
    "oov_ratio": 0.18256130790190736,
    "oov_ratio_2": 0.33787465940054495,
    "sentence_count": 18,
    "avg_word_length": 3.904632152588556,
    "avg_sentence_length": 20.38888888888889,
    "noun_count": 54,
    "verb_count": 76,
    "adjective_count": 17,
    "adverb_count": 40,
    "pronoun_count": 27,
    "stopword_count": 169,
    "tfidf_top1": "writing",
    "tfidf_top2": "good",
    "tfidf_top3": "just",
    "sentiment": "positive",
    "compound_sentiment_score": 0.7737
}
422 Unprocessable Entity

You will receieve a 422 error your request body structure is incorrect.

Sample Request​

Use the below sample request in Python to get started.

warning

You need to fill in your specific header values.

Python Request
import requests

url = 'https://read.heimdallapp.org/read/v1/api/process'
headers = {
    'X-api-key': 'YOUR-API-KEY',
    'X-username': 'YOUR-USERNAME',
}

data = {
    "text": "add you text input value here"
}
    
response = requests.post(url, headers=headers, json=data)