cURL

The examples below show how to call the General API using cURL from the commandline. Expected inputs and outputs of individual is described in G3 API Reference.

Basic Calls

The following call:

curl -X POST https://api.geneea.com/v3/analysis \
  -H 'Authorization: user_key <your user key>' \
  -H 'Content-Type: application/json' \
  -d '{"text": "The pizza in London was great!"}'

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

{
    'language': {'detected': 'en'},
    'entities': [{'id': 'E0', 'gkbId': 'hash_dc386592', 'stdForm': 'London', 'type': 'location'}],
    'tags': [
        {'id': 'T0', 'stdForm': 'London', 'type': 'ENTITIES', 'relevance': 1.0},
        {'id': 'T1', 'stdForm': 'pizza', 'type': 'KEYWORDS', 'relevance': 0.462},
        {'id': 'T2', 'stdForm': 'great', 'type': 'KEYWORDS', 'relevance': 0.284}
    ],
    'relations': [
        {
            'id': 'R0',
            'name': 'great',
            'textRepr': 'great(pizza)',
            'type': 'ATTR',
            'args': [{'type': 'SUBJECT', 'name': 'pizza'}],
            'feats': {'negated': 'false', 'modality': ''}
        }
    ],
    'docSentiment': {'mean': 0.6, 'label': 'positive', 'positive': 0.6, 'negative': 0.0},
    'usedChars': 100
}

Note that in Windows, you need to replace single quotes with double quotes and then escape double quotes inside of the json payload:

curl -X POST https://api.geneea.com/v3/analysis \
  -H "Authorization: user_key <your user key>" \
  -H "Content-Type: application/json" \
  -d "{\"text\": \"The pizza in London was great!\"}"

You can restrict the type of analyses. For example, requesting only entities (see Request for a list of all possible analyses values) will produce the following simpler result:

curl -X POST https://api.geneea.com/v3/analysis \
  -H 'Authorization: user_key <your user key>' \
  -H 'Content-Type: application/json' \
  -d '{"text": "The pizza in London was great!", "analyses": ["entities"]}'

{'language': {'detected': 'en'}, 'entities': [{'id': 'E0', 'gkbId': 'hash_dc386592', 'stdForm': 'London', 'type': 'location'}], 'usedChars': 100}

Linking to Geneea Knowledgebase

We can also use the media domain to have entities linked to Geneea Knowledge Base (at this moment, only media domains link locations):

curl -X POST https://api.geneea.com/v3/analysis \
  -H 'Authorization: user_key <your user key>' \
  -H 'Content-Type: application/json' \
  -d '{"text": "The pizza in London was great!", "analyses": ["entities"], "domain": "media"}'

{'language': {'detected': 'en'}, 'entities': [{'id': 'E0', 'gkbId': 'G84', 'stdForm': 'London', 'type': 'location'}], 'usedChars': 100}

We can use the media endpoint to query Geneea Knowledge Base (note that you need the X-Customer-ID for this; email us at help@geneea.com):

curl -X GET https://api.geneea.com/media/items/G84
  -H 'Authorization: user_key <your user key>'
  -H 'X-Customer-ID: <your customer id>'
  -H 'Content-Type: application/json'

{
    'id': 'G84',
    'hrid': 'London (G84)',
    'descriptions': [
        {'text': 'capital of England and the United Kingdom', 'language': 'en'},
        {'text': 'hlavní město Anglie a Spojeného království', 'language': 'cs'}],
    ...
}