ORCID API Integration Guide

This guide explains how to integrate with the ORCID data API to retrieve researcher activities from the University of Waterloo's ORCID service.

Table of Contents

Available Endpoints

All endpoints require either a username or orcid query parameter to identify the researcher.

Endpoint Description
/api/works Research works (publications, datasets, etc.)
/api/educations Education history
/api/employments Employment history
/api/fundings Funding and grants
/api/peer-reviews Peer review activities

Query Parameters

  • username - The researcher's username (e.g., ?username=jsmith)
  • orcid - The researcher's ORCID iD (e.g., ?orcid=0000-0002-1234-5678)
  • refresh=true - Force a cache refresh from ORCID (optional)

Quick Start

Fetching Works 

// Fetch a researcher's public works by username
const response = await fetch('/api/works?username=jsmith');
const works = await response.json();

console.log(works);
// Returns array of work objects with full details

Fetching Education History 

const response = await fetch('/api/educations?username=jsmith');
const educations = await response.json();

// Each education includes institution, degree, dates, etc.
for (const edu of educations) {
    console.log(edu.data);
}

Response Format

All endpoints return an array of activity objects with the following structure:

[
    {
        "put_code": 12345,
        "activity_type": "work",
        "data": {
            // Full ORCID activity data
            "title": { "title": { "value": "My Research Paper" } },
            "type": "journal-article",
            "publication-date": { "year": { "value": "2024" } },
            // ... additional fields
        },
        "last_modified_date": 1702742400000,
        "updated_at": "2024-12-16T12:00:00.000Z"
    }
]

Work Types

Works can be of various types including:

  • journal-article - Peer-reviewed journal articles
  • conference-paper - Conference proceedings
  • book - Books
  • book-chapter - Book chapters
  • dataset - Research datasets
  • preprint - Preprints
  • dissertation-thesis - Dissertations and theses

Example: Building a Publications List 

<div id="publications"></div>

<script>
async function loadPublications(username) {
    const response = await fetch(`/api/works?username=${username}`);
    
    if (!response.ok) {
        console.error('Failed to fetch publications');
        return;
    }
    
    const works = await response.json();
    const container = document.getElementById('publications');
    
    for (const work of works) {
        const data = work.data;
        const title = data.title?.title?.value || 'Untitled';
        const year = data['publication-date']?.year?.value || '';
        const type = data.type || 'unknown';
        
        const div = document.createElement('div');
        div.className = 'publication';
        div.innerHTML = `
            <h3>${title}</h3>
            <p class="meta">${type} - ${year}</p>
        `;
        container.appendChild(div);
    }
}

loadPublications('jsmith');
</script>

Example: Displaying Employment History 

async function getEmploymentHistory(orcid) {
    const response = await fetch(`/api/employments?orcid=${orcid}`);
    const employments = await response.json();
    
    return employments.map(emp => ({
        organization: emp.data.organization?.name,
        role: emp.data['role-title'],
        department: emp.data['department-name'],
        startDate: emp.data['start-date'],
        endDate: emp.data['end-date']
    }));
}

Caching and Rate Limits

  • Data is cached for 14 days to minimize load on ORCID's API
  • Forced refreshes (?refresh=true) are rate-limited to once per minute
  • If ORCID's API is unavailable, cached data will be returned as a fallback

Cache Response Headers

The response includes metadata about data freshness:

  • dataSource: fresh, cache, cache_fallback, or cache_rate_limited
  • lastUpdate: ISO timestamp of when data was last fetched
  • cacheAgeMs: Age of cached data in milliseconds

Visibility and Privacy

Only public activities are returned by this API. If a researcher has set an activity to "Trusted parties only" or "Private" in ORCID, it will not appear in API responses.

Visibility is checked against the current ORCID data, not the cached data, ensuring privacy settings are always respected.

Error Handling 

async function fetchWithErrorHandling(endpoint) {
    const response = await fetch(endpoint);
    const data = await response.json();
    
    if (!response.ok) {
        // Handle errors
        if (response.status === 404) {
            console.error('User not found:', data.error);
        } else if (response.status === 500) {
            console.error('Server error:', data.error);
        }
        return null;
    }
    
    return data;
}

Common Error Responses

Status Meaning
400 Missing username or orcid parameter
404 User not found in database
500 Failed to fetch from ORCID API

Need Help?

For questions about this API or to register your ORCID with the University of Waterloo, please contact the Library's Research Data Services team.

Back to home