Source: https://shakti.eventregistry.org/documentation?tab=annotate

# Annotate

Uniquely identify people, locations, organizations and things mentioned in the user-provided document.

The API call can be used to semantically annotate the provided document. The semantic annotation includes identification of people, locations, organizations and things mentioned in the document. All annotations will have a unique URI that will correspond to the URL of the Wikipedia page that will match the concept. The annotations can be generated for over 100 different languages. Each returned annotation will contain a property `url` that will point to the concept in the Wikipedia for that language. The `secUrl` parameter will point to the concept in the English Wikipedia, if the page for it exists.

**Endpoint:** GET | POST `http://analytics.eventregistry.org/api/v1/annotate`

**Headers:** Content-Type: application/json

#### `Parameters`

#### `apiKey`

string (required)

Your API key

#### `text`

string (required)

Define a text that you'll like to see annotated.

#### `Additional parameters`

Click to see additional parameters

#### `minLinkFrequency`

integer

The minimum number of times the phrase should appear in the link in order for use to use it as a candidate for the [annotation](#).

Default value: `3`

#### `minLinkRelFrequency`

double

Consider the candidate only if the given text points to the candidate with probability above this value. Value between 0 and 1.

Default value: `0.01`

#### `nWordsToIgnoreFromList`

integer

Use this setting to ignore common phrases. If a phrase consists entirely of very frequent words, it will be ignore. A word is considered frequent if it is one of the most frequent words (in terms of document frequency) in the Wikipedia of the corresponding language. If 0 it will disable this heuristic.

Default value: `200`

#### `minPMentionGivenPhrase`

double

Probability that the given phrase, if found on Wikipedia, is annotated with the concept. If non-zero, it can help to remove the common words.

Default value: `0.03`

#### `pageRankSqThreshold`

double

Probability that the given phrase, if found on Wikipedia, is annotated with the concept. If non-zero, it can help to remove the common words.

Default value: `0.95`

#### `applyPageRankSqThreshold`

boolean

Apply pageRankSqThreshold to the requested response.

## Request examples

### Example 1

Request body:

```json
{
  "text": "Microsoft released a new version of Windows OS.",
  "apiKey": "YOUR_API_KEY"
}
```

```python
from eventregistry import *
er = EventRegistry(apiKey = YOUR_API_KEY)
analytics = Analytics(er)

annInfo = analytics.annotate("Microsoft released a new version of Windows OS.")

for ann in annInfo.get("annotations", []):
    print(ann)
```

```javascript
var er = new erBase.EventRegistry();
                    var analytics = new erBase.Analytics(er);
                    analytics.annotate("Microsoft released a new version of Windows OS.").then((annInfo) => {
                        console.log(annInfo);
                    });
```

```typescript
const er = new EventRegistry();
                    const analytics = new Analytics(er);
                    analytics.annotate("Microsoft released a new version of Windows OS.").then((annInfo) => {
                        console.log(annInfo);
                    });
```

## Example output

```json
{
  "annotations": [
    {
      "title": "Singapore",
      "url": "http://en.wikipedia.org/wiki/Singapore",
      "lang": "en",
      "pageRank": 0.02274951488845428,
      "secLang": "en",
      "secTitle": "Singapore",
      "secUrl": "http://en.wikipedia.org/wiki/Singapore",
      "wikiDataItemId": "Q334",
      "dbPediaTypes": [
        "PopulatedPlace",
        "Place",
        "Country"
      ],
      "dbPediaIri": "http://dbpedia.org/resource/Singapore",
      "support": [
        {
          "wFrom": 0,
          "wTo": 0,
          "chFrom": 0,
          "chTo": 8,
          "pMentionGivenSurface": 0.3624772063561704,
          "pageRank": 0.00733049123934485,
          "prbConfidence": 0.5945097191539227,
          "entropy": 0.3062825090018834,
          "text": "Singapore",
          "wikiLang": "en"
        }
      ],
      "type": "loc",
      "wgt": 0.6666666666666666
    },
    {
      "title": "Lee Hsien Loong",
      "url": "http://en.wikipedia.org/wiki/Lee_Hsien_Loong",
      "lang": "en",
      "pageRank": 0.03712173018650666,
      "secLang": "en",
      "secTitle": "Lee Hsien Loong",
      "secUrl": "http://en.wikipedia.org/wiki/Lee_Hsien_Loong",
      "wikiDataItemId": "Q57643",
      "dbPediaTypes": [
        "Person",
        "Agent",
        "President",
        "Politician",
        "OfficeHolder"
      ],
      "dbPediaIri": "http://dbpedia.org/resource/Lee_Hsien_Loong",
      "support": [
        {
          "wFrom": 4,
          "wTo": 6,
          "chFrom": 27,
          "chTo": 41,
          "pMentionGivenSurface": 0.8918918918918919,
          "pageRank": 0.01803701194257155,
          "prbConfidence": 1,
          "entropy": 0,
          "text": "Lee Hsien Loong",
          "wikiLang": "en"
        },
        {
          "chFrom": 563,
          "chTo": 565,
          "wFrom": 105,
          "wTo": 105,
          "pageRank": null,
          "pMentionGivenSurface": null,
          "text": "Lee",
          "wikiLang": "en"
        },
        {
          "chFrom": 1118,
          "chTo": 1120,
          "wFrom": 219,
          "wTo": 219,
          "pageRank": null,
          "pMentionGivenSurface": null,
          "text": "Lee",
          "wikiLang": "en"
        }
      ],
      "type": "person",
      "wgt": 0.6984843176884913
    },
    {
      "title": "Mediacorp",
      "url": "http://en.wikipedia.org/wiki/Mediacorp",
      "lang": "en",
      "pageRank": 0.020642583639049,
      "secLang": "en",
      "secTitle": "Mediacorp",
      "secUrl": "http://en.wikipedia.org/wiki/Mediacorp",
      "wikiDataItemId": "Q1368796",
      "dbPediaTypes": [],
      "dbPediaIri": "",
      "support": [
        {
          "wFrom": 110,
          "wTo": 110,
          "chFrom": 588,
          "chTo": 596,
          "pMentionGivenSurface": 0.4163602941176471,
          "pageRank": 0.008420185972856556,
          "prbConfidence": 1,
          "entropy": 0,
          "text": "Mediacorp",
          "wikiLang": "en"
        }
      ],
      "type": "wiki",
      "wgt": 0.3333333333333333
    },
    {
      "#META ITEM": "other concepts..."
    }
  ],
  "minPageRank": 0.01728619391379328,
  "maxDfThreshold": 834348,
  "altLabelSetsUsed": [
    "en"
  ],
  "linkSourcesAvailable": true,
  "timeTotalMs": 58.456,
  "timeAnnotationMs": 58.456,
  "timeBuildJsonMs": 0,
  "incIdxTimestampUtc": "",
  "fnRegIdx": "enwiki-20220120-pages-articles-index3.bin",
  "fnWikiData": "wikidata-20200803-all.bin",
  "settings": {
    "pageRankSqThreshold": 0.95,
    "applyPageRankSqThreshold": true,
    "minPMentionGivenPhrase": 0.03,
    "maxMentionEntropy": -1,
    "maxTargetsPerMention": 20,
    "useLogLinkCounts": false,
    "candSelectionUseLinearizedPageRank": false,
    "candSelectionPageRankThreshold": 0,
    "candSelectionCosineWeight": 0,
    "candSelectionLinkCtxCosineWeight": 0,
    "candSelectionUseLinkProb": "log",
    "semanticSimilarity": "in",
    "secondaryAnnotLanguage": "en",
    "minLinkFrequency": 3,
    "minLinkRelFrequency": 0.01,
    "nTopDfWordsToIgnore": 200,
    "nWordsToIgnoreFromList": 200,
    "extraVocabsToInclude": [],
    "altLabelSetsToUse": [
      "*"
    ]
  },
  "language": "en",
  "languageAutodetectInfo": "Language autodetected as \"en\" (0).",
  "languageAutodetectDetails": {
    "topLangNo": 0,
    "topLangCode": "en",
    "candidates": [
      {
        "langNo": 0,
        "langCode": "en",
        "percent": 99,
        "normScore": 1190
      },
      {
        "langNo": 26,
        "langCode": "unknown_26",
        "percent": 0,
        "normScore": 0
      },
      {
        "langNo": 26,
        "langCode": "unknown_26",
        "percent": 0,
        "normScore": 0
      }
    ],
    "textBytes": 1134,
    "validPrefBytes": 1176,
    "isReliable": true,
    "chunks": []
  }
}
```

## Output schema

```json
{
  "type": "object",
  "properties": {
    "annotations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "example": "http://en.wikipedia.org/wiki/Microsoft"
          },
          "title": {
            "type": "string",
            "example": "Microsoft"
          },
          "lang": {
            "type": "string",
            "example": "eng"
          },
          "secUrl": {
            "type": "string",
            "example": "http://en.wikipedia.org/wiki/Microsoft"
          },
          "secTitle": {
            "type": "string",
            "example": "Microsoft"
          },
          "secLang": {
            "type": "string",
            "example": "eng"
          },
          "dbPediaIri": {
            "type": "string",
            "example": "http://dbpedia.org/resource/Microsoft"
          },
          "dbPediaTypes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "Agent",
              "Organisation",
              "Company"
            ]
          },
          "type": {
            "type": "string",
            "example": "org"
          },
          "wgt": {
            "type": "double",
            "example": 0.9
          },
          "pageRank": {
            "type": "double",
            "example": 0.254
          },
          "wikiDataItemId": {
            "type": "string",
            "example": "Q2283"
          },
          "wikiDataClassIds": {
            "type": "array",
            "example": "Q2283",
            "items": {
              "type": "string"
            }
          },
          "support": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "chFrom": {
                  "type": "integer",
                  "example": 0
                },
                "chTo": {
                  "type": "integer",
                  "example": 8
                },
                "pMentionGivenSurface": {
                  "type": "double",
                  "example": 0.255
                },
                "text": {
                  "type": "string",
                  "example": "Microsoft"
                },
                "wFrom": {
                  "type": "integer",
                  "example": 0
                },
                "wTo": {
                  "type": "integer",
                  "example": 0
                },
                "wikiLang": {
                  "type": "string",
                  "example": "en"
                }
              }
            }
          }
        }
      }
    },
    "spaces": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "words": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "normWords": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "ranges": {
      "type": "array",
      "items": {
        "type": "integer"
      }
    },
    "minPageRank": {
      "type": "integer"
    },
    "maxDfThreshold": {
      "type": "integer"
    },
    "altLabelSetsUsed": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "linkSourcesAvailable": {
      "type": "boolean"
    },
    "verbs": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "iFrom": {
            "type": "integer"
          },
          "iTo": {
            "type": "integer"
          },
          "normForm": {
            "type": "string"
          },
          "synsetIds": {
            "type": "array",
            "items": {
              "type": "integer"
            }
          }
        }
      }
    },
    "nouns": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "iFrom": {
            "type": "integer"
          },
          "iTo": {
            "type": "integer"
          },
          "normForm": {
            "type": "string"
          },
          "synsetIds": {
            "type": "array",
            "items": {
              "type": "integer"
            }
          }
        }
      }
    },
    "adjectives": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "iFrom": {
            "type": "integer"
          },
          "iTo": {
            "type": "integer"
          },
          "normForm": {
            "type": "string"
          },
          "synsetIds": {
            "type": "array",
            "items": {
              "type": "integer"
            }
          }
        }
      }
    },
    "adverbs": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "iFrom": {
            "type": "integer"
          },
          "iTo": {
            "type": "integer"
          },
          "normForm": {
            "type": "string"
          },
          "synsetIds": {
            "type": "array",
            "items": {
              "type": "integer"
            }
          }
        }
      }
    },
    "timeTotalMs": {
      "type": "integer"
    },
    "timeAnnotationMs": {
      "type": "integer"
    },
    "timeBuildJsonMs": {
      "type": "integer"
    },
    "incIdxTimestampUtc": {
      "type": "string"
    },
    "fnRegIdx": {
      "type": "string"
    },
    "fnWikiData": {
      "type": "string"
    },
    "settings": {
      "type": "object",
      "properties": {
        "pageRankSqThreshold": {
          "type": "integer"
        },
        "applyPageRankSqThreshold": {
          "type": "boolean"
        },
        "minPMentionGivenPhrase": {
          "type": "integer"
        },
        "maxMentionEntropy": {
          "type": "integer"
        },
        "maxTargetsPerMention": {
          "type": "integer"
        },
        "useLogLinkCounts": {
          "type": "boolean"
        },
        "candSelectionUseLinearizedPageRank": {
          "type": "boolean"
        },
        "candSelectionPageRankThreshold": {
          "type": "integer"
        },
        "candSelectionCosineWeight": {
          "type": "integer"
        },
        "candSelectionLinkCtxCosineWeight": {
          "type": "integer"
        },
        "candSelectionUseLinkProb": {
          "type": "string"
        },
        "semanticSimilarity": {
          "type": "string"
        },
        "secondaryAnnotLanguage": {
          "type": "string"
        },
        "minLinkFrequency": {
          "type": "integer"
        },
        "minLinkRelFrequency": {
          "type": "integer"
        },
        "nWordsToIgnoreFromList": {
          "type": "integer"
        },
        "extraVocabsToInclude": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {}
          }
        },
        "altLabelSetsToUse": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "language": {
      "type": "string"
    },
    "languageAutodetectInfo": {
      "type": "string"
    },
    "languageAutodetectDetails": {
      "type": "object",
      "properties": {
        "topLangNo": {
          "type": "integer"
        },
        "topLangCode": {
          "type": "string"
        },
        "candidates": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "langNo": {
                "type": "integer"
              },
              "langCode": {
                "type": "string"
              },
              "percent": {
                "type": "integer"
              },
              "normScore": {
                "type": "integer"
              }
            }
          }
        },
        "textBytes": {
          "type": "integer"
        },
        "validPrefBytes": {
          "type": "integer"
        },
        "isReliable": {
          "type": "boolean"
        },
        "chunks": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    }
  }
}
```