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