In order to call our REST API, one needs a JSON parser and a HTTP client. In this example, we will use Jackson and Apache HttpClient. Below we show dependency declaration for Maven.



The examples below show how to call the General API from Java. Expected inputs and outputs are described in G3 API Reference.

First, you create a very simple API client.

import java.util.List;
import java.util.Map;

import org.apache.commons.codec.Charsets;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.ByteArrayEntity;
import org.apache.http.entity.ContentType;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;
import com.fasterxml.jackson.databind.ObjectMapper;

public class GeneeaApi {

    private static final String USER_KEY = "<your user key>";

    private static final String URL = "";
    private static final CloseableHttpClient CLIENT = HttpClients.createDefault();
    private static final ObjectMapper MAPPER = new ObjectMapper();

    public static String call(String text, String... analyses) throws Exception {
        // prepare JSON request body
        byte[] jsonBody = MAPPER.writeValueAsBytes(
                Map.of("text", text, "analyses", List.of(analyses))

        // prepare HTTP request
        HttpPost httpPost = new HttpPost(URL);
        httpPost.addHeader("Authorization", "user_key " + USER_KEY);
        httpPost.setEntity(new ByteArrayEntity(jsonBody, ContentType.APPLICATION_JSON));

        // perform the HTTP request
        try (CloseableHttpResponse response = CLIENT.execute(httpPost)) {
            return EntityUtils.toString(response.getEntity(), Charsets.UTF_8);

Then you can use it as follows.

String result ="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

You can restrict the type of analyses. For example, requesting only entities will produce the following simpler result:

String result ="The pizza in London was great!", "entities");
{'language': {'detected': 'en'}, 'entities': [{'id': 'E0', 'gkbId': 'hash_dc386592', 'stdForm': 'London', 'type': 'location'}], 'usedChars': 100}

For using the results in a code, they should be deserialized from JSON into an appropriate objects.

String result ="The pizza in London was great!", "sentiment");
Map resObj = new ObjectMapper().readValue(result, Map.class);
Map sentiment = (Map) resObj.get("docSentiment");