pkgdown/analytics.html Skip to contents

Retrieve a GeoLocator Data Package from a Zenodo record identifier:

  1. Resolve and fetch Zenodo record metadata from the REST API.

  2. Download datapackage.json, then the files its resources refer to and params.json when the record has one, to a temporary directory. Other files of the record are not downloaded. Each file is checked against the MD5 checksum Zenodo records for it.

  3. Read datapackage.json with read_gldp(), loading every table into memory, then delete the temporary directory.

  4. Attach Zenodo metadata and recompute derived package properties with update_gldp().

Usage

read_zenodo(
  id,
  token = NULL,
  draft = FALSE,
  sandbox = FALSE,
  quiet = FALSE,
  timeout = 600
)

Arguments

id

Zenodo identifier. Can be a record id, DOI, DOI URL, or Zenodo record URL. Supported examples include "18467383", "10.5281/zenodo.18467383", "https://doi.org/10.5281/zenodo.18467383", and "https://zenodo.org/records/18467383". A Zenodo Sandbox record URL or DOI (prefix 10.5072) is read from Zenodo Sandbox; for a bare Sandbox record id, set sandbox = TRUE.

token

Optional Zenodo access token for authenticated requests. A token given here is always used. If NULL, a draft is read with a token resolved from environment variables or the system keyring, and a published record is read without authentication.

draft

Logical. If TRUE, read the draft version of the record instead of the public record. This queries the draft endpoint (/api/records/{id}/draft), which requires a token and permission to access the deposition. Use this for unpublished records or when draft files or metadata differ from the published record.

sandbox

Logical. If TRUE, query Zenodo Sandbox instead of the main Zenodo service. This also switches draft token lookup to sandbox-first sources.

quiet

Logical. If TRUE, suppress progress messages from read_zenodo().

timeout

Maximum time in seconds allowed to download each file.

Value

A geolocatordp object from the Zenodo record.

Details

  • If the record has no files, because it is metadata-only or its files are restricted or embargoed, the function warns and returns a package with only metadata, created with create_gldp().

  • If the record does not contain datapackage.json or a file it refers to, the function aborts.

  • If one or more file downloads fail or do not match their checksum, the function aborts with download details.

Downloaded files are written under tempdir() in a run-specific folder, which is deleted once the package is read. A resource without a table schema, which is not loaded into memory, keeps a path into that deleted folder.

A published record is read without authentication unless token is given, so its restricted or embargoed files are only read with token =.

To read a draft:

  1. Create or identify the Zenodo deposition and note its record id.

  2. Obtain a Zenodo access token with permission to view that draft.

  3. Provide the token directly with token =, or make it available as ZENODO_TOKEN (main Zenodo) or ZENODO_TOKEN_SANDBOX (Zenodo Sandbox). The same names are also checked in the system keyring.

  4. Call read_zenodo(id, draft = TRUE), and set sandbox = TRUE when the draft is hosted on Zenodo Sandbox.

If draft = TRUE and token = NULL, token lookup is attempted in this order:

  • for main Zenodo: ZENODO_TOKEN, then keyring service ZENODO_TOKEN;

  • for Zenodo Sandbox: ZENODO_TOKEN_SANDBOX, ZENODO_TOKEN, then keyring services ZENODO_TOKEN_SANDBOX and ZENODO_TOKEN.

See also

read_gldp() to read a local or remote datapackage.json, and create_gldp() for the empty package shell used when record files are not accessible.

Examples

if (FALSE) { # \dontrun{
pkg <- read_zenodo("18467383", quiet = TRUE)

# Resolve from DOI URL
pkg <- read_zenodo("https://doi.org/10.5281/zenodo.18467383", quiet = TRUE)

# Access a draft in Zenodo Sandbox using a token from the environment/keyring
pkg <- read_zenodo("470406", sandbox = TRUE, draft = TRUE, quiet = TRUE)

# Or provide the token explicitly
pkg <- read_zenodo(
  "470406",
  sandbox = TRUE,
  draft = TRUE,
  token = "<TOKEN>",
  quiet = TRUE
)
} # }