• The ParaCite Web Service
• Using the Web Service from Perl
• Web Service Examples
• Web Service Structures
• ParaciteSearchResult
• ResultElement
• Metadata

The ParaCite Web Service

The Biblio::Citation::Parser package includes several examples that demonstrate the ParaCite web service, as well as the WSDL definition file. This section explains the web service, and gives an introduction to using it.

As ParaCite is written entirely in Perl, there are obvious issues if you wish to use Java, PHP, or another language. The ParaCite web services provides an interface into the reference parsing features of ParaCite, while remaining language agnostic.

Using the Web Service from Perl

To access the web service from Perl requires the SOAP::Lite module (see Required Software). Once this is present, this is all that is required to connect to the web service:

 my $service = SOAP::Lite
        -> service("http://paracite.eprints.org/paracite.wsdl";);

Three functions are now available from the $service variable:

doOpenURLConstruct($reference, $baseurl)

This returns an OpenURL, prefixed by the base URL if one is provided.

doReferenceParse($reference, $baseurl)

This returns a hash containing the metadata in the reference, and an OpenURL formed using the metadata and the base URL.

doParaciteSearch($reference, $baseurl)

This returns an hash containing 'resultElements' (an array of search results), and 'metadata' (a hash of metadata).

Web Service Examples

The following code parses a reference, and stores the metadata in $metadata and the OpenURL in $openurl:

 use SOAP::Lite;
 my $service = SOAP::Lite
        -> service("http://paracite.eprints.org/paracite.wsdl";);
 my $base_url = "http://paracite.eprints.org/cgi-bin/openurl.cgi?";;
 my $result = $service 
        -> doReferenceParse("Jewell, M (2002) Example", $base_url);
 my $metadata = $result->{metadata};
 my $openurl = $result->{openURL};

If you do not want the metadata, and just want a link to an OpenURL resolver, the following will do that:

 use SOAP::Lite;
 my $service = SOAP::Lite
        -> service("http://paracite.eprints.org/paracite.wsdl";);
 my $base_url = "http://paracite.eprints.org/cgi-bin/openurl.cgi?";;
 my $open_url = $service
        -> doOpenURLConstruct("Jewell, M (2002) Example", $base_url);
 
Finally, this example uses the doParaciteSearch method to get the first match on a reference:

 use SOAP::Lite;
 my $service = SOAP::Lite
        -> service("http://paracite.eprints.org/paracite.wsdl";);
 my $base_url = "http://paracite.eprints.org/cgi-bin/openurl.cgi?";;
 my $query = "Harnad, Stevan (1995) The PostGutenberg Galaxy.";
 my $result = $service 
        -> doParaciteSearch($query, $base_url);
 my $first_result = $result->{resultElements}->[0];
 print "First result is: ".$first_result->{URL}."\n";

The web service automatically adds Google, Scirus, and Vivissimo as resources to the search request, so if no resources match the publication or subject these will be used as fall-backs.

Web Service Structures

Most of the Paracite structures have been modelled very closely on the Google web service structures to allow some degree of standardisation. Some additions have been made, and some fields are not yet used, but these may change in future versions.

ParaciteSearchResult

resultElements

This is an array of resources, along with the search URLs associated with them. See the ResultElement description later in this section.

estimatedTotalResultsCount

This returns the number of items in the resultElements array.

estimateIsExact

This currently always returns 1.

searchQuery

This contains the original reference.

openURL

This contains the OpenURL represented by the reference metadata (prefixed by base URL if one is supplied).

metadata

This is a Metadata object (see later in this section).

ResultElement

URL

This is a URL that searches the current resource for the reference.

template

This contains the template of the matching resource interface that was used to generate the search URL.

name

The name of the resource (e.g. Google).

description

Some more information about the resource.

tollfree

A boolean value that is true if the results can be viewed without cost.

fulltext

A boolean value that is true if a resulting article from this resource will have the full text available.

stratum

An integer representing the stratum in which this resource lies. A complete list of the strata is available at http://paracite.eprints.org/cgi-bin/views/viewstrata.cgi

Metadata

All of the fields in Metadata are valid fields in OpenURL metadata. See Table 1 at http://www.sfxit.com/openurl/openurl.html for a complete list.