Biblio::Citation::Parser 1.10 Documentation - ParaCite Web Service

- 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.

Biblio::Citation::Parser 1.10 Documentation - ParaCite Web Service