Skip to main content

Entities

Entities are elements explicitly mentioned in the article. They include:

  • Names of people, locations, organizations, products, and events (e.g., Barack Obama, Paris, Apple Inc., iPhone 13, Olympic Games)
  • General concepts, sometimes referred to as keywords, which may not refer to a specific named item but represent meaningful ideas or topics—such as flu season, electric vehicle, or income tax.

These entities are identified to help you understand what the article is about and to support tasks like tagging, linking, or analysis.

See:

Entity Information​

The following information is provided for each detected entity (JSON field names are in parentheses):

  • GKB ID (gkbId): The entity's identifier in our Geneea Knowledge Base (GKB), typically in its generic bucket (e.g., G145 for Britain). This field is missing for synthetic entities (see below).

  • Standard Form (stdForm): The standard/canonical name of the entity in the relevant language. For example, the standard form for G145 is: United Kingdom in English Spojené království in Czech Royaume-Uni in French Storbritannien in Danish. While typically translations, standard forms do not need to be direct equivalents.

  • Type (type): One of the supported entity types listed below.

  • Mentions: The API provides information about entity mentions in two ways:

    1. Simple Mention Reference (feats.mentionText, feats.mentionParaSpecId, feats.mentionParaSpecSpan): A lightweight way to locate an early occurrence of the entity in the original text (including HTML). These three feats keys give you the mention's surface text, the paragraph it appears in, and the character offset within that paragraph — enough to create a hyperlink or highlight. No special request parameter is needed; the features appear automatically when enabled for your account. See the simple mention reference guide and the Entity Custom Features reference for details.

    2. Full Mentions (mentions): A complete list of all occurrences of the entity in the text, with token-level detail. For example, G145 might appear as United Kingdom, UK, Britain, Great Britain and Northern Ireland in English. Each mention includes:

      • References to the article text (tokenIds): References to specific tokens in the article, allowing you to link back to exact positions — useful for highlighting or hyperlinking entity mentions. Note that if you process HTML, all the offsets refer to the extracted plain text.
      • Normalized form of the mention (mwl): The base form of the mention, abstracting away language-specific morphological variations. For instance, in Czech, the entity Spojené království (United Kingdom in English) may appear in several grammatical cases — e.g., Spojeného království, Spojenému království, etc. The mwl field always contains the base form: Spojené království.

      Full mentions must be requested with "returnMentions": "true" and add the full tokenized text structure to the response. See the Semantic Tagging guide for an example.

    If you only need to locate a single mention for linking or highlighting, the simple mention reference is sufficient and much simpler to work with, especially if you need references to HTML. Use full mentions when you need every occurrence or token-level precision.

  • Relevance Score (feats.relevance): A numeric value between 0 and 100 that indicates how central the entity is to the meaning of the text. For example, if the article is primarily about Britain, the relevance score of the G145 entity (United Kingdom) will be high. If Britain is mentioned only briefly or in passing, the score will be much lower. This helps to distinguish main topics from incidental references. See this guide for more information.

  • Other Custom Features (depending on configuration, under the feats key): The feats object can also contain other metadata such as Wikidata IDs, knowledge base type information, and deprecation flags. See the Entity Custom Features reference for the full list.

See the Entity object reference page for more details.

Entity Types​

The standard configuration includes the following entity types:

  • person – John Doe
  • organization – UNESCO, IBM
  • location – London, France
  • product – Skoda Octavia, iPhone 13
  • event – Brexit, World War II
  • general – electric vehicle, trade war, flu season, income tax

In addition, we support detection of numeric and temporal expressions such as dates, currencies, and amounts.

We can also enable detection of custom entity types tailored to your use case—for example:
colors, food items, economic terms, laws, product numbers, etc.

Derived Entities​

Derived entities are not explicitly mentioned in the text but are logically related to those that are.

For example, if an article mentions Prague, we infer that it is also about the Czech Republic, based on geographic relationships stored in our Knowledge Base.
Here:

  • Prague is a direct entity
  • Czech Republic is a derived entity

Derived entities inherit all mentions of the original (direct) entity. So, in the example above, every mention of Prague would also count as a (derived) mention of the Czech Republic.

It's also possible for an entity to have both a direct and derived mention in the same sentence.
For example, in the sentence “Prague is the capital of the Czech Republic,” the entity Czech Republic has two mentions:

  • A direct mention: Czech Republic
  • A derived mention: Prague

We currently support a selection of derived entity types such as:

  • manufacturer
  • industry
  • country, region, district, city, cityPart

Coverage varies depending on geography and data availability.

Synthetic Entities​

While we aim to include all entities in the GKB, this is not always possible. Entities that are reliably detected in the text but lack a corresponding GKB entry are called synthetic entities.

Characteristics of synthetic entities:

  • They do not have GKB identifiers, Wikidata IDs, or social media links.
  • Their standard form is generated from the mention using grammatical heuristics.
  • Quality may be lower due to lack of structured data.

In general, GKB-linked entities are preferred. Synthetic entities are useful for completeness but are not recommended for most production use cases, especially where accuracy or linkage is important.