Pure API Guide: h-IndexesPure API Guide: h-Indexes

Requirements

This guide is intended for users with intermediate experience working with the Pure API. It assumes familiarity with API concepts such as pagination, UUIDs, and JSON response structures.

• The API key must be linked to an appropriate access definition with sufficient data visibility.
• For setup instructions, refer to the Pure API: Access definitions for content and field filtering.

• Knowledge of post-processing tools (e.g., Power BI, Excel, Python, etc.) to transform and sort output if needed.

API Endpoints Used

• GET /persons
• GET /persons/{uuid}/metrics/hIndex

Data Retrieval and Processing Workflow

1. Retrieve Academic Person Records

Endpoint:
GET /persons?size=300&offset=...

Pagination Strategy:
Loop through all pages to collect person records. For each person:

• Evaluate the staffOrganizationAssociations block.
• Include only those where staffType.uri ends in /academic or where the term includes “academic”.
• Store the UUID and full name (Last name, First name) for each qualifying person.

This ensures that h-index aggregation is performed only for academic staff.

2. Retrieve h-Index Metrics by Source and Category

For each academic person's UUID:

Endpoint:
GET /persons/{uuid}/metrics/hIndex

Response Parsing:

• Iterate through the items array.
• For each item:
  • Extract the source (source.term.en_US or source.term.en_GB)
  • Extract the category (category.term.en_US or source.term.en_GB), such as:
    • “All years”
    • “5 years”
    • “10 years”
  • Identify the h-index value where metricId = "hindex"

Group results by:

• Source (e.g., Scopus, PlumX)
• Category (All years, 5 years, 10 years)

Use 0 as default if a value is missing for a given category.

3. Organize and Sort Output

For each person:

• Build a result object containing:
  • Full name (LastName, FirstName)
  • Source
  • h-index values by category:
    • h-index (All years)
    • h5-index (5 years)
    • h10-index (10 years)

Sorting (optional):
Alphabetically by last name (case-insensitive) to align with institutional reporting conventions.

4. Convert API Results for Reporting Use

Once the API results are structured: 

Convert the data into a format suitable for your preferred reporting or analysis tools (e.g., CSV, TXT, Excel, JSON, database-ready structures, etc.)

Suggested output columns:

• Name
• Source
• h-index (All years)
• h5-index (5 years)
• h10-index (10 years)

Output formats:

Output a file. (post processing tool).

Post-Processing Logic

Client-side Grouping & Defaults

The Pure API does not directly return grouped or comparative source data.

• Time categories like “5 years” or “10 years” appear as part of the response and must be organized per source manually.
• Any missing values for expected categories are defaulted to 0.

Sorting & Readability

• Sorting is applied on the last name to mirror report layouts used in Pure Admin.
• Final results can be adapted for display in tools like dashboards or Excel.

Validation and Accuracy Check

To ensure output accuracy:

• Cross-check values for a few individuals against entries in Pure Admin’s Person Editor or Reporting Workspace.
• Confirm that time categories (“All years”, “5 years”, “10 years”) align with internal terminology.
• This helps build trust in the API-driven process.

Permissions and Data Access

• The /persons and /metrics/hIndex endpoints respect your API key's access scope.
• If your key lacks permission to retrieve h-index data, results may differ from what’s visible in Pure Admin.
• Always validate that your access definition includes metric data retrieval privileges.

Summary

This guide is designed to support institutions aiming to:

• Extract h-index scores from multiple sources.
• Automate recurring insights aligned with Pure Admin reports.
• Replicate or customize reporting outputs for integration with external systems.

By using the Pure API directly, institutions gain flexibility and control over how research metrics are analyzed and shared, without depending on manual extraction from the Pure Admin interface.