Pure API Guide: Total Number of Research Outputs per GenderPure API Guide: Total Number of Research Outputs per Gender

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.

• A valid API key with access to /research-outputs and /persons endpoints is required.
• 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 /research-outputs
• GET /persons/{uuid}

Data Retrieval Process (via Pure API)

1. Retrieve Research Outputs (Paginated)

• Endpoint: GET /research-outputs?size=300&offset=…
  • Use a loop to paginate through all research outputs.
  • Extract the list of contributors from each research output record.

2. Identify Internal Contributors

• Filter contributors with typeDiscriminator == "InternalContributorAssociation".
• These contributors are associated with persons in the Pure system.

3. Retrieve Gender from Contributor UUIDs

• For each internal contributor, extract the person.uuid.
• Perform a lookup using GET /persons/{uuid}.
• Parse the gender from the person record’s gender.uri field.
• Use a cache to avoid repeated API calls for the same UUID.

4. Aggregate Research Outputs by Gender

• For each research output, gather all associated contributor genders.
• If a research output includes contributors from multiple genders, count it once per gender.
• Tally the total number of research outputs per gender.

5. Convert API Results for Reporting Use

• Convert the data into a format suitable for your preferred reporting or analysis tools (e.g., CSV, TXT, Excel, JSON, database-ready structures, etc.)
• Total number of research outputs
• Breakdown of research outputs per gender: Male, Female, Unknown, Other

Post-Processing Logic

While the Pure API provides raw structured data, summary statistics such as totals and groupings must be calculated client-side. The approach outlined here offers a practical example of how post-processing can be applied to derive meaningful insights.

Contributor Filtering

• Include only InternalContributorAssociation types.
• This ensures we only examine internal Pure persons.

Gender Classification

• Extract the gender URI from each person record.
• Convert the URI suffix into a readable gender label (e.g., /gender/male → "Male").
• If the gender is missing or unknown, classify as "Unknown".

Output Counting

• Track research output UUIDs by gender.
• Each research output is counted once per gender represented among its internal contributors.
• Results are stored in a gender-wise dictionary.

Output Format

The post-processed results can be exported to a human-readable file with the following structure:

Number of Research Outputs per Gender
Total Research Outputs: <number>

Total Number of Research Outputs per Gender
Male        <count>
Female      <count>
Unknown     <count>
Other       <count>

Data Validation

• To ensure the data retrieved from the API aligns with internal reporting:
  • Compare the total research output count obtained through the API with the totals shown in the Research Output editor within Pure Admin.
  • Cross-check gender labels and counts with those in a built-in Reporting Workspace or in Pure Admin Editor Workspace (if available).
• This comparison helps validate:
  • The correctness of API data interpretation
  • That filtering logic is consistent between API-based and in-platform reports
  • That custom reports using the API can be trusted by institutional stakeholders

Permissions and Access

Please ensure:

• Your API key has visibility into the necessary person records.
• Data visibility is subject to user-based access controls.
  • Some records may be excluded if your API access is restricted by organizational units or roles.

Summary

This example outlines how to replicate a common reporting insight from Pure Admin using Pure API endpoints and post-processing logic. It focuses on retrieving and analyzing research output data by gender, emphasizing:

• Pagination through records using the /research-outputs endpoint to gather a comprehensive dataset.
• Entity resolution by linking each internal contributor to their corresponding person record via the /persons/{uuid} endpoint to extract gender details.
• Post-processing to apply grouping and aggregation logic — such as counting each research output once per gender represented — to mirror the structure of built-in reporting outputs.