Knowledge Base API

Overview

The Knowledge Base API (GKB) provides endpoints for retrieving real-world information about tags and entities, such as details, infoboxes, redirects, and standard forms.

Endpoints

Endpoint	Description
	Request	200 Response
POST /v2/knowledgebase/details	Retrieves detailed information about tags and entities.
	GkbItemsInfoRequest	Map[string, Details]
POST /v2/knowledgebase/infoboxes	Retrieves information about tags and entities optimized for UI display.
	GkbItemsInfoRequest	Map[string, LangValueInfoBox]
POST /v2/knowledgebase/redirects	Returns replacements for deprecated knowledge base entities.
	GkbItemsRedirectsRequest	List[Redirects]
POST /v2/knowledgebase/search	Searches the knowledge base for entities.
	GkbItemsSearchRequest	List[SearchResults]
POST /v2/knowledgebase/stdforms	Retrieves standard forms of tags and entities for a given language.
	GkbItemsStdFormRequest	Map[string, LangValueString]

POST /v2/knowledgebase/details

Retrieves detailed information about tags and entities.

• Request: GkbItemsInfoRequest
• Response: Map[string, Details]

Example

KB Details

Request

JavaScript

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

input = {
    ids: ['Q42'],
    language: 'en',
    externalSource: 'wikidata'
};

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

Python

def kbDetails(input: Mapping[str, Any]):
    return requests.post(f'{BASE_URL}knowledgebase/details', json=input, headers=HEADERS).json()

input = {
    'ids': ['Q42'],
    'language': 'en',
    'externalSource': 'wikidata',
}

kbDetails(input)

Response

JavaScript

{
    Q42: {
        gkbId: "G42",
        stdForm: {
            value: "Douglas Adams",
            language: "en"
        },
        description: {
            value: "English science fiction writer and humorist (1952–2001)",
            language: "en"
        },
        type: "person",
        subtypes: [],
        externalIds: {
            wikidata: "Q42"
        },
        externalLinks: {
            "enwiki": "https://en.wikipedia.org/wiki/Douglas_Adams",
            "wikidata": "https://www.wikidata.org/entity/Q42"
        }
    }
}

Python

{
    'Q42': {
        'gkbId': 'G42',
        'stdForm': {
            'value': 'Douglas Adams',
            'language': 'en',
        },
        'description': {
            'value': 'English science fiction writer and humorist (1952–2001)',
            'language': 'en',
        },
        'type': 'person',
        'subtypes': [],
        'externalIds': {
            'wikidata': 'Q42',
        },
        'externalLinks': {
            'enwiki': 'https://en.wikipedia.org/wiki/Douglas_Adams',
            'wikidata': 'https://www.wikidata.org/entity/Q42',
        }
    }
}

POST /v2/knowledgebase/infoboxes

Retrieves information about tags and entities optimized for UI display.

• Request: GkbItemsInfoRequest
• Response: Map[string, LangValueInfoBox]

Example

KB Infoboxes

Request

JavaScript

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

input = {
    ids: ['G458', 'G567'],
    language: 'fr'
};

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

Python

def kbInfoBoxes(input: Mapping[str, Any]):
    return requests.post(f'{BASE_URL}knowledgebase/infoboxes', json=input, headers=HEADERS).json()

input = {
    'ids': ['G458', 'G567'],
    'language': 'fr',
}

kbInfoBoxes(input)

Response

JavaScript

{
    G458: {
    value: {
    title: "Union européenne",
    header: "union politico-économique sui generis d'États européens",
    body: "",
    footer: {
    cswiki: "https://cs.wikipedia.org/wiki/Evropská_unie",
    enwiki: "https://en.wikipedia.org/wiki/European_Union",
    wikidata: "https://www.wikidata.org/entity/Q458",
},
},
    language: "fr",
},
    G567: {
    value: {
    title: "Angela Merkel",
    header: "chancelière fédérale allemande",
    body: "",
    footer: {
    cswiki: "https://cs.wikipedia.org/wiki/Angela_Merkelová",
    enwiki: "https://en.wikipedia.org/wiki/Angela_Merkel",
    facebook: "https://www.facebook.com/AngelaMerkel",
    instagram: "https://www.instagram.com/bundeskanzlerin",
    wikidata: "https://www.wikidata.org/entity/Q567",
},
},
    language: "fr",
},
}

Python

