Quick Start¶

For a full description of the API, see the reference guide.

Note

The Media API V1 was deprecated; use the new version instead. It offers much-improved functionality, including photo and article suggestion, entity and tag translation, derived entities, and much more.

To get tags (keywords) for an article, use the following code:

const axios = require('axios');
const callGeneea = async (input) => {
    const url = 'https://api.geneea.com/media/tags';
    const options = {
        headers: {
            'content-type': 'application/json',
            'X-Customer-ID': '<your customer ID>',
            'Authorization': 'user_key <your user key>'
        }
    };
    const response = await axios.post(url, input, options);
    return response.data;
};
callGeneea({
    'id': '1',
    'date': '2019-02-03T10:15:30',
    'categories': ['science'],
    'domicile': 'Prague',
    'title': 'Amazing Discovery',
    'perex': 'Scientists made an amazing discovery about our planet.',
    'body': '<p>Scientists have found that the Earth is <b>not</b> flat!</p>'
}).then((output) => console.log(output));

import requests

def callGeneea(input):
    url = 'https://api.geneea.com/media/tags'
    headers = {
        'content-type': 'application/json',
        'X-Customer-ID': '<your customer ID>',
        'Authorization': 'user_key <your user key>'
    }
    return requests.post(url, json=input, headers=headers).json()

print(callGeneea({
    'id': '1',
    'date': '2019-02-03T10:15:30',
    'categories': ['science'],
    'domicile': 'Prague',
    'title': 'Amazing Discovery',
    'perex': 'Scientists made an amazing discovery about our planet.',
    'body': '<p>Scientists have found that the Earth is <b>not</b> flat!</p>'
}))

import axios from 'axios';

const callGeneea = async (input: any) => {
    const url = 'https://api.geneea.com/media/tags';
    const options = {
        headers: {
            'content-type': 'application/json',
            'X-Customer-ID': '<your customer ID>',
            Authorization: 'user_key <your user key>',
        },
    };
    const response = await axios.post(url, input, options);
    return response.data;
};

callGeneea({
    id: '1',
    date: '2019-02-03T10:15:30',
    categories: ['science'],
    domicile: 'Prague',
    title: 'Amazing Discovery',
    perex: 'Scientists made an amazing discovery about our planet.',
    body: '<p>Scientists have found that the Earth is <b>not</b> flat!</p>'
}).then((output) => console.log(output));

produces the following results (see the TagsResponse reference page for explanation):

{
  version: 'M1.0',
  id: '1',
  referenceKey: '2f337473',
  tags: [ { id: 'G2', text: 'Earth', score: 6.87, type: 'location' } ]
}

The text was assigned a single tag Earth – location with the id G2 in Geneea Knowledgebase. We can query the knowledge for that id:

const axios = require('axios');
const callGkb = async (id) => {
    const url = `https://api.geneea.com/media/items/${id}`;
    const options = {
        headers: {
            'Accept': 'application/json',
            'X-Customer-ID': '<your customer ID>',
            'Authorization': 'user_key <your key>'
        }
    };
    const response = await axios.get(url, options);
    return response.data;
};
callGkb('G2').then((output) => console.log(output));

import requests

def callGkb(id):
    url = f'https://api.geneea.com/media/items/{id}'
    headers = {
        'Accept': 'application/json',
        'X-Customer-ID': '<your customer ID>',
        'Authorization': 'user_key <your key>'
    }
    return requests.get(url, headers=headers).json()

print(callGkb('G2'))

import axios from 'axios';

const callGkb = async (id: string) => {
    const url = `https://api.geneea.com/media/items/${id}`;
    const options = {
        headers: {
            Accept: 'application/json',
            'X-Customer-ID': '<your customer ID>',
            Authorization: 'user_key <your key>',
        },
    };
    const response = await axios.get(url, options);
    return response.data;
};

callGkb('G2').then((output) => console.log(output));

The output:

{
    'id': 'G2',
    'hrid': 'Earth (G2)',
    'descriptions': [
        {'text': 'třetí planeta od Slunce ve Sluneční soustavě', 'language': 'cs'},
        {'text': 'dritter Planet von der Sonne aus im Sonnensystem', 'language': 'de'},
        {'text': 'third planet from the Sun in the Solar System', 'language': 'en'}],
        {'text': 'tercer planeta desde el Sol en el Sistema solar', 'language': 'es'}],
        {'text': 'troisième planète du Système solaire', 'language': 'fr'}],
        {'text': 'trzecia planeta od Słońca', 'language': 'pl'},
    ...
}

The Media API also allows to send a feedback for the results of tagging, i.e. the correct/expected tags.

const axios = require('axios');
const callFeedback = async (input) => {
    const url = 'https://api.geneea.com/media/tags/feedback';
    const options = {
        headers: {
            'content-type': 'application/json',
            'X-Customer-ID': '<your customer ID>',
            'Authorization': 'user_key <your user key>'
        }
    }
    const response = await axios.post(url, input, options);
    return response.data;
};
callFeedback({
    'id': '1',
    'referenceKey': '0d33fdf8',
    'tags': [
        {'id': 'G111', 'text': 'Mars', 'type': 'location'}
    ]
}).then((output) => console.log(output));

import requests

def callFeedback(input):
    url = 'https://api.geneea.com/media/tags/feedback'
    headers = {
        'content-type': 'application/json',
        'X-Customer-ID': '<your customer ID>',
        'Authorization': 'user_key <your user key>'
    }
    return requests.post(url, json=input, headers=headers).json()

print(callFeedback({
    'id': '1',
    'referenceKey': '0d33fdf8',
    'tags': [
        {'id': 'G111', 'text': 'Mars', 'type': 'location'}
    ]
}))

import axios from 'axios';

const callFeedback = async (input: any) => {
    const url = 'https://api.geneea.com/media/tags/feedback';
    const options = {
        headers: {
            'content-type': 'application/json',
            'X-Customer-ID': '<your customer ID>',
            Authorization: 'user_key <your user key>',
        },
    };
    const response = await axios.post(url, input, options);
    return response.data;
};

callFeedback({
    id: '1',
    referenceKey: '0d33fdf8',
    tags: [{ id: 'G111', text: 'Mars', type: 'location' }],
}).then((output) => console.log(output));

Note that the referenceKey value in the feedback body refers to a particular API response. If omitted, the feedback is considered as “global” for a particular document id.