C#

The examples below show how to call the General API from C#. It requires http://restsharp.org/, a REST client for C#. Replace <YOUR USER KEY> with the actual key. Expected inputs and outputs are described in G3 API Reference.

The code was kindly provided by Alvar.

Simple Call

Executing this simple code:

namespace GeneeaApiTest
{
    class Program
    {
        static void Main(string[] args)
        {
            string API_BASE_URL = "https://api.geneea.com/";
            string USER_KEY = "<YOUR USER KEY>";

            // Get full response
            var restRequest = new RestRequest("v3/analysis", Method.GET);

            // You need your API key for all calls
            restRequest.AddHeader("Authorization", String.Format("user_key {0}", USER_KEY));

            // Text to by analysed
            restRequest.AddParameter("text", "The pizza in London was great!");

            var response = new RestClient(API_BASE_URL).Execute(restRequest)
            Console.WriteLine(response.Content);
        }
    }
}

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
}

Deserialization

In most cases it is better to use the automatic deserialization of RestSharp:

namespace GeneeaApiTest
{
    class Program
    {
        static void Main(string[] args)
        {
            // Get full response
            var response = GeneeaRestApiExample.GetGeneeaTextAnalysisResponse<GeneeaTextAnalysisResponse>("The pizza in London was great!");
            Console.WriteLine(string.Format("Language: '{0}'", response.Language.Detected));
            Console.WriteLine(string.Format("Mean sentiment: '{0}'", response.DocSentiment.Mean));
        }
    }

    public class GeneeaRestApiExample
    {
        private static string API_BASE_URL = "https://api.geneea.com/";
        private static string USER_KEY = "<YOUR USER KEY>";

        public static T GetGeneeaTextAnalysisResponse<T>(string input) where T : new()
        {
            var restRequest = new RestRequest("v3/analysis", Method.GET);

            // You need your API key for all calls
            restRequest.AddHeader("Authorization", String.Format("user_key {0}", USER_KEY));

            // Text to by analysed
            restRequest.AddParameter("text", input);

            var client = new RestClient(API_BASE_URL);
            var response = client.Execute<T>(restRequest);
            return response.Data;
        }
    }
}

Obviously, we need to define basic DTO classes:

namespace GeneeaApiTest
{
    public class GeneeaTextAnalysisResponse
    {
        public Language Language { get; set; }
        public List<Entity> Entities { get; set; }
        public List<Tag> Tags { get; set; }
        public List<Relation> Relations { get; set; }
        public Sentiment DocSentiment { get; set; }
        public int UsedChars { get; set; }
    }

    public class Entity
    {
        public string Id { get; set; }
        public string GkbId { get; set; }
        public string StdForm { get; set; }
        public string Type { get; set; }
    }

    public class Tag
    {
        public string Id { get; set; }
        public decimal Relevance { get; set; }
        public string StdForm { get; set; }
        public string Type { get; set; }
    }

    public class Relation
    {
        public string Id { get; set; }
        public string Name { get; set; }
        public string TextRepr { get; set; }
        public string Type { get; set; }
        public List<Arg> Args { get; set; }
        public List<Feat> Feats { get; set; }
    }

    public class Arg
    {
        public string Type { get; set; }
        public string Name { get; set; }
    }

    public class Feat
    {
        public string Negated { get; set; }
        public string Modality { get; set; }
    }

    public class Sentiment
    {
        public string Label { get; set; }
        public decimal Mean { get; set; }
        public decimal Positive { get; set; }
        public decimal Negative { get; set; }
    }

    public class Language
    {
        public string Detected { get; set; }
    }
}

Basic Analysis options

The analysis can be configured in several ways. See Request for the list of parameters and their possible values. Here we show, how to:

• restrict the the type of possible analyses: In the code above, all available analyses were returned. We can restrict only some of them. For example, we can set the analyses parameter to entities.

• use the domain parameter to invoke analysers tuned for a particular domain.

First, we need to modify GetGeneeaTextAnalysisResponse so that it passes additional parameters to the API:

public static T GetGeneeaTextAnalysisResponse<T>(string input, IList<string> analyses = null, string domain = "") where T : new()
{
    var restRequest = new RestRequest("v3/analysis", Method.GET);

    // You need your API key for all calls
    restRequest.AddHeader("Authorization", String.Format("user_key {0}", USER_KEY));

    // Text to by analysed
    restRequest.AddParameter("text", input);

    // You can restrict the type of analyses
    if (analyses != null && analyses.Count > 0)
    {
        foreach (var a in analyses)
        {
            restRequest.AddParameter("analyses", a);
        }
    }

    // You use an analyzer tuned for a particular domain
    if (!string.IsNullOrEmpty(domain))
    {
        restRequest.AddParameter("domain", domain);
    }

    var client = new RestClient(API_BASE_URL);
    var response = client.Execute<T>(restRequest);
    return response.Data;
}

