worldcat_api_search {libbib}

Use the WorldCat Search API

Description

Searches WorldCat using a CQL query. Returns a data.table containing the bibliographic metadata of the results, along with the total number of results.

Usage

worldcat_api_search(
  sru,
  max_records = 10,
  sru_query_assist = getOption("libbib.sru_query_assist", TRUE),
  frbrGrouping = "on",
  start_at = 1,
  wskey = getOption("libbib.wskey", NULL),
  more = TRUE,
  print.progress = TRUE,
  debug = FALSE
)

Arguments

sru

The search query (in CQL syntax). See examples section for some examples.

max_records

The maximum number of search results to return. Must be a number between 0 and 100 or Inf. If Inf, the function will automatically make all follow-up requests to retrieve all search results. For safety, the default is 10.

sru_query_assist

A logical indicating whether translation from more human-readable aliases to the SRU search index codes should be allowed. See details for more information. (default is TRUE). You can control this parameter globally by setting options("libbib.sru_query_assist").

frbrGrouping

With this parameter set to "on" (default), an attempt is made by the WorldCat API to group together similar editions and present only the top held record as the representative record for that group.

start_at

The search result to start at (default is 1)

wskey

A WorldCat API key (default is getOption("libbib.wskey"))

more

A logical indicating whether more information from the MARCXML search results should be returned (publisher, bib level, etc....). (Default is TRUE)

print.progress

A logical indicating whether a message should be displayed for each API request. If max_records is Inf a message will be displayed for every group of 100 search results the function fetches. (default is TRUE)

debug

A logical indicating whether the HTTP and API responses should be printed (for debugging) (default is FALSE)

Details

There is an entire vignette dedicated to this function; to view it, execute vignette("using-the-worldcat-search-api")

By default, this function allows for the usage of more human-readable aliases to the arcane SRU search index codes. This allows you, for example, to search using "$title" instead of "srw.ti". This behavior is controlled using the 'sru_query_assist' parameter. If it is TRUE (the default) you can still use the formal search index codes. See vignette("using-the-worldcat-search-api") for more information.

As with all API access functions in this package, it's up to the user to limit their API usage so as to not get blocked. These functions are deliberately not vectorized for this reason; they only accept one standard number at a time.

This (and other) WorldCat API communication functions require a WorldCat API key. The easiest way to use these functions is to set a global options with your key: options("libbib.wskey"="YOUR KEY HERE")

Value

A data.table containing the bibliographic metadata of the results, along with the total number of results.

Examples

## Not run: 

# A title search for "The Brothers Karamazov"
worldcat_api_search('$title = "Brothers Karamazov"')

# An exact title search for "The Brothers Karamazov"
worldcat_api_search('$title exact "Brothers Karamazov"')

# Search for title "Madame Bovary" by author "Gustave Flaubert"
# in language Greek (all results)
# (queries may span multiple lines)
sru <- '$author = "Gustave Flaubert" and $title="Madame Bovary"
          and $language=greek'
worldcat_api_search(sru, max_records=Inf)

# Hip Hop (subject) materials on Cassette, CD, or wax from years 1987 to 1990
sru <- '(($material_type=cas or $material_type=cda or $material_type=lps)
           and $subject="Rap") and $year="1987-1990"'
worldcat_api_search(sru)

# all materials with keyword "Common Lisp" at The New York Public Library
sru <- '$keyword="common lisp" and $holding_library=NYP'
worldcat_api_search(sru, max_records=Inf)

# 19th century materials on ethics (Dewey code 170s / LC Call prefix BJ)
sru <- '($dewey="17*" or $lc_call="bj*") and $year="18*"'
worldcat_api_search(sru, max_records=Inf)

# Music (Dewey 780s) materials that are only held by The New York Public
# Library (a "cg" code of 11 means there is only one holding)
# [searching with debugging]
sru <- '$dewey="78*" and $holding_library=NYP
          and $library_holdings_group=11'
worldcat_api_search(sru, debug=TRUE)

Keyword search for "danger music" from year 2010 to present
worldcat_api_search('$keyword="danger music" and $year="2010-"')


## End(Not run)