Named Entity Recognition

Named Entity Recognition

This method can be used to extract named entities from the given text such as country, name, nationality, date, time, number, email, username, URL, etc. This can be used to quickly identify and extract important information from a given text

The input of your data is limited by your subscription and a larger input can take longer to process
Sentiment Example


Parameter NameDefault ValueRequiredDescription
inputNULLTrueThe given input to process, the size of the input is limited by your subscription
languageenFalseThe language the input is based in, if the given language is not english then CoffeeHouse will attempt to translate the input to english before processing
sentence_split0FalseSplits the results into sentences

Example Success Response (Without sentence_split)

The results has been shortened for demonstration purposes.
{
  "success": true,
  "response_code": 200,
  "results": {
    "text": "Terrence Andrew Davis (December 15, 1969 – August 11, 2018) was an American programmer who created and designed the operating system TempleOS. Its development was an extremely complex, time-consuming and unusual undertaking for one person.",
    "source_language": "en",
    "ner_tags": [
      {
        "text": "Terrence Andrew Davis",
        "offset_begin": 0,
        "offset_end": 21,
        "prediction": 1,
        "type": "PERSON",
        "value": "Terrence Andrew Davis",
        "alt_values": null
      },
      {
        "text": "December 15, 1969",
        "offset_begin": 23,
        "offset_end": 40,
        "prediction": 1,
        "type": "DATE",
        "value": -1450800,
        "alt_values": [
          {
            "type": "DATE",
            "date": {
              "day": "15",
              "month": "12",
              "year": "1969"
            }
          }
        ]
      },
      {
        "text": "August 11, 2018",
        "offset_begin": 43,
        "offset_end": 58,
        "prediction": 1,
        "type": "DATE",
        "value": 1533960000,
        "alt_values": [
          {
            "type": "DATE",
            "date": {
              "day": "11",
              "month": "08",
              "year": "2018"
            }
          }
        ]
      },
      {
        "text": "American",
        "offset_begin": 67,
        "offset_end": 75,
        "prediction": 1,
        "type": "NATIONALITY",
        "value": "American",
        "alt_values": null
      },
      {
        "text": "one",
        "offset_begin": 228,
        "offset_end": 231,
        "prediction": 1,
        "type": "NUMBER",
        "value": 0,
        "alt_values": null
      }
    ]
  }
}

Example Success Response (With sentence_split)

The results has been shortened for demonstration purposes.
{
  "success": true,
  "response_code": 200,
  "results": {
    "text": "Terrence Andrew Davis (December 15, 1969 – August 11, 2018) was an American programmer who created and designed the operating system TempleOS. Its development was an extremely complex, time-consuming and unusual undertaking for one person.",
    "source_language": "en",
    "sentences": [
      {
        "text": "Terrence Andrew Davis (December 15, 1969 – August 11, 2018) was an American programmer who created and designed the operating system TempleO",
        "offset_begin": 0,
        "offset_end": 142,
        "ner_tags": [
          {
            "text": "Terrence Andrew Davis",
            "offset_begin": 0,
            "offset_end": 21,
            "prediction": 1,
            "type": "PERSON",
            "value": "Terrence Andrew Davis",
            "alt_values": null
          },
          {
            "text": "December 15, 1969",
            "offset_begin": 23,
            "offset_end": 40,
            "prediction": 1,
            "type": "DATE",
            "value": -1450800,
            "alt_values": [
              {
                "type": "DATE",
                "date": {
                  "day": "15",
                  "month": "12",
                  "year": "1969"
                }
              }
            ]
          },
          {
            "text": "August 11, 2018",
            "offset_begin": 43,
            "offset_end": 58,
            "prediction": 1,
            "type": "DATE",
            "value": 1533960000,
            "alt_values": [
              {
                "type": "DATE",
                "date": {
                  "day": "11",
                  "month": "08",
                  "year": "2018"
                }
              }
            ]
          },
          {
            "text": "American",
            "offset_begin": 67,
            "offset_end": 75,
            "prediction": 1,
            "type": "NATIONALITY",
            "value": "American",
            "alt_values": null
          }
        ]
      },
      {
        "text": ". Its development was an extremely complex, time-consuming and unusual undertaking for one perso",
        "offset_begin": 143,
        "offset_end": 239,
        "ner_tags": [
          {
            "text": "one",
            "offset_begin": 228,
            "offset_end": 231,
            "prediction": 1,
            "type": "NUMBER",
            "value": 0,
            "alt_values": null
          }
        ]
      }
    ]
  }
}