Now we can use it to either restrict the set of analyses, or specify the analysis domain, or both. Note that the media domain analyzer considers locations, but not food expressios as being entities, while the voc-hospitality domain analyzer considers food, but not locations as being entities.

class Program
{
    static void Main(string[] args)
    {
        // Restrict the type of analyses
        response = GeneeaRestApiExample.GetGeneeaTextAnalysisResponse<GeneeaTextAnalysisResponse>("The pizza in London was great!", new[] { "entities", "tags" });
        Console.WriteLine(string.Format("Number of entities: '{0}'", response.Entities.Count));
        Console.WriteLine(string.Format("Number of tags: '{0}'", response.Tags.Count));
        Console.WriteLine(string.Format("No relations: '{0}'", response.Relations == null));

        // Use analysis tuned for the media domain
        EntitiesForDomain("The pizza in London was great!", "media");

        // Use analysis tuned for the voice-of-the-customer in hospitality
        EntitiesForDomain("The pizza in London was great!", "voc-hospitality");
    }

    static void EntitiesForDomain(string input, string domain)
    {
        Console.WriteLine(string.Format("Entities for domain = '{0}':", domain);
        response = GeneeaRestApiExample.GetGeneeaTextAnalysisResponse<GeneeaTextAnalysisResponse>(input, new[] { "entities" }, domain);
        foreach (var e in response.Entities)
        {
            Console.WriteLine(string.Format("Entity: stdForm = '{0}', type = '{1}'", e.StdForm, e.Type);
        }
    }
}

Output:

Number of entities: '1'
Number of tags: '3'
No relations: 'True'

Entities for domain = 'media':
Entity: stdForm = 'London', type = 'location'

Entities for domain = 'voc-hospitality':
Entity: stdForm = 'pizza', type = 'food'

Linking to Geneea Knowledge Base

Entities and tags can be linked to Geneea Knowledge Base. This is not done in the default domain, but for example, analysis for the media domain will link London to GKB item G84. Various domains link entities of various types (e.g., voc-hospitality links food entities).

class Program
{
    static void Main(string[] args)
    {
        response = GeneeaRestApiExample.GetGeneeaTextAnalysisResponse<GeneeaTextAnalysisResponse>("The pizza in London was great!", new[] { "entities" }, "media");
        Console.WriteLine(response.Entities[0].GkbId); // "G84"
    }
}

We can use the media endpoint to query Geneea Knowledge Base (note that you need the X-Customer-ID for this):

class Program
{
    static void Main(string[] args)
    {
        response = GeneeaRestApiExample.GetGeneeaTextAnalysisResponse<GeneeaTextAnalysisResponse>("The pizza in London was great!", new[] { "entities" }, "media");
        var itemId = response.Entities[0].GkbId; // "G84"
        var gkbResponse = GeneeaRestApiExample.GetGeneeaKnowledgeBaseResponse<GeneeaKnowledgeBaseResponse>(itemId);
        foreach (var desc in gkbResponse.Descriptions)
        {
            Console.WriteLine(string.Format("GKBItem '{0}': {1} description: '{2}'", itemId, desc.Language, desc.Text));
        }
}

public class GeneeaRestApiExample
{
    private static string CUSTOMER_ID = "<YOUR CUSTOMER ID>";

    ...

    // Query Geneea Knowledge Base
    public static T GetGeneeaKnowledgeBaseResponse<T>(string id) where T : new()
    {
        var restRequest = new RestRequest(string.Format("media/items/{0}", id), Method.GET);

        // You need your API key for all calls
        restRequest.AddHeader("Authorization", String.Format("user_key {0}", USER_KEY));

        // You need customer id too
        restRequest.AddHeader("X-Customer-ID", CUSTOMER_ID);

        var client = new RestClient(API_BASE_URL);
        var response = client.Execute<T>(restRequest);
        return response.Data;
    }
}

public class GeneeaKnowledgeBaseResponse
{
    public string Id { get; set; }
    public string Hrid { get; set; }
    public List<Description> Descriptions { get; set; }
    public List<Description> Labels { get; set; }
}

public class Description
{
    public string Text { get; set; }
    public string Language { get; set; }
}

Output:

GKBItem 'G84': en description: 'capital of England and the United Kingdom'
GKBItem 'G84': cs description: 'hlavní město Anglie a Spojeného království'

Full code

namespace GeneeaApiTest
{
    class Program
    {
        static void Main(string[] args)
        {
            // Get full response
            var response = GeneeaRestApiExample.GetGeneeaTextAnalysisResponse<GeneeaTextAnalysisResponse>("The pizza in London was great!");
            Console.WriteLine(string.Format("Language is '{0}', mean sentiment is '{1}'", response.Language.Detected, response.DocSentiment.Mean));

            // You can restrict the type of analyses
            response = GeneeaRestApiExample.GetGeneeaTextAnalysisResponse<GeneeaTextAnalysisResponse>("The pizza in London was great!", new[] { "entities", "tags" });
            Console.WriteLine(string.Format("Number of entities: '{0}'", response.Entities.Count));
            Console.WriteLine(string.Format("Number of tags: '{0}'", response.Tags.Count));
            Console.WriteLine(string.Format("No relations: '{0}'", response.Relations == null));

            // We can also use the media domain to have entities linked to Geneea Knowledge Base ...
            response = GeneeaRestApiExample.GetGeneeaTextAnalysisResponse<GeneeaTextAnalysisResponse>("The pizza in London was great!", new[] { "entities" }, "media");
            Console.WriteLine(string.Format("Number of entities: '{0}'", response.Entities.Count));

            // ... and can use the media endpoint to query Geneea Knowledge Base (note that you need the X-Customer-ID for this)
            var itemId = response.Entities[0].GkbId; // "G84"
            var gkbResponse = GeneeaRestApiExample.GetGeneeaKnowledgeBaseResponse<GeneeaKnowledgeBaseResponse>(itemId);
            Console.WriteLine(string.Format("Number of descriptions: '{0}'", gkbResponse.Descriptions.Count));
            Console.WriteLine(string.Format("Number of labels: '{0}'", gkbResponse.Labels.Count));
        }
    }

    public class GeneeaRestApiExample
    {
        private static string API_BASE_URL = "https://api.geneea.com/";
        private static string USER_KEY = "<YOUR USER KEY>";
        private static string CUSTOMER_ID = "<YOUR CUSTOMER ID>";

        public static T GetGeneeaTextAnalysisResponse<T>(string input, IList<string> analyses = null, string domain = "") where T : new()
        {
            var restRequest = new RestRequest("v3/analysis", Method.GET);

            // You need your API key for all calls
            restRequest.AddHeader("Authorization", String.Format("user_key {0}", USER_KEY));

            // Text to by analysed
            restRequest.AddParameter("text", input);

            // You can restrict the type of analyses
            if (analyses != null && analyses.Count > 0)
            {
                foreach (var a in analyses)
                {
                    restRequest.AddParameter("analyses", a);
                }
            }

            // You use an analyzer tuned for a particular domain (media domains link entities to Geneea Knowledge Base)
            if (!string.IsNullOrEmpty(domain))
            {
                restRequest.AddParameter("domain", domain);
            }

            var client = new RestClient(API_BASE_URL);
            var response = client.Execute<T>(restRequest);
            return response.Data;
        }

        // Query Geneea Knowledge Base
        public static T GetGeneeaKnowledgeBaseResponse<T>(string id) where T : new()
        {
            var restRequest = new RestRequest(string.Format("media/items/{0}", id), Method.GET);

            // You need your API key for all calls
            restRequest.AddHeader("Authorization", String.Format("user_key {0}", USER_KEY));

            // You need customer id too
            restRequest.AddHeader("X-Customer-ID", CUSTOMER_ID);

            var client = new RestClient(API_BASE_URL);
            var response = client.Execute<T>(restRequest);
            return response.Data;
        }
    }

    public class GeneeaTextAnalysisResponse
    {
        public Language Language { get; set; }
        public List<Entity> Entities { get; set; }
        public List<Tag> Tags { get; set; }
        public List<Relation> Relations { get; set; }
        public Sentiment DocSentiment { get; set; }
        public int UsedChars { get; set; }
    }

    public class GeneeaKnowledgeBaseResponse
    {
        public string Id { get; set; }
        public string Hrid { get; set; }
        public List<Description> Descriptions { get; set; }
        public List<Description> Labels { get; set; }
    }

    public class Description
    {
        public string Text { get; set; }
        public string Language { get; set; }
    }

    public class Entity
    {
        public string Id { get; set; }
        public string GkbId { get; set; }
        public string StdForm { get; set; }
        public string Type { get; set; }
    }

    public class Tag
    {
        public string Id { get; set; }
        public decimal Relevance { get; set; }
        public string StdForm { get; set; }
        public string Type { get; set; }
    }

    public class Relation
    {
        public string Id { get; set; }
        public string Name { get; set; }
        public string TextRepr { get; set; }
        public string Type { get; set; }
        public List<Arg> Args { get; set; }
        public List<Feat> Feats { get; set; }
    }

    public class Arg
    {
        public string Type { get; set; }
        public string Name { get; set; }
    }

    public class Feat
    {
        public string Negated { get; set; }
        public string Modality { get; set; }
    }

    public class Sentiment
    {
        public string Label { get; set; }
        public decimal Mean { get; set; }
        public decimal Positive { get; set; }
        public decimal Negative { get; set; }
    }

    public class Language
    {
        public string Detected { get; set; }
    }
}