Perl

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

The code was kindly provided by egon choroba.

Basic Calls

Here we define a simple function call_geneea to call the General API:

#!/usr/bin/perl
use warnings;
use strict;

use Data::Dumper qw{ Dumper };
use HTTP::Tiny;
use JSON::PP qw{ encode_json decode_json };

my $user_key = '...';

sub call_geneea {
    my ($input)  = @_;
    my $url      = 'https://api.geneea.com/v3/analysis';
    my $ua       = 'HTTP::Tiny'->new;
    my $response = $ua->request(POST => $url, {
        content => encode_json($input),
        headers => {
            Authorization  => "user_key $user_key",
            'Content-Type' => 'application/json',
        },
    });
    die $response->{reason} unless $response->{success};

    return decode_json($response->{content})
}

my $input = { text => 'The pizza in London was great!' };

my $result = call_geneea($input);

print Dumper($result);

$VAR1 = {
          'relations' => [
                           {
                             'type' => 'ATTR',
                             'feats' => {
                                          'modality' => '',
                                          'negated' => 'false'
                                        },
                             'name' => 'great',
                             'textRepr' => 'great(pizza)',
                             'args' => [
                                         {
                                           'type' => 'SUBJECT',
                                           'name' => 'pizza'
                                         }
                                       ],
                             'id' => 'R0'
                           }
                         ],
          'usedChars' => 100,
          'tags' => [
                      {
                        'type' => 'KEYWORDS',
                        'relevance' => '1',
                        'stdForm' => 'London',
                        'id' => 'T0'
                      },
                      {
                        'relevance' => '0.462',
                        'stdForm' => 'pizza',
                        'id' => 'T1',
                        'type' => 'KEYWORDS'
                      },
                      {
                        'stdForm' => 'great',
                        'relevance' => '0.284',
                        'id' => 'T2',
                        'type' => 'KEYWORDS'
                      }
                    ],
          'entities' => [
                          {
                            'stdForm' => 'London',
                            'id' => 'E0',
                            'type' => 'location'
                          }
                        ],
          'docSentiment' => {
                              'positive' => '0.6',
                              'negative' => '0',
                              'label' => 'positive',
                              'mean' => '0.6'
                            },
          'language' => {
                          'detected' => 'en'
                        }
        };

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:

my $input = { text => 'The pizza in London was great!',
              analyses => ['entities'] };

$VAR1 = {
          'usedChars' => 100,
          'language' => {
                          'detected' => 'en'
                        },
          'entities' => [
                          {
                            'id' => 'E0',
                            'stdForm' => 'London',
                            'type' => 'location'
                          }
                        ]
        };

Linking to Geneea Knowledge Base

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

my $input = { text     => 'The pizza in London was great!',
           analyses => ['entities'],
           domain   => 'media'};

$VAR1 = {
          'language' => {
                          'detected' => 'en'
                        },
          'entities' => [
                          {
                            'type' => 'location',
                            'id' => 'E0',
                            'stdForm' => 'London',
                            'gkbId' => 'G84'
                          }
                        ],
          'usedChars' => 100
        };

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

#!/usr/bin/perl
use warnings;
use strict;

use Data::Dumper qw{ Dumper };
use HTTP::Tiny;
use JSON::PP qw{ encode_json decode_json };

my $user_key    = '...';
my $customer_id = '...';

sub call_gkb {
    my ($id)  = @_;
    my $url      = "https://api.geneea.com/media/items/$id";
    my $ua       = 'HTTP::Tiny'->new;
    my $response = $ua->request(GET => $url, {
        headers => {
            Accept          => 'application/json',
            Authorization   => "user_key $user_key",
            'X-Customer-ID' => $customer_id,
        },
    });
    die $response->{reason} unless $response->{success};

    return decode_json($response->{content})
}

my $result = call_gkb('G84');

print Dumper($result);

$VAR1 = {
          'id' => 'G84',
          'hrid' => 'London (G84)',
          'descriptions' => [
                              {
                                'language' => 'cs',
                                'text' => "hlavn\x{ed} m\x{11b}sto Anglie a Spojen\x{e9}ho kr\x{e1}lovstv\x{ed}"
                              },
                              {
                                'language' => 'en',
                                'text' => 'capital of England and the United Kingdom'
                              }
                            ],
          'labels' => [
                      ...
                      ]
        };

If the output should contain non-ASCII characters, you need to specify the encoding of the output. The example works for a terminal with UTF-8 encoding:

binmode *STDOUT, ':encoding(UTF-8)';
print $result->{descriptions}[0]{text}, "\n";

hlavní město Anglie a Spojeného království