{
    'G458': {
    'value': {
    'title': 'Union européenne',
    'header': 'union politico-économique sui generis d\'États européens',
    'body': '',
    'footer': {
    'cswiki': 'https://cs.wikipedia.org/wiki/Evropská_unie',
    'enwiki': 'https://en.wikipedia.org/wiki/European_Union',
    'wikidata': 'https://www.wikidata.org/entity/Q458',
},
},
    'language': 'fr',
},
    'G567': {
    'value': {
    'title': 'Angela Merkel',
    'header': 'chancelière fédérale allemande',
    'body': '',
    'footer': {
    'cswiki': 'https://cs.wikipedia.org/wiki/Angela_Merkelová',
    'enwiki': 'https://en.wikipedia.org/wiki/Angela_Merkel',
    'facebook': 'https://www.facebook.com/AngelaMerkel',
    'instagram': 'https://www.instagram.com/bundeskanzlerin',
    'wikidata': 'https://www.wikidata.org/entity/Q567',
},
},
    'language': 'fr',
},
}

POST /v2/knowledgebase/redirects

Returns replacements for deprecated knowledge base entities.

• Request: GkbItemsRedirectsRequest
• Response: List[Redirects]

Example

KB Redirects

Request

JavaScript

const itemRedirects = async (ids, config) => {
    const response = await axios.post('/knowledgebase/redirects', {gkbIds: ids}, config)
    return response.data;
};

ids = ['G1', 'G22262439', 'G8ad70d13-E', 'Gfd6d708c-C'];

itemRedirects(ids, config).then(report);

Python

def itemRedirects(ids: List[str]):
    return requests.post(f'{BASE_URL}/knowledgebase/redirects', json={'gkbIds': ids}, headers=HEADERS).json()

ids = ['G1', 'G22262439', 'G8ad70d13-E', 'Gfd6d708c-C']

itemRedirects(ids)

Response

JavaScript

{
    G1: {status: 'active'},
    G22262439: {status: 'active', replaces: ['G8ad70d13-E', 'Gfd6d708c-C']},
    G8ad70d13-E: {status: 'inactive', replacedBy: 'G22262439'},
    Gfd6d708c-C: {status: 'inactive', replacedBy: 'G22262439'}
}

Python

{
    'G1': {'status': 'active'},
    'G22262439': {'status': 'active', 'replaces': ['G8ad70d13-E', 'Gfd6d708c-C']},
    'G8ad70d13-E': {'status': 'inactive', 'replacedBy': 'G22262439'},
    'Gfd6d708c-C': {'status': 'inactive', 'replacedBy': 'G22262439'}
}

POST /v2/knowledgebase/search

Searches the knowledge base for entities.

• Request: GkbItemsSearchRequest
• Response: List[SearchResults]

Example

KB Search

Request

JavaScript

const itemSearch = async (query, lang) => {
    const response = await axios.post('knowledgebase/search', {query: query, language: lang}, config)
    return response.data;
};

Python

def itemSearch(query: str, lang: str):
    return requests.post(
        f'{BASE_URL}knowledgebase/search',
        json={'query': query, 'language': lang},
        headers=HEADERS
    ).json()

Response

JavaScript

itemSearch('Jordan', 'en').then(report);

{
    query: 'Jordan',
    hits: 1,
    itemDetails: [
    {
        gkbId: 'G810',
        stdForm: {value: 'Jordan', language: 'en'},
        description: {value: 'constitutional monarchy in Western Asia', language: 'en'},
        type: 'location'
    }
    ]
}

Python

itemSearch('Jordan', 'en')

{
    'query': 'Jordan',
    'hits': 1,
    'itemDetails': [
    {
        'gkbId': 'G810',
        'stdForm': {'value': 'Jordan', 'language': 'en'},
        'description': {'value': 'constitutional monarchy in Western Asia', 'language': 'en'},
        'type': 'location'
    }
    ]
}

POST /v2/knowledgebase/stdforms

Retrieves standard forms of tags and entities for a given language.

• Request: GkbItemsStdFormRequest
• Response: Map[string, LangValueString]

Example

KB Standard Forms

Request

JavaScript

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

input = {
    ids: ['G458', 'G567'],
    language: 'pl',
};

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

Python

def kbStdForms(input: Mapping[str, Any]):
    return requests.post(f'{BASE_URL}knowledgebase/stdforms', json=input, headers=HEADERS).json()

input = {
    'ids': ['G458', 'G567'],
    'language': 'pl',
}

kbStdForms(input)

Response

JavaScript

{
    G458: { value: 'Unia Europejska', language: 'pl' },
    G567: { value: 'Angela Merkel', language: 'pl' }
}

Python

{
    'G458': {'value': 'Unia Europejska', 'language': 'pl'},
    'G567': {'value': 'Angela Merkel', 'language': 'pl'}
}