RLL: Web Service

RLL web service

RLL now supports a web service for developers who wish to integrate RLL data directly into their applications in real time.

This powerpoint presentation given at IAL6 in July 2008 will give some instructions on how to use the service, e.g. an example (source code) of a php script handling the incoming xml file produced by the script.

Syntax

http://nhm2.uio.no/botanisk/cgi-bin/rll.pl?fo=w&<parameter_list>

where <parameter_list> is a set of key-value pair options controlling how the service handles the request.

Notice that "fo=w" is a key-value pair option like the other options in the parameter list (and may be put anywhere in the list) except for being the only required option. If fo is not supplied, the rll.pl script will return an html page (the standard search result).

Example: http://nhm2.uio.no/botanisk/cgi-bin/rll.pl?au=Acharius&fr=1790&to=1815&t1=Methodus&fo=w&Mat=x returns records in Mattick's Literature Index by author "Acharius" published in the period 1790–1815 containing the word (substring) "Methodus" in the title, keyword or abstract fields.

Available options

sq - return records starting at index sq+1. If this option is not supplied the service starts at 1. The option can be used in conjunction with a previous request which returned the maximum number of records (100).

max - maximum number of records returned. If not supplied (or set to more than 100), set to 100.

au - return records where the value matches in the author field. See ws, dia, and t1 for matching modification.

fr - return records from the supplied year or later. If not supplied, assumes 1536.

to - return records from the supplied year or earlier. If not supplied, assumes the current year.

lyear - returns records from the last lyear years. If supplied, this option overrides any values in fr and to (fr = current year - lyear + 1; to = current year).

jo - return records where the value matches in the journal field (article and review type records), series field (book type record), or book title field (chapter type records). See ws, dia, and t1 for matching modification.

t1 - return records where the value matches in the title, keyword, or abstract fields. See ws and dia for matching modification. If any of the options t2–t5 are supplied, the matching assumes an AND relationship between the t-fields (i.e. the values of all non-empty t-fields must match).
The au, jo and the five t-fields may by split into subfields using the "|" as separator. Matching will be based on an OR relationship between the subfields. Example: http://nhm2.uio.no/botanisk/cgi-bin/rll.pl?au=Acharius|Zahlbruckner&t1=Methodus|Universalis&t2=lichen&fo=w returns all papers by Acharius or Zahlbruckner containing the words "Methodus" or "Universalis" and "lichen" in the title, keyword, or abstract fields.

t2 - See t1. (Additional field for making AND queries.)

t3 - See t1. (Additional field for making AND queries.)

t4 - See t1. (Additional field for making AND queries.)

t5 - See t1. (Additional field for making AND queries.)

casc - return records where the value matches the title, keyword, or abstract fields. The service assumes the value is a family name and expands the search to also match all genera of the family.

gen - return records where the value matches the title, keyword, or abstract fields. The service assumes the value is the genus part of a species name and expands the search to also match the genus part of all known synonyms of this species.

epi - return records where the value matches the title, keyword, or abstract fields. The service assumes the value is the epithet part of a species name and expands the search to also match the epithet part of all known synonyms of this species.

tp - return records of one of the four types of records:
     a: journal article
     b: book
     c: chapter of book
     r: review
   If not supplied, return records of all types.

down - if value = "y" or "Y", return only records which are linked to a downloadable pdf file or a web site.

r0 - return only records from RLL list number value, or, if r1 is also supplied, from RLL list value or later.

r1 - return only records from RLL list number value or earlier.

rn - return record number rn. Notice that three separate record numbers are used in this service, each for the three data sets RLL, Mattick and RLL Supplement. You may also supply the option RLL, Mat and/or Supl for specifying a particular record.

ws - specify whether matching in options au, jo, t1, t2, t3, t4, t5 treats the supplied value as being:
     w: a complete word
     s: a substring matching anywhere in the field
   If not supplied, the matching assumes ws=s.

dia - if value = "1", matching in options au, jo, t1, t2, t3, t4, t5 ignores diacritical signs.

st - sort records according to:
     a: author, year, title
     y: year, author, title
   If not supplied, the matching assumes st=y.

sdir - if value = "r", reverse sort direction.

RLL - if any non-empty value is supplied (or all three option RLL, Mat, and Supl are empty or not supplied), return records from data set Recent Literature on lichens.

Mat - if any non-empty value is supplied (or all three option RLL, Mat, and Supl are empty or not supplied), return records from data set Mattick's Literatur Index.

Supl - if any non-empty value is supplied (or all three option RLL, Mat, and Supl are empty or not supplied), return records from data set RLL & Mattick Supplement.

Notes

The parameter list is case insensitive, both the key and value parts.

The maximum numbers of records returned is 100. Use the sq option for retrieving the next set of records, if needed.

Return format

<?xml version="1.0" encoding="utf-8" ?> 
<NewDataSet>
  <record>
    <id></id> 
    <database></database> 
    <RLLlist></RLLlist> 
    <publicationType></publicationType> 
    <author></author> 
    <year></year> 
    <title></title> 
    <journal></journal> 
    <volume></volume> 
    <pages></pages> 
    <publisher></publisher> 
    <editor></editor> 
    <keywords></keywords> 
    <abstract></abstract> 
    <paperUrl></paperUrl> 
    <journalUrl></journalUrl> 
  </record>
  <record>
  .
  .
  </record>
</NewDataSet>

where

<id> is the record number in the database, preceeded by "M" for the Matticks Literature Index and by "S" for the Supplement. Note that this preceeding character must be omitted in the rn option of the web service request.

<database> is either "Recent Literature on Lichens", "Mattick's Literature Index", or "Recent Literature on Lichens Supplement".

<RLLlist> is the RLL list number (no value for Mattick's index and the supplement).

<publicationType> is either "article", "book", "chapter", or "review".

The content of five fields are to be interpreted differently for the four publication types. These are:

<publicationType> <title> <journal> <volume> <publisher> <editor>

article title journal volume [empty] [empty]
book title series volume publisher [empty]
chapter title of chapter title of book series + volume publisher editor
review title of reviewed paper journal volume publisher of reviewed paper author or reviewed paper

<publicationType>	<title>	<journal>	<volume>	<publisher>	<editor>
article	title	journal	volume	[empty]	[empty]
book	title	series	volume	publisher	[empty]
chapter	title of chapter	title of book	series + volume	publisher	editor
review	title of reviewed paper	journal	volume	publisher of reviewed paper	author or reviewed paper

<paperUrl> is a link to a downloadable pdf file or to a web site supplying a link. Based on information linked to each record, uploaded by the users.

<journalUrl> is a link to the journal's web site. Only for journals giving free access to pdf files of their articles. Automatically generated based on journal name and volume number.

Notes

Any Digital Object Identifyer (DOI) is embedded in the <abstract> field as the text string: "[DOI: value]".

Einar Timdal, 2008-06-02