Most parameter descriptions below have been adapted from the official USDA PLANTS Web Services Interface Definition. If the search is broad, and if the number of symbols to be returned are greater than 10,then only basic information of those symbols are returned. If more detailed records are required, please narrow the search criteria.

ptr_search(
  symbol = NULL,
  scientific_name = NULL,
  common_name = NULL,
  state_province = NULL,
  county = NULL,
  introduced = NULL,
  native = NULL,
  federal_noxious = NULL,
  state_noxious = NULL,
  federal_te = NULL,
  state_te = NULL,
  basic = TRUE,
  flatten = TRUE
)

Arguments

symbol

Returns plants that match the USDA symbol given. Example values: ABBA, CAR.

scientific_name

Returns plants that match the specified scientific name (without author). Parameter is case sensitive. Example value: Abies balsamea.

common_name

Represents the National Common Name (Also known as the accepted or preferred common name). Returns plants that match the specified common name. Parameter is case sensitive. Example values: balsam fir.

state_province

Returns plants that are present in the specified state or province. When state is specified it should be referenced as state name. Example values: Alabama, Colorado, Alberta.

county

Returns plants that are present in the specified county. Example values (for the state of Colorado): Adams, Larimer, Yuma.

introduced, native

Only one of these parameters may be specified. A list of acceptable values is included below.

federal_noxious

Returns only plants that have the specified federal noxious status. Current statuses are "Noxious Weed" (nw), "Quarantine" (q).

state_noxious

Returns only plants that are designated as noxious weeds (or equivalent) in a specified state. As the categories of noxious weeds vary greatly by state, specific noxious codes are not used as a filter. When state is specified it can be referenced as state code. Example values: UT, AZ

federal_te

Returns only plants that have the specified federal threatened, endangered status. The possible statuses are endangered or threatened.

state_te

Returns only plants that are designated on any threatened or endangered list in the specified state. As the categories of threatened and endangered weeds vary greatly by state, specific codes are not used as a filter. When state is specified it can be referenced as state code. Example values: CO, CA

basic

Logical: should the search use the basic API (returning data on plant symbols, accepted common names, and scientific names) or the full API which returns much more data? Note that queries using the full API without many parameters (such as searching using a common name or symbol without specifying restrictions using the other arguments) may take a long time, time out or error in unexpected ways, or (if more than 10 species will be returned) fall back to using the basic API with a warning. When using the full API, it is often a good idea to run multiple queries for smaller regions rather than attempting to run a single query for a larger region.

flatten

Logical: attempt to flatten nested data frames into a data frame with fewer nested layers? Passed to jsonlite::fromJSON.

Value

A data frame containing the data returned by the API call requested.

Nativity status

Only one of introduced and native may be specified in a single API call, as filtering for only introduced species in a region necessarily excludes native species in that region.

Valid values for these fields are:

  • l48: Lower 48 states

  • Ak: Alaska

  • Hi: Hawaii

  • pr: Puerto Rico

  • vi: U.S. Virgin Islands

  • can: Canada

  • gl: Greenland (Denmark)

  • spm: St. Pierre and Miquelon (France)

  • na: North America

Specifying introduced = l48, for example, will return a list of introduced species within the lower 48 states, while native = Hi will return a list of plants native to Hawaii.

Examples

if (FALSE) { # Get basic results matching the common name "balsam fir": ptr_search(common_name = "balsam fir") # Get full results for the same query: ptr_search(common_name = "balsam fir", basic = FALSE) }