Skip to main content

NLP API

Overview​

The NLP API provides endpoints for semantic analysis of articles. It can extract tags, entities, sentiment, and other semantic information from the text.

Endpoints​

EndpointDescription
Request200 Response
POST /v2/nlp/analyzeAnalyzes an article and returns tags, entities, sentiment, and more.
NlpRequestAnalysis
POST /v2/nlp/analyze/feedbackSends feedback on a specific analysis result.
AnalyzeFeedback

POST /v2/nlp/analyze​

Analyzes an article and returns tags, entities, sentiment, and more.

Examples​

Basic analysis

Request - send an article for the default analysis configured for the customer, typically semantic tagging:

curl -X POST -H 'X-API-KEY: <YOUR_API_KEY>' -H 'accept: */*' -H 'content-type: application/json' 'https://media-api.geneea.com/v2/nlp/analyze' -d '{
    "id": "1234",
    "title": "Emmanuel Macron in Germany.",
    "text": "Mr. Macron visited a trade show in Munich."
}'

Response (see Analysis for the description of the fields)

{
    "version": "3.3.0",
    "id": "1234",
    "language": {"detected": "en"},
    "tags": [
        {"id": "t1", "gkbId": "G3052772", "stdForm": "Emmanuel Macron", "type": "media", "relevance": 96.0, "feats": {"wikidataId": "Q3052772", "gkbEntityType": "person"}},
        {"id": "t2", "gkbId": "G183", "stdForm": "Germany", "type": "media", "relevance": 94.0, "feats": {"wikidataId": "Q183", "gkbEntityType": "location"}},
        {"id": "t3", "gkbId": "G1726", "stdForm": "Munich", "type": "media", "relevance": 66.0, "feats": {"wikidataId": "Q1726", "gkbEntityType": "location"}},
        {"id": "t4", "gkbId": "IPTC-11000000", "stdForm": "politics", "type": "media-topic", "relevance": 68.51, "feats": {"MediaTopicId": "11000000", "wikidataId": "Q7163", "gkbEntityType": "general"}}
    ]
    "usedChars": 100,
    "metadata": {"referenceKey": "241014-164726-9bdaf485"},
}
Analysis with mentions

To receive mentions — text snippets in the article that correspond to tags — use the "returnMentions": "true" parameter.

Request

curl -X POST -H 'X-API-KEY: <YOUR_API_KEY>' -H 'accept: */*' -H 'content-type: application/json' 'https://media-api.geneea.com/v2/nlp/analyze' -d '{
    "id": "1234",
    "title": "Emmanuel Macron in Germany.",
    "text": "Mr. Macron visited a trade show in Munich.",
    "returnMentions": "true"
}'

POST /v2/nlp/analyze/feedback​

Sends feedback on a specific analysis result.

Example​

Tags to send feedback on

The request sending an article with ID article-123 for tagging:

POST https://media-api.geneea.com/v2/nlp/analyze
{
    "id": "article-123",
    "title": "Tesla to accept Dogecoin as payment for merchandise, says Musk",
    "text": "Dec 14 (Reuters) - Tesla Inc (TSLA.O) chief Elon Musk said on Tuesday the electric carmaker will accept Dogecoin as payment for merchandise on a test basis, sending the meme-based cryptocurrency up 24%.",
    "language": "en"
}

A sample result (in this case, the Assistant is configured to return tags only):

{
    "id": "article-123",
    "language": { "detected": "en" },
    "tags": [
        {
            "id": "t0",
            "gkbId": "G478214",
            "stdForm": "Tesla, Inc.",
            "type": "media",
            "relevance": 24.33
        },
        {
            "id": "t1",
            "gkbId": "G317521",
            "stdForm": "Elon Musk",
            "type": "media",
            "relevance": 22.5
        },
        {
            "id": "t2",
            "gkbId": "G15377916",
            "stdForm": "Dogecoin",
            "type": "media",
            "relevance": 19.24
        },
        {
            "id": "t3",
            "gkbId": "G130879",
            "stdForm": "Reuters",
            "type": "media",
            "relevance": 9.275
        }
    ],
    "metadata": { "referenceKey": "211201-103000-d64a0290" }
}
Feedback on the returned tags

The feedback references:

  • the ID of the article (article-123)
  • the referenceKey (211201-103000-d64a0290) identifying the particular result
  • individual tags:
    • some were accepted (accepted-actively),
    • some were correct but not important enough (rejected-actively-marginal)
    • some were not expected in the result but had to be entered manually (expected).
POST https://media-api.geneea.com/v2/nlp/analyze/feedback
{
    "docId": "article-123",
    "referenceKey": "211201-103000-d64a0290",
    "tags": [
        { "gkbId": "G478214", "stdForm": "Tesla, Inc.", "status": "accepted-actively"},
        { "gkbId": "G317521", "stdForm": "Elon Musk", "status": "accepted-actively"},
        { "gkbId": "G130879", "stdForm": "Reuters", "status": "rejected-actively-marginal", "comment": "Reuters not wanted" },
        { "gkbId": "G13479982", "stdForm": "cryptocurrency", "status": "expected", "comment": "cryptocurrency is missing"}
    ]
}