Find Item

Find more information about the FindItem service which allows libraries to pass a known item search to Relais ILL and get back an indication of the requestability of the item within the partnership or consortium.

 Note: FindItem uses the aid obtained using the Authentication service.  Patron credentials can not be sent as part of FindItem.

FindItem

FindItem service URL:

${aid} is the authorization ID for the user logged in.  The {aid} value is provided by the Authentication service.

For example:

HTTP Method: POST 
HTTP Header Content-Type: application/json

FindItem request body JSON elements

Element Description

PartnershipId

Required. Partnership ID indicating to which consortium/group the library belongs.

ExactSearch

 Notes: 

  • One of ExactSearch or BibSearch must be provided.
  • Only one of ExactSearch or BibSearch may be provided.
  • If both are provided, use ExactSearch and ignore BibSearch parameters.

          Type

The type of exact search to be used.  Supported options are: 

  • ISBN (repeatable)
  • ISSN (repeatable)
  • LCCN
  • OCLC
     

     Notes: 

    • Values are case-sensitive.

    • If an invalid Type is supplied, then an error is returned: Invalid Type: {type} provided.

If there are hyphens in the ISBN they are dropped.  

  • Example: ISBN 1-4380-7071-3 becomes 1438070713

If there are alpha characters at the end of the ISBN they are dropped, unless the alpha character is an X.

  • Examples:
    • ISBN 0060621273PBK. becomes 0060621273
    • ISBN 0-8131-2414-X becomes 081312414X

If there is punctuation within the ISBN that is listed in the ID_SPECIAL_CHAR table, the punctuation and any characters after it are dropped.

  • Example: ISBN 9781572247055;157 becomes 9781572247055

If multiple ISBNs are provided, they are combined using OR logic.
BibSearch

 Notes: 

  • One of ExactSearch or BibSearch must be provided.
  • Only one of ExactSearch or BibSearch may be provided.
  • If both are provided, use ExactSearch and ignore BibSearch parameters.

Title

Mandatory when BibSearch is provided.

The title is searched as a phrase.

No cleanup, such as the removal of special characters, is done prior to the search.

Author
  • Repeatable.

Commas and periods will be replaced with a space.  Any initials are dropped.

  • Example: For DICKSON, BRUCE J. the  keywords = DICKSON and BRUCE are used.

the following keywords are dropped: author, editor, edited by, and DR.

  • Example: For  Begun, David R, the keywords Begun and David are used.

Dates are dropped.

  • Example: For Enterline, Lynn, 1956-, the keywords Enterline and Lynn are used.
ResultFilter

Date and format filters can be used to narrow the results.

Only one of Include and Exclude filters may be provided.

Include

Include the records that match the filter(s) provided.

PublicationDate

Include the records that match the year(s) provided.

  • Repeatable.

For publication dates, the four digit year is extracted based on the valid dates configured.

  • Example: For c2013, the date 2013 is used. For 2015-01-01 the date 2015 is used.

Format

Include the records that match the format(s) provided.

  • Repeatable.

The value for format must be from the configurable list of formats supported.

Exclude

Exclude the records that match the filter(s) provided.

PublicationDate

Exclude the records that match the year(s) provided.

  • Repeatable

For publication dates, the four digit year is extracted based on the valid dates configured.

  • Example: For c2013, the date 2013 is used. For 2015-01-01 the date 2015 is used.

Format

Exclude the records that match the format(s) provided.

  • Repeatable

The value for format must be from the configurable list of formats supported.


FindItem request - template (for download)

FindItem response - json elements

Element Description

Available

Depending on the results of the Requestability evaluation, a true or false value is returned.

  • true: The item is requestable from another member of the partnership/consortium.
  • false: The item is not requestable from another member of the partnership/consortium.  The item may be available at the patron's library.
RequestLink  

ButtonLink

The ButtonLink used depends on the results of the Requestability evaluation.  The following options are possible:

  • Deep link to the local catalog. For example: http://dla.library.upenn.edu/dla/franklin/record.html?id=${md-id}
  • The link to display to submit a request to another consortium member via a web form. For example: https://rc.relais-host.com/dws/incrementRequest?pid=${pid}&SS=${oclcSymbol1}&targetURL=https://ill.lib.umich.edu/illiad/illiad.dll/OpenURL%3fsid=UBILL
  • AddRequest when the library is configured to not use a web form when submitting a request to another consortium member.
  • The link to display to submit an ILL request. For example: https://mit.illiad.oclc.org/illiad/illiad.dll/OpenURL%3fsid=BDILL
  • Blank if no ILL requesting is allowed.

These links are taken from the library's configuration.
   ButtonLabel

The text to display for the link. 

  • For example:  Request.

This text is taken from the library’s configuration.
     RequestMessage

A configurable message that accompanies the button described above.

  • Example:  This item is not available from another consortium member.  It may be available via ILL. 

The text of this message is taken from the library’s configuration.
OrigNumberOfRecords The original number of bibliographic records returned by the search, i.e., before any records are merged.
PickupLocation PickupLocation is only included when Available = true.
PickupLocationCode A list of pickup location codes (as used in Relais).
PickupLocationDescription A list of pickup locations to display when AddRequest is used in the ButtonLink.


FindItem response "successful" - template (for download)

Example 1 - single ISBN 

Example 4 - title with date and format filters

Errors

FindItem may return the following error codes and messages:

Code

Type

Message
PUBSC001 Public

Invalid request

The following message could be appended:

 

Missing required URL parameter: aid

 
PUBSC005 Public Invalid JSON request
PUBAZ001, PUBFI001 Public

Missing parameter

The following message could be appended:

 

PartnershipId is required

ExactSearch or BibSearch is required

Invalid Type: {Type} provided.

No Value for ExactSearch Type: {Type} provided.

No title provided.

PublicationDate provided in Include and Exclude filters.

Format provided in Include and Exclude filters.

 
PUBFI004 Public Not a valid format: {Format}
PUBFI005 Public Could not parse valid date: {PublicationDate}
PUBFI003 Public Invalid aid
PUBSC006 Public User group not authorized to access the service
PUBFI002 Public No result
PRIAZ001, PRIFI001, PRISC001 Private Internal error has occurred in FindItem
PRIFI002 Private Requestability error

 Note:  PRIFI002: is used for a Requestability error, if Requestability returns an error (Problem), this error message may be appended. 

The following is a sample response for an unsuccessful FindItem request:

   {
     "Problem": {
       "ErrorCode": "PUBFI001",
       "ErrorMessage": "PartnershipId is required"
     }
   }