rdpla (version 0.2.0)

dpla_items: Search items from the Digital Public Library of America (DPLA).

Description

Search items from the Digital Public Library of America (DPLA).

Usage

dpla_items(q = NULL, description = NULL, title = NULL, subject = NULL,
  creator = NULL, type = NULL, publisher = NULL, format = NULL,
  rights = NULL, contributor = NULL, provider = NULL, sp = NULL,
  sp_coordinates = NULL, sp_city = NULL, sp_county = NULL,
  sp_distance = NULL, sp_country = NULL, sp_code = NULL, sp_name = NULL,
  sp_region = NULL, sp_state = NULL, fields = NULL, sort_by = NULL,
  date = NULL, date_before = NULL, date_after = NULL, language = NULL,
  page_size = 100, page = NULL, facets = NULL, facet_size = 100,
  key = NULL, what = "table", ...)

Arguments

q

(character) Query terms.

description

(character) Object description.

title

(character) Object title.

subject

(character) Subject area

creator

(character) Creator name

type

(character) Type of object

publisher

(character) Publisher

format

(character) Format

rights

(character) Rights

contributor

(character) Contributor

provider

(character) Provider

sp

(character) Query all spatial fields.

sp_coordinates

(character) Query only coordinates. Of the form <latitude,longitude>

sp_city

(character) Query by city name.

sp_county

(character) Query by county name.

sp_distance

(character) Distance from point defined in the sp_coordinates field

sp_country

(character) Query by location country

sp_code

(character) Query by ISO 3166-2 country code. Codes are included in this package, see country_codes. Find out more at https://www.iso.org/obp/ui/#search

sp_name

(character) Location name.

sp_region

(character) Name of a region, e.g., "Upstate New York" (literal)

sp_state

(character) ISO 3166-2 code for a U.S. state or territory

fields

(character) A vector of the fields to return in the output. The default is all fields. See dpla_fields for options.

sort_by

(character) The default sort order is ascending. Most, but not all fields can be sorted on. Attempts to sort on an un-sortable field will return the standard error structure with a HTTP 400 status code.

date

(character) A date

date_before

(character) Date before

date_after

(character) Date after

language

(character) One of a name of a language, or an ISO-639 code. Codes are included in this package, see language_codes. Find out more at http://www-01.sil.org/iso639-3/default.asp

page_size

(integer) Number of items to return, defaults to 100. Max of 500.

page

(integer) Page number to return, defaults to NULL.

facets

(character) Fields to facet on.

facet_size

(integer) Default to 100, maximum 2000.

key

(character) Your DPLA API key. See dpla_get_key()

what

(character) One of list or table (data.frame). (Default: table)

...

Curl options passed on to crul::HttpClient()

Value

A list of length three:

• meta - metadata for the call, with one row and three columns:

  • found - number of records found matching criteria

  • start - offset from record 1

  • returned - number of records returned

• data - tibble (data.frame) of results

• facets - list of same length as number of facets requested, each with a list of length two with a meta tibble/data.frame, and a data tibble/data.frame

Details

Note that parsing of results right now can lead to multiple rows per record because sometimes an array of length > 1 for a result makes a data.frame of more than one row per record. Thus, you will get duplicated values in the id column of the results.

Examples

# NOT RUN {
# Basic search, "fruit" in any fields
dpla_items(q="fruit")

# Limit records returned
dpla_items(q="fruit", page_size=2)

# Return certain fields
dpla_items(q="fruit", fields=c("id","publisher","format"))
dpla_items(q="fruit", fields="subject")

# Max is 500 per call, but you can use combo of page_size and page params
dpla_items(q="fruit", fields="id", page_size=500)$meta$returned
lapply(1:2, function(x) {
   dpla_items(q="fruit", fields="id", page_size=500, page=x)$meta$returned
})
out <- lapply(1:2, function(x) dpla_items(q="fruit", fields="id",
   page_size=500, page=x))
lapply(out, function(y) head(y$data))

# Search by date
out <- dpla_items(q="science", date_before=1900, page_size=200)
out$data

# Search by various fields
dpla_items(description="obituaries", page_size=2, fields="description")
dpla_items(title="obituaries", page_size=2, fields="title")
dpla_items(subject="yodeling", page_size=2, fields="subject")
dpla_items(creator="Holst-Van der Schalk", page_size=2, fields="creator")
dpla_items(type="text", page_size=2, fields="type")
dpla_items(publisher="Leningrad", page_size=2, fields="publisher")
dpla_items(rights="unrestricted", page_size=2, fields="rights")
dpla_items(provider="HathiTrust", page_size=2, fields="provider")

## don't seem to work
# dpla_items(contributor="Smithsonian", page_size=2, fields="contributor")
# dpla_items(format="Electronic resource", page_size=2, fields="format")

# Spatial search
## sp searches all spatial fields, or search on specific fields, see those
## params with sp_*
dpla_items(sp='Boston', page_size=2)
dpla_items(sp_state='Hawaii', page_size=2)
dpla_items(sp_state='Massachusetts OR Hawaii', page_size=2)
dpla_items(sp_coordinates='40,-100', page_size=2)
dpla_items(sp_country='Canada', page_size=2)
dpla_items(sp_county='Sacramento', page_size=2)

# Language search
dpla_items(language='Russian')$meta
dpla_items(language='rus')$meta
dpla_items(language='English')$meta

# Sorting
dpla_items(fields=c("id","title"), page_size=10)
dpla_items(fields=c("id","title"), page_size=10,
  sort_by="sourceResource.title")

# Faceting
dpla_items(facets="sourceResource.format", page_size=0)
dpla_items(facets="sourceResource.format", page_size=0, facet_size=5)
ids <- c("sourceResource.spatial.state","sourceResource.spatial.country")
dpla_items(facets=ids, page_size=0)
dpla_items(facets="sourceResource.type", page_size=0)
#dpla_items(facets="sourceResource.spatial.coordinates:42.3:-71",
#   page_size=0)
#dpla_items(facets="sourceResource.temporal.begin", page_size=0)
dpla_items(facets="provider.name", page_size=0)
dpla_items(facets="isPartOf", page_size=0)
dpla_items(facets="hasView", page_size=0)
# }