Java

Dependencies

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.

<dependencies>
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
        <version>2.9.8</version>
    </dependency>
    <dependency>
        <groupId>org.apache.httpcomponents</groupId>
        <artifactId>httpclient</artifactId>
        <version>4.5.7</version>
    </dependency>
</dependencies>

Example

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 = "https://api.geneea.com/v3/analysis";
    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 = GeneeaApi.call("The pizza in London was great!");
System.out.println(result);

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 = GeneeaApi.call("The pizza in London was great!", "entities");
System.out.println(result);

{'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 = GeneeaApi.call("The pizza in London was great!", "sentiment");
Map resObj = new ObjectMapper().readValue(result, Map.class);
Map sentiment = (Map) resObj.get("docSentiment");

System.out.println(sentiment.get("label"));

positive