Quick Start - Semantic Tagging

In this quick start, we describe how the Media API can be used to perform semantic tagging of articles. The topic is described in more detail in this guide article.

First Steps

To use the API, you need a valid API key with appropriate authorizations. Please get in touch with us if you do not have it here.

Note that we do not provide SDKs for the API yet, but our G3 SDKs can be used to perform NLP analysis.

We will first define some common code (replace <YOUR_API_KEY> with your API key):

cURL

# No special setup necessary

cURL (Windows)

# No special setup necessary

JavaScript

// HTTP client; see https://github.com/axios/axios
const axios = require('axios');

const config = {
    baseURL: 'https://media-api.geneea.com/v2/',
    headers: {
        'X-API-KEY': '<YOUR_API_KEY>'
    }
};

// A simple function to report the returned json objects
const report = (output) => console.dir(output, { depth: null });

// In production environment, the API should always be called from the backend,
// otherwise you run into CORS problems

Python

# http client; see https://docs.python-requests.org/en/latest/
import requests

BASE_URL = 'https://media-api.geneea.com/v2/'
HEADERS = {
    'content-type': 'application/json',
    'X-API-Key': '<YOUR_API_KEY>'
}

Python SDK

# Geneea NLP client SDK; see https://help.geneea.com/sdk/index.html
# The SDK can be used for the content analysis (i.e. NLP) part of the Media API
from geneeanlpclient  import g3

BASE_URL = 'https://media-api.geneea.com/v2/'
API_KEY = '<YOUR_API_KEY>'

Basic analysis

To perform a basic analysis of a document to obtain tags (keywords), entities, relations and sentiment use the following code:

cURL

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

cURL (Windows)

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

JavaScript

const analyze = async (config, input) => {
    const response = await axios.post('nlp/analyze', input, config);
    return response.data;
};

const input = {
    id: '1234',
    title: 'Emmanuel Macron in Germany.',
    text: 'Mr. Macron visited a trade show in Munich.'
}

analyze(config, input).then(report);

Python

def analyze(input):
    return requests.post(f'{BASE_URL}nlp/analyze', json=input, headers=HEADERS).json()

input = {
    'id': '1234',
    'title': 'Emmanuel Macron in Germany.',
    'text': 'Mr. Macron visited a trade show in Munich.'
}

analyze(input)

Python SDK

requestBuilder = g3.Request.Builder()

with g3.Client.create(url=f'{BASE_URL}nlp/analyze') as analyzer:
    analyzer.session.headers.update({'X-API-Key': API_KEY})

    request = requestBuilder.build(id=str('1234'), title='Emmanuel Macron in Germany.', text='Mr. Macron visited a trade show in Munich.')
    result = analyzer.analyze(request)

    print("Entities:")
    for e in result.entities:
        print(f'   {e.type}: {e.stdForm} ({e.gkbId})')

    print("Tags:")
    for t in result.tags:
        print(f'   \t{t.type}: {t.stdForm} ({t.gkbId}) relevance: {t.relevance}')

the above code produces the following result (see the Analysis reference page for explanation. Note that (i) we have omitted the relations field for simplicity, and (ii) the exact set of returned features depends on your account plan).

cURL

{
    "version": "3.2.1",
    "id": "1234",
    "language": { "detected": "en" },
    "entities": [
        { "id": "e0", "gkbId": "G57305", "stdForm": "trade fair", "type": "general" },
        { "id": "e1", "gkbId": "G183", "stdForm": "Germany", "type": "location" },
        { "id": "e2", "gkbId": "G1726", "stdForm": "Munich", "type": "location" },
        { "id": "e3", "gkbId": "G3052772", "stdForm": "Emmanuel Macron", "type": "person" },
        { "id": "e4", "gkbId": "G183", "stdForm": "Germany", "type": "country", "feats": {"derivedBy": "gkb2:[gkbp:adminCountry]" } },
        { "id": "e5", "gkbId": "G980", "stdForm": "Bavaria", "type": "region", "feats": { "derivedBy": "gkb2:[gkbp:region]" } }
    ],
    "tags": [
        { "id": "t0", "gkbId": "G3052772", "stdForm": "Emmanuel Macron", "type": "media", "relevance": 22.605, "feats": { "wikidataId": "Q3052772" } },
        { "id": "t1", "gkbId": "G183", "stdForm": "Germany", "type": "media", "relevance": 18.365, "feats": { "wikidataId": "Q183" } },
        { "id": "t2", "gkbId": "G1726", "stdForm": "Munich", "type": "media", "relevance": 7.57, "feats": { "wikidataId": "Q1726" } }
    ],
    "relations": [..],
    "docSentiment": { "mean": 0.0, "label": "neutral", "positive": 0.0, "negative": 0.0 },
    "usedChars": 100,
    "metadata": {"referenceKey": "311441-120020-a24f0281"}
}

cURL (Windows)

