Skip to contents

Search by term

Source: R/searchbyterm.R
searchbyterm.Rd

Flexible search for records using keywords/terms

Usage

searchbyterm(
  ...,
  limit = 1000,
  compact = TRUE,
  messages = TRUE,
  only_dwc = TRUE,
  callopts = list()
)

Arguments

...

arguments, must be named, see section Parameters for details. Multiple inputs to a single parameter are supported, but you have to construct that string yourself with AND or OR operators; see examples below.

limit

(numeric) Limit on the number of records returned. If >1000 results, we use a cursor internally, but you should still get up to the results you asked for. See also bigsearch() to get larger result sets in a text file via email.

compact

(logical) Return a compact data frame

messages

(logical) Print progress and information messages. Default: TRUE

only_dwc

(logical) whether or not to return only Darwin Core term fields. Default: TRUE

callopts

(named list) Curl arguments passed on to crul::verb-GET

Value

A list with two slots:

  • meta: a named list of metadata for the search results

  • data: a data frame of search results, columns vary

Details

searchbyterm() builds a query from input parameters based on Darwin Core (dwc) terms (for the full list of terms, see https://code.google.com/p/darwincore/wiki/DarwinCoreTerms).

Parameters

All these parameters can be passed in to searchbyterm(). All others will be silently dropped.

See https://github.com/VertNet/webapp/wiki/The-API-search-function for more details

taxon

  • kingdom (character) Taxonomic kingdom

  • phylum (character) Taxonomic phylum

  • class (character) Taxonomic class

  • order (character) Taxonomic order

  • family (character) Taxonomic family

  • genus (character) Taxonomic genus

  • specificepithet (character) Taxonomic specific epithet, e.g. (sapiens in Homo sapiens)

  • infraspecificepithet (character) Taxonomic infraspecific epithet

  • scientificname (character) scientific name

  • vernacularname (character) a verncular name

event

  • year (numeric) Year or range of years designated by comparison operators "<", ">", "<=" or ">=". You can pass in more than one of these queries, in a vector. See example below

  • month (numeric) month or range of months designated by comparison operators "<", ">", "<=" or ">=". You can pass in more than one of these queries, in a vector. See example below

  • day (numeric) day or range of days designated by comparison operators "<", ">", "<=" or ">=". You can pass in more than one of these queries, in a vector. See example below

  • eventdate Event date associated with this occurrence record; yyyy-mm-dd or the range yyyy-mm-dd/yyyy-mm-dd (character)

record level

  • institutioncode (character) Code name for the provider/institution of record

  • occurrenceid (character) Provider's unique identifier for this occurrence record

  • catalognumber (character) Provider's catalog number or other ID for this record

  • collectioncode (character) collection code

  • license (dcterms:license) license string

  • iptlicense (eml:intellectualRights) license string

  • basisofrecord (character) one of PreservedSpecimen, FossilSpecimen, MaterialSample, Occurrence, MachineObservation, HumanObservation

  • hasmedia (logical) Record also references associated media, such as a film or video

  • isfossil (logical) dwc:basisOfRecord is FossilSpecimen or collection is a paleo collection

  • haslicense (logical) dcterms:license or eml:intellectualRights has a license designated

identification

  • typestatus (character) a type status

  • hastypestatus (logical) type status known or not

occurrence

  • iptrecordid (character) (same as dwc:occurrenceID)

  • recordedby (character) Collector name

  • recordnumber (character) record number

  • fieldnumber (character) field number

  • establishmentmeans (character) establishment means

  • wascaptive (logical) (dwc:establishmentMeans or occurrenceRemarks suggests it was captive)

  • wasinvasive (logical) (was the organism recorded to be invasive where and when it occurred)

  • sex (character) standardized sex from original sex field or extracted from elsewhere in the record

  • lifestage (character) lifeStage from original sex field or extracted from elsewhere in the record

  • preparations (not sure what this means)

  • hastissue (logical) Record is likely to reference tissues

  • reproductivecondition (not sure what this means)

location

  • continent (character) Continent to search for occurrence

  • country (character) Country to search for occurrence

  • stateprovince (character) State or province to search for occurrence

  • county (character) County to search for occurrence

  • island (character) Island to search for occurrence

  • igroup (character) Island group to search for occurrence

  • municipality (character)

  • waterbody (character)

  • geodeticdatum (character)

  • georeferencedby (character)

  • georeferenceverificationstatus (character)

  • location a Google GeoField of the dwc:decimalLatitude, dwc:decimalLongitude

  • mappable (logical) Record includes valid coordinates in decimal latitude and decimal longitude

geological context

  • bed (character) geological bed

  • formation (character) geological formation

  • group (character) geological group

  • member (character) geological member

traits

  • haslength (logical) (was a value for length extracted?)

  • hasmass (logical) (was a value for mass extraccted?)

  • hassex (logical) (does the record have sex?)

  • haslifestage (logical) (does the record have life stage?)

  • lengthtype (character) type of length measurement extracted from the record, can refer to a number or to a range) ('total length', 'standard length', 'snout-vent length','head-body length', 'fork length', 'total length range', 'standard length range', 'snout-vent length range', 'head-body length range', 'fork length range'

  • lengthinmm (numeric) length measurement extracted from the record

  • massing (numeric) mass measurement extracted from the record (For detailed information about trait extraction and aggregation and querying via the VertNet portal, see http://vertnet.org/resources/traitsguide.html

data set

  • gbifdatasetid (character) GBIF identifier for the data set

  • gbifpublisherid (character) GBIF identifier for the data publishing organization

  • lastindexed (character) date (YYYY-MM-DD) the record was most recently indexed into VertNet

  • networks (character) one of MaNIS, ORNIS, HerpNET, FishNet, VertNet, Arctos, Paleo

  • migrator (character) the version of the migrator used to process the data set, a date of form (YYYY-MM-DD)

  • orgcountry (character) the country where the organization is located

  • orgstateprovince (character) the first-level administrative unit where the organization is located

index

  • rank (character) a higher number means the record is more complete with respect to georeferences, scientific names, and event dates

  • vntype (character) Type of record; "specimen" or "observation"

  • hashid (integer) a value to distribute records in 10k bins; 0-9998

other

  • coordinateuncertaintyinmeters (character) Coordinate uncertainty in meters (numeric) or range of uncertainty values designated by comparison operators "<", ">", "<=", or ">="

No results?

It's possible to get no results with a call to searchbyterm(), then run it again 10 seconds later, and you do get a result. I'm not sure why this is, something having to do with Vertnet's infrastucture that I'm not aware of. Point is, if you are sure you haven't made any mistakes with the parameters, etc., then simply run the function call again.

References

https://github.com/VertNet/webapp/wiki/The-API-search-function

Examples

if (FALSE) {
# Find multiple species
out <- searchbyterm(genus = "ochotona",
  specificepithet = "(princeps OR collaris)", limit=10)

# iptrecordid
searchbyterm(iptrecordid = "7108667e-1483-4d04-b204-6a44a73a5219")

# you can pass more than one, as above, in a single string in parens
records <- "(7108667e-1483-4d04-b204-6a44a73a5219 OR 1efe900e-bde2-45e7-9747-2b2c3e5f36c3)"
searchbyterm(iptrecordid = records, callopts = list(verbose = TRUE))

# Specifying a range (in meters) for uncertainty in spatial location
# (use quotes)
out <- searchbyterm(class = "aves", stateprovince = "nevada", 
  coordinateuncertaintyinmeters = "<25")
out <- searchbyterm(class = "aves", stateprovince = "california", year = 1976,
  coordinateuncertaintyinmeters = "<=1000")

# Specifying records by event date (use quotes)
out <- searchbyterm(class = "aves", stateprovince = "california",
  eventdate = "2009-03-25")
# ...but specifying a date range may not work
out <- searchbyterm(specificepithet = "nigripes",
  eventdate = "1935-09-01/1935-09-30")

# Pass in curl options for curl debugging
out <- searchbyterm(class = "aves", limit = 10,
 callopts = list(verbose = TRUE))

# Use more than one year query
searchbyterm(genus = "mustela", specificepithet = "nigripes",
   year = c('>=1900', '<=1940'))

searchbyterm(sex  = "male", limit = 30)$data$sex
searchbyterm(lifestage  = "juvenile", limit = 30)$data$lifestage
}