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):

// 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

# 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>'
}

# Geneea NLP client SDK; see https://help.geneea.com/sdk/index.html
# The SDK can be used for 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 -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."
}'

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

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);

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)

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).

{
  "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"}
}

{
  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'}
}

{
  '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'}
}

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.