# ROR API (Research Organization Registry) MCP > ROR API (Research Organization Registry) connects your AI agent to a global database of over 100,000 research institutions. It lets you search for specific academic entities using keyword filters or advanced syntax. You can retrieve complete metadata—including official ROR IDs and external identifiers like GRID—for data cleaning and scholarly record verification. ## Overview - **Category:** data-management - **Price:** Free - **Tags:** academic-research, metadata, persistent-identifiers, institutional-data, search-api ## Description You're hooking your AI agent up to the **Research Organization Registry (ROR)** API. This isn't just some general database; it connects you directly to a global pool of over 100,000 records for academic institutions. When you pull this server into your workspace, you get immediate access to verified metadata. You don't have to guess if an institution exists or what its official ID is. It’s essential for cleaning up messy scholarly data. **Checking API Status with `get_heartbeat`** Before you run any complex query, you gotta check the pipes first. Running `get_heartbeat` confirms whether the entire ROR service is actually running right now. This tool gives you a simple confirmation that the Research Organization Registry connection is live and operational, so your agent doesn't waste time hitting dead ends. **Finding Specific Institutions with `get_organization`** You need details on one specific place? Use `get_organization`. You feed it an identifier—that can be the institution’s full URL, its domain name, or even a known ROR ID. This tool doesn't give you general info; it pulls the complete metadata record for that single entity. When you run this, your agent gets everything: the official ROR ID, external identifiers like GRID and ISNI, location data, and all the associated details needed to confirm an institution’s existence and structure. **Searching and Listing Multiple Institutions with `list_organizations`** When you're dealing with a bunch of records—say, cleaning up a bibliography that lists twenty different affiliations—you run `list_organizations`. This tool is your discovery engine. You can search for groups of institutions by applying general keyword queries or advanced filters. These filters let you narrow down the results far beyond simple text matching; they let you use complex syntax to pinpoint exactly what you need. If you're working with affiliation strings that are a mess, this tool handles it too. You can pass in specific affiliation strings so your agent finds groups of related academic bodies across different domains. It manages the search by applying general queries and advanced filters simultaneously, giving you a comprehensive list of candidates to verify. When combining these functions, your AI client uses `list_organizations` to narrow down potential matches based on complex criteria, then it can use `get_organization` on the resulting IDs or domains to pull the final, verified metadata for each one. It's how you turn sloppy reference data into clean, actionable records. **What You Can Actually Do:** * You run `get_heartbeat` to confirm the API is up and running before anything else. * If you know an institution's exact domain or ID, use `get_organization` for a definitive data pull. * To find groups of institutions, feed specific queries, advanced filters (like Elasticsearch syntax), or messy affiliation strings into `list_organizations`. This process allows your agent to identify potential entities across huge datasets. It helps you resolve those unstructured affiliations found in papers and map them to official ROR identifiers. ## Tools ### get_organization Fetches a single, detailed record for an organization using its full URL, domain name, or ROR ID. ### get_heartbeat Checks the API status to confirm if the Research Organization Registry is currently operational. ### list_organizations Searches and retrieves a list of organizations by applying general queries, advanced filters, or affiliation strings. ## Prompt Examples **Prompt:** ``` Search for research organizations in Brazil with the type 'education'. ``` **Response:** ``` I'll search the ROR registry for you. Using `list_organizations` with the filter `types:education,locations.geonames_details.country_code:BR`, I found several institutions including 'Universidade de São Paulo' (ROR: 0369vth32). ``` **Prompt:** ``` Get the full record for ROR ID 015w2mp89. ``` **Response:** ``` Fetching details for `015w2mp89`... This record corresponds to 'University of Cambridge'. It is an active education institution located in the United Kingdom, with external IDs including GRID: grid.5335.0. ``` **Prompt:** ``` Check if the ROR API is currently online. ``` **Response:** ``` I'll check the system status using `get_heartbeat`. The ROR API responded with 'OK', so the service is fully operational. ``` ## Capabilities ### Check API operational status Runs the `get_heartbeat` tool to confirm if the ROR service is currently available. ### Retrieve single organization details Uses `get_organization` to fetch a complete record for one institution, given its ID, full URL, or domain name. ### Search and list multiple organizations Runs `list_organizations` by applying specific queries, advanced filters, or affiliation strings to find groups of institutions. ## Use Cases ### Cleaning citation lists from old papers A librarian receives a grant proposal with dozens of manually typed affiliations. Instead of correcting them one by one, they prompt their agent: 'Clean this list.' The agent uses `list_organizations` to find all entities and then `get_organization` to fetch the official ROR ID for each, giving you a clean dataset in minutes. ### Verifying institutional relationships A policy analyst needs to see if two collaborating institutions are parent/child organizations. They use `list_organizations`, filtering by location and type, which returns a list that they can then process with `get_organization` to confirm their official relationship structure. ### Building a new research portal database A developer needs metadata for every university in a specific state. They run a targeted search using `list_organizations` with advanced filters (e.g., location codes). The resulting list allows them to systematically pull all necessary identifiers and domain names. ### Quickly checking system uptime A data scientist starts their morning workflow and needs to make sure the ROR source is stable before running complex queries. They run a quick `get_heartbeat` check first. If it returns 'OK', they know they can trust the subsequent, more resource-intensive calls. ## Benefits - Stop dealing with vague institutional names. The `list_organizations` tool lets you search by keyword or use advanced filters to find the exact research entities you need, narrowing thousands of possibilities down to a precise list. - Instantly get full metadata for any institution using `get_organization`. You don't just get a name; you get official ROR IDs and external identifiers like GRID: grid.5335.0—data essential for data integrity. - It handles the hardest part of academic research data: messy affiliations. Use these tools to resolve unstructured strings from papers into clean, verifiable global standards. - Before running big queries, check in with `get_heartbeat`. This simple call confirms the API is up and ready to go, preventing failed runs and wasted time on a downed service. - Build better research systems. By automating metadata retrieval via this MCP server, you eliminate manual cross-referencing against multiple academic databases. ## How It Works The bottom line is, your AI client runs these tools against a massive global registry so you don't have to manually cross-reference academic databases. 1. First, subscribe to the ROR API server. You can optionally input your ROR Client ID for tracking. 2. Next, prompt your AI client with a request (e.g., 'Find all universities in Texas'). The agent determines it needs `list_organizations` and executes the query. 3. Finally, the server returns structured JSON containing lists of institutions or detailed records that you can use to clean up data. ## Frequently Asked Questions **How do I check if the ROR API is working with `get_heartbeat`?** Call `get_heartbeat`. If it responds with 'OK', the service is operational. This quick check confirms connectivity before you run any complex queries, saving time and preventing failed runs. **What kind of filters can I use in `list_organizations`?** You can search using keywords, advanced Elasticsearch syntax, or by specific affiliation strings. This lets you narrow down the 100k+ records to a manageable list based on location or type. **If I have an ROR ID, which tool should I use?** Use `get_organization`. It's designed specifically to take a known identifier (like the full ROR ID) and retrieve the complete, detailed record for that single institution. **Does this help me match messy names? Using `list_organizations`?** Yes. The tools are built to resolve unstructured affiliation strings from research papers into official ROR identifiers, which is exactly what you need for data cleaning. **When I run `list_organizations`, do I need a specific API key for my AI client?** You can optionally supply your ROR Client ID. This helps track the traffic associated with your queries, which is important if you are running high volumes of searches or collaborating on multiple projects. **How flexible is `get_organization` if I don't have the exact ROR ID?** The tool is highly flexible. You can pass a full URL, just the domain combined with an ID, or simply use the raw ROR identifier. This makes fetching records much more robust than relying on one single input type. **When I use `get_organization`, what specific metadata fields can I expect to receive?** It retrieves a full record set for the organization, including its ROR ID, location data, website domain, and external identifiers like GRID and ISNI. You get everything needed for comprehensive academic mapping. **For large datasets, how efficient is searching using `list_organizations`?** The tool supports advanced Elasticsearch syntax along with keyword searches. This mechanism lets you narrow down results quickly and efficiently across tens of thousands of records. **How can I find a ROR ID for a specific university name?** Use the `list_organizations` tool with the `query` parameter. For example, searching for 'University of Cambridge' will return the matching record and its unique ROR ID. **Can I retrieve external identifiers like GRID or ISNI for an organization?** Yes! When you use `get_organization` with a ROR ID, the response includes a crosswalk to other identifiers like GRID, ISNI, Crossref Funder ID, and Wikidata. **Is there a way to check if the ROR service is currently available?** You can use the `get_heartbeat` tool. It performs a simple check and returns an 'OK' status if the ROR API is operational.