{
    "version": "3.2.1",
    "id": "1234",
    "language": { "detected": "en" },
    "entities": [
        { "id": "e0", "gkbId": "G57305", "stdForm": "trade fair", "type": "general" },
        { "id": "e1", "gkbId": "G183", "stdForm": "Germany", "type": "location" },
        { "id": "e2", "gkbId": "G1726", "stdForm": "Munich", "type": "location" },
        { "id": "e3", "gkbId": "G3052772", "stdForm": "Emmanuel Macron", "type": "person" },
        { "id": "e4", "gkbId": "G183", "stdForm": "Germany", "type": "country", "feats": {"derivedBy": "gkb2:[gkbp:adminCountry]" } },
        { "id": "e5", "gkbId": "G980", "stdForm": "Bavaria", "type": "region", "feats": { "derivedBy": "gkb2:[gkbp:region]" } }
    ],
    "tags": [
        { "id": "t0", "gkbId": "G3052772", "stdForm": "Emmanuel Macron", "type": "media", "relevance": 22.605, "feats": { "wikidataId": "Q3052772" } },
        { "id": "t1", "gkbId": "G183", "stdForm": "Germany", "type": "media", "relevance": 18.365, "feats": { "wikidataId": "Q183" } },
        { "id": "t2", "gkbId": "G1726", "stdForm": "Munich", "type": "media", "relevance": 7.57, "feats": { "wikidataId": "Q1726" } }
    ],
    "relations": [..],
    "docSentiment": { "mean": 0.0, "label": "neutral", "positive": 0.0, "negative": 0.0 },
    "usedChars": 100,
    "metadata": {"referenceKey": "311441-120020-a24f0281"}
}

JavaScript

{
    "version": "3.2.1",
    "id": "1234",
    "language": { "detected": "en" },
    "entities": [
        { "id": "e0", "gkbId": "G57305", "stdForm": "trade fair", "type": "general" },
        { "id": "e1", "gkbId": "G183", "stdForm": "Germany", "type": "location" },
        { "id": "e2", "gkbId": "G1726", "stdForm": "Munich", "type": "location" },
        { "id": "e3", "gkbId": "G3052772", "stdForm": "Emmanuel Macron", "type": "person" },
        { "id": "e4", "gkbId": "G183", "stdForm": "Germany", "type": "country", "feats": {"derivedBy": "gkb2:[gkbp:adminCountry]" } },
        { "id": "e5", "gkbId": "G980", "stdForm": "Bavaria", "type": "region", "feats": { "derivedBy": "gkb2:[gkbp:region]" } }
    ],
    "tags": [
        { "id": "t0", "gkbId": "G3052772", "stdForm": "Emmanuel Macron", "type": "media", "relevance": 22.605, "feats": { "wikidataId": "Q3052772" } },
        { "id": "t1", "gkbId": "G183", "stdForm": "Germany", "type": "media", "relevance": 18.365, "feats": { "wikidataId": "Q183" } },
        { "id": "t2", "gkbId": "G1726", "stdForm": "Munich", "type": "media", "relevance": 7.57, "feats": { "wikidataId": "Q1726" } }
    ],
    "relations": [..],
    "docSentiment": { "mean": 0.0, "label": "neutral", "positive": 0.0, "negative": 0.0 },
    "usedChars": 100,
    "metadata": {"referenceKey": "311441-120020-a24f0281"}
}

Python

{
    "version": "3.2.1",
    "id": "1234",
    "language": { "detected": "en" },
    "entities": [
        { "id": "e0", "gkbId": "G57305", "stdForm": "trade fair", "type": "general" },
        { "id": "e1", "gkbId": "G183", "stdForm": "Germany", "type": "location" },
        { "id": "e2", "gkbId": "G1726", "stdForm": "Munich", "type": "location" },
        { "id": "e3", "gkbId": "G3052772", "stdForm": "Emmanuel Macron", "type": "person" },
        { "id": "e4", "gkbId": "G183", "stdForm": "Germany", "type": "country", "feats": {"derivedBy": "gkb2:[gkbp:adminCountry]" } },
        { "id": "e5", "gkbId": "G980", "stdForm": "Bavaria", "type": "region", "feats": { "derivedBy": "gkb2:[gkbp:region]" } }
    ],
    "tags": [
        { "id": "t0", "gkbId": "G3052772", "stdForm": "Emmanuel Macron", "type": "media", "relevance": 22.605, "feats": { "wikidataId": "Q3052772" } },
        { "id": "t1", "gkbId": "G183", "stdForm": "Germany", "type": "media", "relevance": 18.365, "feats": { "wikidataId": "Q183" } },
        { "id": "t2", "gkbId": "G1726", "stdForm": "Munich", "type": "media", "relevance": 7.57, "feats": { "wikidataId": "Q1726" } }
    ],
    "relations": [..],
    "docSentiment": { "mean": 0.0, "label": "neutral", "positive": 0.0, "negative": 0.0 },
    "usedChars": 100,
    "metadata": {"referenceKey": "311441-120020-a24f0281"}
}

Python SDK

Entities:
    general: trade fair (G57305)
    location: Germany (G183)
    location: Munich (G1726)
    person: Emmanuel Macron (G3052772)
    country: Germany (G183)
    region: Bavaria (G980)
Tags:
    media: Emmanuel Macron (G3052772) relevance: 22.605
    media: Germany (G183) relevance: 18.365
    media: Munich (G1726) relevance: 7.57

Next Steps

For more advanced uses of the tagging API, see this guide article. The guide describes also other topics: photo suggestions, feedback loop, knowledge base, etc.