Response Structure

NameTypeDescription
textstringThe text of the input, or the translation results if the input is from another language
source_languagestringThe original language source
ner_tagsNerTag[]Array of Named Entity tags, this won't be returned if you use sentence_split
sentencesNerTagSentence[]Array of Named Entity sentence splits, this will be returned if you use sentence_split

NerTag Object Structure

NameTypeDescription
textstringThe text value that is being processed
offset_beginintThe character offset begin of the tag
offset_endintThe character offset end of the tag
predictionfloat|intThe prediction of the named entity
typestringThe named entity value type
valueint|string|float|nullThe named entity value
alt_valuesAltValue[]|nullArray of alternative value for representing the value in different ways

NerTagSentence Object Structure

NameTypeDescription
textstringThe text of the sentence
offset_beginintThe character offset begin of the sentence
offset_endintThe character offset end of the sentence
ner_tagsNerTag[]Array of Named Entity tags for this sentence

AltValue Object Structure

NameTypeDescription
typestringThe alternative value type, can be DATE, TIME, DATE_TIME and DURATION
dateDateThe date representation object, returned if the type is DATE or DATE_TIME
timeTimeThe time representation object, returned if the type is TIME or DATE_TIME
durationDurationThe duration representation object, returned of the type is DURATION

Date Object Structure

NameTypeDescription
daystring|nullThe day of the month if applicable
monthstring|nullThe month of the year if applicable
yearstring|nullThe year if applicable

Time Object Structure

NameTypeDescription
hourstring|nullThe hour (24 Hour representation)
minutestring|nullThe minutes
secondsstring|nullThe seconds

Duration Object Structure

NameTypeDescription
duration_typestring|nullThe duration representation type, can be DATE, TIME, SEVERAL_DAYS, SEVERAL_MONTHS, SEVERAL_YEARS, SEVERAL_WEEKS, SEVERAL_SECONDS, SEVERAL_HOURS, SEVERAL_MINUTES, SEVERAL_MILLISECONDS or UNKNOWN
value_unitstring|nullThe unit of the value, if the duration_type is DATE then it can be YEAR, MONTH, DAY, WEEK or UNKNOWN. if the duration_type is TIME then the possible values are HOUR, MINUTE, SECOND, MILLISECONDS and or UNKNOWN
valueint|string|nullThe value of the duration

DateTime Object Structure

NameTypeDescription
dateDateThe date representation of the value
timeTimeThe time representation of the value

Named Entity Tags

These are the tags that CoffeeHouse is able to detect, if you are using a free subscription then not all of these tags will be returned.
Tag Value Available for Free Subscriptions Description
PERSON False The name of a individual, eg; John Doe
LOCATION False The location specified
ORGANIZATION False An Organization name
MISC False Miscellaneous entity that cannot be categorized
MONEY False Value representation involving money
NUMBER False Number value, eg; 1, three, four hundred, etc.
PERCENT False Percentage value
DATE False Date value, eg; September 4th 1996
TIME False Time value, eg; 4:20 PM
CURRENT_TIME False Text indicating the current time
DURATION False The duration of a time or date unit, eg; Several days, 7 days, 20 hours, 1 decade, etc.
EMAIL True An Email Address such as [email protected]
URL True URL Address
CITY True City Name
STATE_OR_PROVINCE True State of Province value
COUNTRY True Country Value
NATIONALITY True Nationality Value
RELIGION True Religion Value
USERNAME_HANDLE True The username handle, eg; @Intellivoid

Invalid Language Code Response

This response is given when the parameter language contains an invalid value.
{
  "success": false,
  "response_code": 400,
  "error": {
    "error_code": 7,
    "type": "CLIENT",
    "message": "The given language 'not a real language' cannot be identified"
  }
}

Invalid Language Code Response

This response is given when the parameter language contains an invalid value.
{
  "success": false,
  "response_code": 400,
  "error": {
    "error_code": 7,
    "type": "CLIENT",
    "message": "The given language 'not a real language' cannot be identified"
  }
}

Unsupported Language Response

This response is given when the requested language is unsupported by the method
{
  "success": false,
  "response_code": 400,
  "error": {
    "error_code": 23,
    "type": "CLIENT",
    "message": "The given language 'nr' is not supported"
  }
}