Net::Calais - Interface to OpenCalais web service

Net-Calais documentation Contained in the Net-Calais distribution.

Index

Code Index:

NAME

Top

Net::Calais - Interface to OpenCalais web service

SYNOPSIS

Top

    use Net::Calais;

    my $calais = Net::Calais->new(apikey => 'akljelkjde3jlkj2i2l2');
    print $calais->enlighten($html, contentType => 'text/html');

METHODS

Top

new()
	Net::Calais->new(PARAM => ...);

Acceptable parameters:

apikey

The API key used for authentication with the service.

enlighten()
	$calais->enlighten($data, PARAM => ...);

Submits text to the OpenCalais web service.

Optional parameters:

contentType

Format of the input content (may be text/raw, text/txt/, text/html, text/xml). Unless specified, text/txt is assumed.

outputFormat

Format of the server response. Unless specified, XML/RDF is assumed.

reltagBaseURL
calculateRelevanceScore
enableMetadataType
discardMetadata
allowDistribution
allowSearch
externalID
submitter
externalMetadata

This should be a RDF representation of your additional metadata (see OpenCalais docs).

See http://opencalais.com/APIcalls#inputparameters for description of such parameters.

semanticproxy()
	$calais->semanticproxy($url, PARAM => ...);

Submits text to the SemanticProxy web service.

Optional parameters:

output

Format of the requested output (may be html, rdf or microformat).

PACKAGE VARIABLES

Top

$CALAIS_URL

By modifying the $Net::Calais::CALAIS_URL variable you can set a custom URL for REST requests. The default value is http://api.opencalais.com/enlighten/rest/. This may be useful to use the beta service which is usually located at beta.opencalais.com.

$SEMANTICPROXY_URL

By modifying the $Net::Calais::SEMANTICPROXY_URL variable you can set a custom base URL for SemanticProxy REST requests. The default value is http://service.semanticproxy.com/processurl/.

SEE ALSO

Top

http://opencalais.com/

BUGS AND FEEDBACK

Top

You are very welcome to write mail to the maintainer (aar@cpan.org) with your contributions, comments, suggestions, bug reports or complaints.

COPYRIGHT

Top

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Top

Alessandro Ranellucci <aar@cpan.org>

Net-Calais documentation Contained in the Net-Calais distribution. 
# ===========================================================================
# Net::Calais
# 
# Interface to OpenCalais web service
# 
# Alessandro Ranellucci <aar@cpan.org>
# 
package Net::Calais;
use strict;
use warnings;

use HTTP::Request::Common;
use LWP::UserAgent;
use XML::Writer;

our $VERSION = '1.02';

our $CALAIS_URL = 'http://api.opencalais.com/enlighten/rest/';
our $SEMANTICPROXY_URL = 'http://service.semanticproxy.com/processurl/';

#--
sub new {
    my ($class, %params) = @_;
    die "Calais apikey required\n" unless $params{apikey};
    my $self = { apikey => $params{apikey} };
    $self->{ua} = LWP::UserAgent->new() or return undef;
    bless $self, $class;
    return $self;
}
#--
sub enlighten {
    my __PACKAGE__ $self = shift;
    my ($content, %params) = @_;
    
    # process user params and set some defaults
    my %request_params = (licenseID => $self->{apikey}, content => $content);
    my (%processingDirectives, %userDirectives) = ();
    $processingDirectives{'c:contentType'} = $params{contentType} || 'text/txt';
    $processingDirectives{'c:outputFormat'} = $params{outputFormat} || 'XML/RDF';
    for (qw(reltagBaseURL calculateRelevanceScore enableMetadataType discardMetadata)) {
        $processingDirectives{"c:$_"} = $params{$_} if $params{$_};
    }
    for (qw(allowDistribution allowSearch externalID submitter)) {
        $userDirectives{"c:$_"} = $params{$_} if $params{$_};
    }
    
    # build the paramxXML parameter
    my $xmlWriter = XML::Writer->new(
        OUTPUT => \$request_params{paramsXML},
        DATA_MODE => 1,
        DATA_INDENT => 0,
        ENCODING => 'UTF-8'
    );
    $xmlWriter->startTag('c:params',
        'xmlns:c' => 'http://s.opencalais.com/1/pred/',
        'xmlns:rdf' => 'http://www.w3.org/1999/02/22-rdf-syntax-ns#');
    $xmlWriter->startTag('c:processingDirectives', %processingDirectives);
    $xmlWriter->endTag('c:processingDirectives');
    $xmlWriter->startTag('c:userDirectives', %userDirectives);
    $xmlWriter->endTag('c:userDirectives');    
    $xmlWriter->startTag('c:externalMetadata');
    $xmlWriter->raw($params{externalMetadata}) if $params{externalMetadata};
    $xmlWriter->endTag('c:externalMetadata');
    $xmlWriter->endTag('c:params');
    $xmlWriter->end;
    
    # do REST request and return response
    my $response = $self->{ua}->request(POST $CALAIS_URL, \%request_params);
    if (!$response->is_success) {
        $self->{error} = $response->status_line;
        return undef;
    }
    return $response->content;
}
#--
sub semanticproxy {
    my __PACKAGE__ $self = shift;
    my ($url, %params) = @_;
    
    die "URL is required\n" unless $url;
    $params{output} ||= 'html';
    
    my $reqUrl = sprintf("%s%s/%s/%s", $SEMANTICPROXY_URL, $self->{apikey}, $params{output}, $url);
    my $response = $self->{ua}->request(GET $reqUrl);
    if (!$response->is_success) {
        $self->{error} = $response->status_line;
        return undef;
    }
    return $response->content;
}
#--
1;
__END__