orcidtr

Overview

orcidtr provides a modern, CRAN-compliant R interface to the ORCiD public API. It replaces the discontinued rorcid package with a streamlined implementation that:

• Fetches all available public data from ORCiD records
• Returns structured data.table objects for easy manipulation
• Requires no authentication for public data (optional token support)
• Fully complies with CRAN policies and best practices

What is ORCiD?

ORCiD (Open Researcher and Contributor ID) is a persistent digital identifier that distinguishes individual researchers and supports automated linkages between researchers and their professional activities. An ORCiD record can contain employment history, education, publications, funding, peer review activities, and more.

Installation

Install from CRAN (when available):

install.packages("orcidtr")

Or install the development version from GitHub:

# install.packages("pak")
pak::pak("lorenzoFabbri/orcidtr")

Quick Start

Basic Usage (No Authentication Required)

# Fetch employment history
employments <- orcidtr::orcid_employments("0000-0002-1825-0097")
print(employments)

# Fetch publications/works
works <- orcidtr::orcid_works("0000-0002-1825-0097")
print(works)

# Fetch education records
education <- orcidtr::orcid_educations("0000-0002-1825-0097")

# Fetch funding information
funding <- orcidtr::orcid_funding("0000-0002-1825-0097")

# Fetch peer review activities
reviews <- orcidtr::orcid_peer_reviews("0000-0002-1825-0097")

# Fetch biographical data
person <- orcidtr::orcid_person("0000-0002-1825-0097")
bio <- orcidtr::orcid_bio("0000-0002-1825-0097")
keywords <- orcidtr::orcid_keywords("0000-0002-1825-0097")

# Fetch professional activities
distinctions <- orcidtr::orcid_distinctions("0000-0002-1825-0097")
memberships <- orcidtr::orcid_memberships("0000-0002-1825-0097")

Search the ORCID Registry

# Search by name
results <- orcidtr::orcid_search(
  family_name = "Fabbri",
  given_names = "Lorenzo"
)

# Search by affiliation
results <- orcidtr::orcid_search(affiliation_org = "Stanford University")

# Search by DOI
results <- orcidtr::orcid_doi("10.1371/journal.pone.0001543")

# Advanced Solr query
results <- orcidtr::orcid("family-name:Smith AND affiliation-org-name:MIT")

Fetch Complete Record

# Get all sections at once
record <- orcidtr::orcid_fetch_record("0000-0002-1825-0097")
names(record)

# Access individual sections
record$works
record$employments

# Fetch only specific sections
record <- orcidtr::orcid_fetch_record(
  "0000-0002-1825-0097",
  sections = c("works", "employments")
)

Batch Processing

# Fetch works for multiple researchers
orcids <- c("0000-0002-1825-0097", "0000-0003-1419-2405", "0000-0002-9079-593X")
all_works <- orcidtr::orcid_fetch_many(orcids, section = "works")

# Filter using data.table syntax
all_works[type == "journal-article" & !is.na(doi)]

Authentication (Optional)

Important: The ORCID public API allows unauthenticated read access to all public data. Authentication is entirely optional and only needed for:

• Higher rate limits: Authenticated requests have more generous rate limits
• Private data access: If you’ve been granted permission to access restricted/private information

Why Authentication is Optional

Unlike the rorcid package documentation might suggest, the ORCID public API (pub.orcid.org) does NOT require authentication for reading public records. The token mentioned in rorcid guides is for increasing rate limits, not for basic access. This package works perfectly fine without any token for typical use cases.

When You Might Want a Token

You should consider getting a token if you:

• Need to make many requests in a short time (>24 requests/second sustained)
• Are building an application with many users
• Need to access restricted data you’ve been granted permission to view

How to Get a Token (If Needed)

1. Register for ORCID API credentials at https://orcid.org/developer-tools
2. Click “Register for the free ORCID public API”
3. Fill in your application details and agree to terms
4. Copy your Client ID and Client Secret
5. Exchange them for an access token:

# Use your credentials to get a token
library(httr2)
resp <- request("https://orcid.org/oauth/token") |>
  req_headers(
    Accept = "application/json",
    `Content-Type` = "application/x-www-form-urlencoded"
  ) |>
  req_body_form(
    grant_type = "client_credentials",
    scope = "/read-public",
    client_id = "YOUR-CLIENT-ID",
    client_secret = "YOUR-CLIENT-SECRET"
  ) |>
  req_perform()

token_data <- resp_body_json(resp)
token <- token_data$access_token

6. Set the environment variable:

# In your .Renviron file (recommended for persistent use)
ORCID_TOKEN <- "your-token-here"

# Or set temporarily in R session
Sys.setenv(ORCID_TOKEN = "your-token-here")

Note: The package will automatically use the ORCID_TOKEN environment variable if it’s set. For the public API, this is purely optional and most users can skip this entire section.

Supported Data Types

Employment and Education

Professional Activities

Works and Activities

Biographical Data

Search Functions

Utilities

Data Structure

All functions return data.table objects with consistent structure:

works <- orcidtr::orcid_works("0000-0002-1825-0097")
str(works)

Rate Limits and Best Practices

• Public API: ~24 requests per second
• Authenticated: Higher limits (check ORCiD documentation)
• Add delays for large batch operations: Sys.sleep(0.1) between requests
• Use orcid_fetch_many() for efficient batch processing
• Cache results when possible
• Handle errors gracefully with tryCatch()

License

MIT © Lorenzo Fabbri

Acknowledgments

• ORCiD for providing the public API
• The rorcid package authors for leading ORCiD integration in R
• The R community for feedback and contributions