About the ROR REST API

👍

ROR REST API v2

This page documents v2 of the ROR REST API. For v1 documentation of the ROR REST API, see https://ror.readme.io/v1/docs/rest-api. You can also read more about ROR API versions and a summary of what's new in Schema 2.0.

The ROR REST API allows users to retrieve, search, and filter the organizations indexed in ROR. The API is built with Django, indexing and search is enabled by Elasticsearch, and results are returned as JSON. Version 2 of the ROR REST API, released in April 2024, is available at https://api.ror.org/v2/organizations.

Queries to the ROR API will return all fields in ROR's data structure regardless of whether they have a value. JSON will include null values and empty arrays and objects if there is no value available for the given organization. Values in fields that contain multiple values are sorted by Unicode value, which is alphabetical for characters in the Basic Latin set.

Beginning 1 Dec 2022, the ROR API by default returns only records whose status is "active". Records with the new status values "inactive" and "withdrawn" can be included using the new query parameter ?all_status. In addition, after this date, some ROR records contain the new values "Predecessor" and "Successor" in relationships.type. See the 2022-12-01 changelog post for more details.

Registration and rate limits

No registration is required to use the ROR API, but note that the rate limit is a maximum of 2000 requests in a 5-minute period, and API traffic can be quite heavy at popular times like midnight UTC. If you need to make more requests or want to ensure faster response times, you can also run the entire ROR API locally in Docker. See the README on the ROR API GitHub repository for instructions on running the ROR API locally.

❗️

It is not possible to retrieve all ROR records from the API

The API is best for use cases that involve querying or retrieving individual records. The maximum number of results that can be retrieved via the API is 10,000, which means that it is currently not possible to retrieve all 100,000+ records from the ROR API. If you need to use the entire ROR dataset in your application, please download the data dump.

News and support

Users of the ROR API are strongly encouraged to sign up for the ROR Technical Forum Google Group in order to receive announcements, calls for feedback, release notifications, and other important information about the ROR API. Message volume is about twice monthly. ROR API users are also welcome to ask technical questions in the group.

Heartbeat

If your application uses the ROR API and you'd like it to send a quick health check to determine if the ROR API is operational, you can send a query to the ROR API heartbeat at https://api.ror.org/heartbeat. If the ROR API is up, you will receive a status of OK.

Status and uptime

If you'd like to check manually on the status of the ROR API or assess its uptime, see https://ror1.statuspage.io/ for full API status details and history. Our current API status and recent history is below.

Usage insights

Want to see how others are using the ROR API? Visit the public ROR API usage insights dashboard by DataDog.