Help for package natserv

Title:

'NatureServe' Interface

Description:

Interface to 'NatureServe' (https://www.natureserve.org/). Includes methods to get data, image metadata, search taxonomic names, and make maps.

Version:

1.0.0

License:

MIT + file LICENSE

URL:

https://docs.ropensci.org/natserv, https://github.com/ropensci/natserv

BugReports:

https://github.com/ropensci/natserv/issues

LazyData:

true

VignetteBuilder:

knitr

Language:

en-US

Encoding:

UTF-8

Depends:

R(≥ 3.2.1)

Imports:

crul (≥ 0.7.0), jsonlite, tibble

Suggests:

testthat, knitr, vcr

RoxygenNote:

7.1.0

X-schema.org-applicationCategory:

Taxonomy

X-schema.org-keywords:

taxonomy, species, API, web-services, NatureServe, metadata, maps

X-schema.org-isPartOf:

https://ropensci.org

NeedsCompilation:

Packaged:

2020-05-15 21:02:58 UTC; sckott

Author:

Scott Chamberlain

[aut, cre], rOpenSci [fnd] (https://ropensci.org/)

Maintainer:

Scott Chamberlain <myrmecocystus@gmail.com>

Repository:

CRAN

Date/Publication:

2020-05-16 22:30:07 UTC

natserv

Description

Interface to NatureServe https://www.natureserve.org/

Author(s)

Scott Chamberlain myrmecocystus@gmail.com

A data.frame with 49 rows and 2 columns

Description

state (character) state 2 letter abbreviation
state_name (character) state full name

Get taxon by uid, id, or elCode

Description

Get taxon by uid, id, or elCode

Usage

ns_altid(uid = NULL, id = NULL, el_code = NULL, ...)

Arguments

uid

(character) A NatureServe taxon id (The taxon’s Element Global UID)

id

The primary key value (ELEMENT_GLOBAL_ID) of the record within Central Biotics

el_code

The Biotics Element Code (ELCODE_BCD) of the record

...

Curl options passed on to verb-GET

Details

see https://explorer.natureserve.org/api-docs/#_taxon_data_model for details on the response data

Value

A list with lots of elements

References

https://explorer.natureserve.org/api-docs/

Examples

## Not run: 
ns_altid(uid = "ELEMENT_GLOBAL.2.154701")
ns_altid(id = "154701")
ns_altid(el_code = "PDRAN0F010")

## End(Not run)

Get a summary of the upper level hierarchy for an Ecosystem record

Description

Get a summary of the upper level hierarchy for an Ecosystem record

Usage

ns_ecohier(uid, ...)

Arguments

uid

(character) A NatureServe taxon id (The taxon’s Element Global UID)

...

Curl options passed on to verb-GET

Details

see https://explorer.natureserve.org/api-docs/#_taxon_data_model for details on the response data

Value

A list with lots of elements

References

https://explorer.natureserve.org/api-docs/

Examples

## Not run: 
ns_ecohier("ELEMENT_GLOBAL.2.683060")

## End(Not run)

Search exports

Description

Search exports

Usage

ns_export(
  text = NULL,
  text_adv = NULL,
  status = NULL,
  location = NULL,
  record_type = NULL,
  record_subtype = NULL,
  modified_since = NULL,
  format = "json",
  lang = "en",
  ...
)

ns_export_status(id, ...)

Arguments

text

(character) basic text search, equiavalent to text_adv with matchAgainst="allNames" and operator="similarTo"

text_adv

(list) advanced search, must specify the following three elements: searchToken, matchAgainst, and operator. see https://explorer.natureserve.org/api-docs/#_advanced_text_search_parameter

status

(character) conservation status, one of G1, G2, G3, G4, G5, GH, GX, GNR, GNA, GU. case insensitive

location

(list) location, country and sub-country. specify either nation OR nation and subnation. each expects a two-letter ISO code

record_type

(character) limit results by record type, one of "species" or "ecosystem"

record_subtype

(character) limit results by record sub-type, one of: "class", "subclass", "formation", "division", "macrogroup", "group", "alliance", "association", "terrestrial_ecological_system"

modified_since

(character) search for records modified since a given time. value must be a date and time with a UTC offset in ISO 8601 format. optional

format

(character) output format, one of "json" or "xlsx"

lang

(character) language, one of "en", "es", or "fr"

...

Curl options passed on to verb-GET

id

(character) a job id, from output of ns_export()

Value

ns_export() returns a single character string (a job id) ns_export_status() returns a list of metadata concerning the status of the export

References

https://explorer.natureserve.org/api-docs/

Examples

## Not run: 
x <- ns_export(text = "robin")
res <- ns_export_status(x)
str(res)
res$state
res$data$errorMessage
res$data$url

w <- ns_export(text_adv = list(searchToken = "western",
  matchAgainst="allScientificNames", operator="startsWith"))
m <- ns_export_status(w)
head(jsonlite::fromJSON(m$data$url))

## End(Not run)

Get taxon by uid

Description

Get taxon by uid

Usage

ns_id(uid, ...)

Arguments

uid

(character) A NatureServe taxon id (The taxon’s Element Global UID). required.

...

Curl options passed on to verb-GET

Details

see https://explorer.natureserve.org/api-docs/#_taxon_data_model for details on the response data

Value

A list with lots of elements

References

https://explorer.natureserve.org/api-docs/

Examples

## Not run: 
ns_id("ELEMENT_GLOBAL.2.154701")

## End(Not run)

Combined search

Description

Combined search

Usage

ns_search_comb(
  text = NULL,
  text_adv = NULL,
  status = NULL,
  location = NULL,
  record_type = NULL,
  record_subtype = NULL,
  modified_since = NULL,
  page = NULL,
  per_page = NULL,
  ...
)

Arguments

text

(character) basic text search, equiavalent to text_adv with matchAgainst="allNames" and operator="similarTo"

text_adv

(list) advanced search, must specify the following three elements: searchToken, matchAgainst, and operator. see https://explorer.natureserve.org/api-docs/#_advanced_text_search_parameter

status

(character) conservation status, one of G1, G2, G3, G4, G5, GH, GX, GNR, GNA, GU. case insensitive

location

(list) location, country and sub-country. specify either nation OR nation and subnation. each expects a two-letter ISO code

record_type

(character) limit results by record type, one of "species" or "ecosystem"

record_subtype

(character) limit results by record sub-type, one of: "class", "subclass", "formation", "division", "macrogroup", "group", "alliance", "association", "terrestrial_ecological_system"

modified_since

(character) search for records modified since a given time. value must be a date and time with a UTC offset in ISO 8601 format. optional

page

(integer) Zero-indexed page number; default: 0. optional

per_page

(integer) Records per page; default: 20. optional

...

Curl options passed on to verb-GET

References

https://explorer.natureserve.org/api-docs/

Examples

## Not run: 
ns_search_comb(text = "robin")
ns_search_comb(text_adv = list(searchToken = "western",
  matchAgainst="allScientificNames", operator="startsWith"))
ns_search_comb(status = "G1")
ns_search_comb(location = list(nation = "US"))
ns_search_comb(location = list(nation = "US", subnation = "VA"))
ns_search_comb(record_type = "species")
ns_search_comb(record_subtype = "macrogroup")
ns_search_comb(modified_since = "2020-04-30T00:00:00+0000")
ns_search_comb(page = 0, per_page = 2)

## End(Not run)

Ecosystem search

Description

Ecosystem search

Usage

ns_search_eco(
  text = NULL,
  text_adv = NULL,
  status = NULL,
  location = NULL,
  ecosystem_taxonomy = NULL,
  record_subtype = NULL,
  modified_since = NULL,
  page = NULL,
  per_page = NULL,
  ...
)

Arguments

text

(character) basic text search, equiavalent to text_adv with matchAgainst="allNames" and operator="similarTo"

text_adv

(list) advanced search, must specify the following three elements: searchToken, matchAgainst, and operator. see https://explorer.natureserve.org/api-docs/#_advanced_text_search_parameter

status

(character) conservation status, one of G1, G2, G3, G4, G5, GH, GX, GNR, GNA, GU. case insensitive

location

(list) location, country and sub-country. specify either nation OR nation and subnation. each expects a two-letter ISO code

ecosystem_taxonomy

(character) the classification code of the higher level (ancestor) ecosystem. E.g.'s: "1" (Class code), "1.B" (Subclass code), "1.B.2" (Formation code), "1.B.2.Nd" (Division code), "M886" (Macrogroup key), "G206" (Group key), "A3328" (Alliance Key)

record_subtype

(character) limit results by record sub-type, one of: "class", "subclass", "formation", "division", "macrogroup", "group", "alliance", "association", "terrestrial_ecological_system"

modified_since

(character) search for records modified since a given time. value must be a date and time with a UTC offset in ISO 8601 format. optional

page

(integer) Zero-indexed page number; default: 0. optional

per_page

(integer) Records per page; default: 20. optional

...

Curl options passed on to verb-GET

References

https://explorer.natureserve.org/api-docs/

Examples

## Not run: 
ns_search_eco(text = "robin")
ns_search_eco(text_adv = list(searchToken = "bird",
  matchAgainst = "allNames", operator="similarTo"))
ns_search_eco(status = "G1")
ns_search_eco(location = list(nation = "US"))
ns_search_eco(location = list(nation = "US", subnation = "VA"))
ns_search_eco(ecosystem_taxonomy = "M067")
ns_search_eco(record_subtype = "macrogroup")
ns_search_eco(modified_since = "2020-04-30T00:00:00+0000")
ns_search_eco(page = 0, per_page = 2)

## End(Not run)

Species search

Description

Species search

Usage

ns_search_spp(
  text = NULL,
  text_adv = NULL,
  status = NULL,
  location = NULL,
  species_taxonomy = NULL,
  record_subtype = NULL,
  modified_since = NULL,
  page = NULL,
  per_page = NULL,
  ...
)

Arguments

text

(character) basic text search, equiavalent to text_adv with matchAgainst="allNames" and operator="similarTo"

text_adv

(list) advanced search, must specify the following three elements: searchToken, matchAgainst, and operator. see https://explorer.natureserve.org/api-docs/#_advanced_text_search_parameter

status

(character) conservation status, one of G1, G2, G3, G4, G5, GH, GX, GNR, GNA, GU. case insensitive

location

(list) location, country and sub-country. specify either nation OR nation and subnation. each expects a two-letter ISO code

species_taxonomy

(list) species taxonomy. either a list with level and scientificTaxonomy (a scientific name), or with just informalTaxonomy (a vernacular name). possible level values: "kingdom", "phylum", "class", "order", "family", "genus"

record_subtype

(character) limit results by record sub-type, one of: "class", "subclass", "formation", "division", "macrogroup", "group", "alliance", "association", "terrestrial_ecological_system"

modified_since

(character) search for records modified since a given time. value must be a date and time with a UTC offset in ISO 8601 format. optional

page

(integer) Zero-indexed page number; default: 0. optional

per_page

(integer) Records per page; default: 20. optional

...

Curl options passed on to verb-GET

References

https://explorer.natureserve.org/api-docs/

Examples

## Not run: 
ns_search_spp(text = "robin")
ns_search_spp(text_adv = list(searchToken = "bird", 
  matchAgainst = "allNames", operator="similarTo"))
ns_search_spp(status = "G1")
ns_search_spp(location = list(nation = "US"))
ns_search_spp(location = list(nation = "US", subnation = "VA"))
ns_search_spp(species_taxonomy = list(scientificTaxonomy = "Animalia", level = "kingdom"))
ns_search_spp(species_taxonomy = list(informalTaxonomy = "birds"))
ns_search_spp(record_subtype = "macrogroup")
ns_search_spp(modified_since = "2020-04-30T00:00:00+0000")
ns_search_spp(page = 0, per_page = 2)

## End(Not run)

natserv

Description

Author(s)

A data.frame with 49 rows and 2 columns

Description

Get taxon by uid, id, or elCode

Description

Usage

Arguments

Details

Value

References

Examples

Get a summary of the upper level hierarchy for an Ecosystem record

Description

Usage

Arguments

Details

Value

References

Examples

Search exports

Description

Usage

Arguments

Value

References

Examples

Get taxon by uid

Description

Usage

Arguments

Details

Value

References

Examples

Combined search

Description

Usage

Arguments

References

See Also

Examples

Ecosystem search

Description

Usage

Arguments

References

See Also

Examples

Species search

Description

Usage

Arguments

References

See Also

Examples