Entities

Entities are important expressions, both named (e.g., organizations, cities) and unnamed (e.g., dates). The exact set of supported entities is dependent on the domain.

Entities have:

  • name or standard form – disambiguated and standardized form of the entity. For example, we will return USA for both USA and United States. We will also take care of morphology: returning Německo even when the text contains the form Německu. Media API V2 can also display the standard form in a specified language (Germany, Deutschland, Německo, etc.)

  • id – a unique id of the entity in some knowledge base (we support this only in certain domains)

  • link to Geneea Knowledge Base if the domain supports it.

  • type – a string indicating whether the entity is a person or date, see below for a list of types.

  • instances or mentions - the actual mention of the entity in the document

See the Entity object reference page for more information.

Entity types

The standard media domains support the following entity types:

  • Basic:

    • person – John Doe

    • organization – UNESCO, IBM

    • location – London, France

    • product – Skoda Octavia, iPhone 13

    • event – Brexit, World War II

    • general – electric vehicle, trade war

  • Internet:

    • url – geneea.com

    • email – info@geneea.com

    • hashtag – #hashtag

    • mention – @mention

  • Date and Time:

    Entities can be resolved relative to some point in time (see referenceDate in Request). Standard forms follow the TIMEX3 format.

    • date – September 3 (XXXX-09-03 when unresolved), next Monday, summer of 2015 (2015-SU)

    • time – 12:03 (YYYY-MM-DDT12:03), tonight (YYYY-MM-DDTNI)

    • duration – 3 years and 4 days (P3Y4D), 5 minutes (PT5M). Standard form P(n)Y(n)M(n)DT(n)H(n)M(n)S

    • set – set of times/dates – every Monday (XXXX-WXX-1), semiannual (P6M)

  • Numbers:

    • number – 3; five (words only in English)

    • ordinal – third (only for English)

    • money – $40

    • percent – 5%

The standard VoC domains support selected named entities, general entities, industry specific entities (e.g. food for restaurants) and Internet/data/numeric entities.

In addition, we can support many other entity types (colors, means of transport, food items, economic terms, laws, product numbers, …) in custom domains.

We use a combination of machine learning models, rules and lexicons. And as always we can customize all of these.

Sample call

You can easily try it yourself:

curl -X POST https://api.geneea.com/v3/analysis \
-H 'Authorization: user_key <YOUR USER KEY>' \
-H 'Content-Type: application/json' \
-d '{
    "id": "1",
    "text": "The trip to London last summer was great. I also liked Cambridge a lot. ",
    "referenceDate": "2016-02-01",
    "analyses": ["entities"]
}'

# On Windows, use \" instead of " and " instead of '

You should get the following response:

{
    "id": "1",
    "language": {"detected": "en"},
    "entities": [
        {"id": "E0", "stdForm": "2015-SU", "type": "date"},
        {"id": "E1", "stdForm": "London", "type": "location"},
        {"id": "E2", "stdForm": "Cambridge", "type": "location"}
    ],
    "usedChars": 100
}

Mentions and highlighting

You can use "returnMentions": "true" to return the entity mentions:

curl -X POST https://api.geneea.com/v3/analysis \
-H 'Authorization: user_key <YOUR USER KEY>' \
-H 'Content-Type: application/json' \
-d '{
    "id": "1",
    "text": "The trip to London last summer was great. I also liked Cambridge a lot. ",
    "referenceDate": "2016-02-01",
    "analyses": ["entities"],
    "returnMentions": "true"
}'

# On Windows, use \" instead of " and " instead of '

In comparison with the previous response, this one contains mentions of the individual entities: their text and reference to the relevant tokens (text, split into paragraphs, sentences and tokens are added automatically to the response).

{
    "id": "1",
    "language": {"detected": "en"},
    "paragraphs": [{
        "id": "P2",
        "type": "BODY",
        "text": "The trip to London last summer was great. I also liked Cambridge a lot. ",
        "corrText": "The trip to London last summer was great. I also liked Cambridge a lot. ",
        "sentences": [{
            "id": "s0",
            "tokens": [
                {"id": "t0", "off": 0, "text": "The", "corrOff": 0, "corrText": "The"},
                {"id": "t1", "off": 4, "text": "trip", "corrOff": 4, "corrText": "trip"},
                {"id": "t2", "off": 9, "text": "to", "corrOff": 9, "corrText": "to"},
                {"id": "t3", "off": 12, "text": "London", "corrOff": 12, "corrText": "London"},
                {"id": "t4", "off": 19, "text": "last", "corrOff": 19, "corrText": "last"},
                {"id": "t5", "off": 24, "text": "summer", "corrOff": 24, "corrText": "summer"},
                {"id": "t6", "off": 31, "text": "was", "corrOff": 31, "corrText": "was"},
                {"id": "t7", "off": 35, "text": "great", "corrOff": 35, "corrText": "great"},
                {"id": "t8", "off": 40, "text": ".", "corrOff": 40, "corrText": "."}]
        }, {
            "id": "s1",
            "tokens": [
                {"id": "t9", "off": 42, "text": "I", "corrOff": 42, "corrText": "I"},
                {"id": "t10", "off": 44, "text": "also", "corrOff": 44, "corrText": "also"},
                {"id": "t11", "off": 49, "text": "liked", "corrOff": 49, "corrText": "liked"},
                {"id": "t12", "off": 55, "text": "Cambridge", "corrOff": 55, "corrText": "Cambridge"},
                {"id": "t13", "off": 65, "text": "a", "corrOff": 65, "corrText": "a"},
                {"id": "t14", "off": 67, "text": "lot", "corrOff": 67, "corrText": "lot"},
                {"id": "t15", "off": 70, "text": ".", "corrOff": 70, "corrText": "."}
            ]
        }]
    }],
    "entities": [
        {"id": "E0", "stdForm": "2015-SU", "type": "date", "mentions": [{"id": "m0", "mwl": "last summer", "text": "last summer", "tokenIds": ["t4", "t5"]}]},
        {"id": "E1", "stdForm": "London", "type": "location", "mentions": [{"id": "m1", "mwl": "London", "text": "London", "tokenIds": ["t3"]}]},
        {"id": "E2", "stdForm": "Cambridge", "type": "location", "mentions": [{"id": "m2", "mwl": "Cambridge", "text": "Cambridge", "tokenIds": ["t12"]}]}
    ],
    "usedChars": 100
}