README.md

RORClient

🚀 A Python client for interacting with the ROR API. RORClient provides a simple, efficient way to query the Research Organization Registry (ROR) API using HTTPX and Pydantic.

---

📖 Table of Contents

• Installation
• Quick Start
• Synchronous Client
• Asynchronous Client
• Models
• Testing
• Contributing
• License

---

⚡ Installation

You can easily install rorclient using pip:

pip install rorclient

---

🚀 Quick Start

Synchronous Client

from rorclient import RORClient

with RORClient() as client:
    # Get institution details
    org = client.get_institution("03yrm5c26")
    if org:
        print(f"Found institution: {org.name}")

    # Fetch multiple institutions
    multiple_orgs = client.get_multiple_institutions(["03yrm5c26", "029z82x56"])
    print(f"Fetched {len(multiple_orgs)} institutions")

Asynchronous Client

import asyncio
from rorclient import AsyncRORClient

async def main():
    async with AsyncRORClient() as client:
        # Get institution details
        org = await client.get_institution("03yrm5c26")
        if org:
            print(f"Found institution: {org.name}")

        # Fetch multiple institutions
        multiple_orgs = await client.get_multiple_institutions(["03yrm5c26", "029z82x56"])
        print(f"Fetched {len(multiple_orgs)} institutions")

asyncio.run(main())

---

🏛 Models

RORClient uses Pydantic models to structure API responses. The main model is Institution, which represents an organization in ROR.

Example usage:

from rorclient import RORClient

client = RORClient()
org = client.get_institution("03yrm5c26")

if org:
    print(org.name)  # Stanford University
    print(org.external_ids)  # External identifiers like GRID, ISNI
    print(org.location.country)  # Country of the institution

For a full list of available fields, see the institution.py file. You can also have a look at the ROR API documentation

---

🧪 Testing

To run the test suite, run:

uv run pytest

---

🤝 Contributing

Contributions are welcome! Please open an issue or submit a pull request.

---

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.