Research Organization Registry API in Python

Research Organization Registry API in Python#

by Michael T. Moen

The Research Organization Registry (ROR) API provides persistent identifiers for research organizations.

These recipe examples were tested on March 28, 2025.

NOTE: The ROR API limits requests to a maximum of 2000 requests in a 5-minute period.

Setup#

Import Libraries#

The following external libraries need to be installed into your enviornment to run the code examples in this tutorial:

We import the libraries used in this tutorial below:

import requests
from time import sleep

ROR Data Dump#

When working with larger datasets, consider using the ROR data dump.

1. Searching with Queries#

This first example uses the query parameter of the ROR API to search for an institution by name. In this example, we’ll search for The University of Alabama:

# The search query is the institution name
institution = 'University of Alabama'

# Construct URL and send HTTP request
url = f'https://api.ror.org/organizations?query={institution}'
response = requests.get(url).json()

# Print total number of results and number of results in page
print(f'Total number of results: {response["number_of_results"]}')
print(f'Page length: {len(response["items"])}')

Total number of results: 27751
Page length: 20

The results indicate that the query produced thousands of results, but only the data for 20 institutions were returned in this query. However, the top result is exactly what we were looking for:

# Display data of the top search result
response['items'][0]

{'id': 'https://ror.org/03xrrjk67',
 'name': 'University of Alabama',
 'email_address': None,
 'ip_addresses': [],
 'established': 1831,
 'types': ['Education', 'Funder'],
 'relationships': [{'label': 'University of Alabama System',
   'type': 'Parent',
   'id': 'https://ror.org/051fvmk98'},
  {'label': 'Mississippi Alabama Sea Grant Consortium',
   'type': 'Related',
   'id': 'https://ror.org/04vzsq290'}],
 'addresses': [{'lat': 33.20984,
   'lng': -87.56917,
   'state': None,
   'state_code': None,
   'city': 'Tuscaloosa',
   'geonames_city': {'id': 4094455,
    'city': 'Tuscaloosa',
    'geonames_admin1': {'name': 'Alabama',
     'id': None,
     'ascii_name': None,
     'code': 'US.AL'},
    'geonames_admin2': {'name': None,
     'id': None,
     'ascii_name': None,
     'code': None},
    'license': {'attribution': 'Data from geonames.org under a CC-BY 3.0 license',
     'license': 'http://creativecommons.org/licenses/by/3.0/'},
    'nuts_level1': {'name': None, 'code': None},
    'nuts_level2': {'name': None, 'code': None},
    'nuts_level3': {'name': None, 'code': None}},
   'postcode': None,
   'primary': False,
   'line': None,
   'country_geonames_id': None}],
 'links': ['https://www.ua.edu/'],
 'aliases': [],
 'acronyms': [],
 'status': 'active',
 'wikipedia_url': 'http://en.wikipedia.org/wiki/University_of_Alabama',
 'labels': [{'label': 'Universidad de Alabama', 'iso639': 'es'},
  {'label': "Université de l'Alabama", 'iso639': 'fr'}],
 'country': {'country_name': 'United States', 'country_code': 'US'},
 'external_ids': {'ISNI': {'preferred': None, 'all': ['0000 0001 0727 7545']},
  'FundRef': {'preferred': '100011531', 'all': ['100011531']},
  'Wikidata': {'preferred': None, 'all': ['Q492318']},
  'GRID': {'preferred': 'grid.411015.0', 'all': 'grid.411015.0'}}}

The following code produces the name, ROR ID, city, and wikipedia URL of the top result of the query:

response['items'][0]['name']

'University of Alabama'

response['items'][0]['id']

'https://ror.org/03xrrjk67'

response['items'][0]['addresses'][0]['city']

'Tuscaloosa'

response['items'][0]['wikipedia_url']

'http://en.wikipedia.org/wiki/University_of_Alabama'

Searching by Alternate Names#

The example below uses abbreviated forms of the full names of universities when searching:

# List of institutions to be searched
institutions = [
    'University of Alabama Tuscaloosa',
    'Missouri',
    'Dartmouth',
    'Oxford',
    'UCLA'
]

# Send an HTTP request for each institution
for institution in institutions:
    url = f'https://api.ror.org/organizations?query={institution}'
    search_data = requests.get(url).json()

    # Print the search term and the name of its top result
    print(f'{institution}: {search_data["items"][0]["name"]}')

    # Stagger requests to be nicer on the ROR servers
    sleep(0.5)

University of Alabama Tuscaloosa: University of Alabama
Missouri: Missouri Southern State University
Dartmouth: Dartmouth Hospital
Oxford: Oxford Optronix
UCLA: Universidad Centroccidental Lisandro Alvarado

The top results of the queries above are probably not what you would have expected. The example below remedies these issues by having more clearly defined search strings:

# List of institutions to be searched
institutions = [
    'University of Alabama Tuscaloosa',
    'University of Missouri',
    'Dartmouth College',
    'University of Oxford',
    'University of California Los Angeles'
]

# Send an HTTP request for each institution
for institution in institutions:
    url = f'https://api.ror.org/organizations?query={institution}'
    search_data = requests.get(url).json()

    # Print the search term and the name of its top result
    print(f'{institution}: {search_data["items"][0]["name"]}')

    # Stagger requests to be nicer on the ROR servers
    sleep(0.5)

University of Alabama Tuscaloosa: University of Alabama
University of Missouri: University of Missouri
Dartmouth College: Dartmouth College
University of Oxford: University of Oxford
University of California Los Angeles: University of California, Los Angeles

2. Searching with Filters#

The ROR API also allows searches to be performed with the filter parameter, which can take 3 arguments: status, types, and country. For more information on what values these arguments can take, read the ROR documentation.

filters = ','.join([
    'country.country_name:United States',
    'types:Education',
    'status:Active'
])

# URL constructed with the filters
url = f'https://api.ror.org/organizations?filter={filters}'
response = requests.get(url).json()

# Display number of results
response['number_of_results']

4331

Paging through a Result#

The example below pages through the results to find the names and ROR IDs of the first 100 institutions returned using the filter:

# Filters to are separated by commas
filters = ','.join([
    'country.country_name:United States',
    'types:Education',
    'status:Active'
])

# URL constructed with the filters
url = f'https://api.ror.org/organizations?filter={filters}'
response = requests.get(url).json()

# Calculate number of pages in result
total_pages = (response['number_of_results'] // len(response['items'])) + 1

# Store resulting names in a dictionary
institution_rors = {}

# Limited to first 5 pages for this tutorial
for page_number in range(total_pages)[:5]:
    url = f'https://api.ror.org/organizations?filter={filters}&page={page_number+1}'
    search_data = requests.get(url).json()

    # Add institution names and ROR IDs to the institution_results list
    for result in search_data['items']:
        institution_rors[result['name']] = result['id']

    # Stagger requests to be nicer on the ROR servers
    sleep(0.5)

# Display first 100 results
for name, ror_id in sorted(institution_rors.items()):
    print(f'{name}: {ror_id}')

Albert Einstein Academy: https://ror.org/01fhhqb25
Albuquerque Academy: https://ror.org/04bty2w72
American College of Veterinary Ophthalmologists: https://ror.org/010m1h651
American University of Beirut New York Office: https://ror.org/05t3agv77
Arizona School for the Arts: https://ror.org/00a0wam85
Arkansas State University System: https://ror.org/0152qkr29
Asbestos Institute: https://ror.org/058kkmh35
Avraham Y. Goldratt Institute: https://ror.org/00me50c36
BMCC Tribeca Performing Arts Center: https://ror.org/021rrz441
Beck Institute for Cognitive Behavior Therapy: https://ror.org/0271pep11
Beth Mardutho: https://ror.org/01agawy76
Brown-Spath & Associates: https://ror.org/05h7bqz94
Bucks County Intermediate Unit: https://ror.org/052bwdm80
Cacapon Institute: https://ror.org/02bt8sv61
California Northstate University: https://ror.org/03h0d2228
Chattahoochee Valley Community College: https://ror.org/052rvpm80
Chhandam School of Kathak: https://ror.org/01z2dq675
Chicago Arts Partnerships in Education: https://ror.org/02pd2vd80
Chicago Youth Symphony Orchestras: https://ror.org/04mm4cb76
ChildCare Education Institute: https://ror.org/032nv5f98
College of the Muscogee Nation: https://ror.org/01qfzbz52
Collingswood Public Schools: https://ror.org/04c9j0t17
Courant Institute of Mathematical Sciences: https://ror.org/037tm7f56
Dallas Theological Seminary: https://ror.org/03cv0r897
Dominican School of Philosophy and Theology: https://ror.org/015yfqq31
East Baton Rouge Parish School System: https://ror.org/05cendc56
Emergency University: https://ror.org/011bbtj34
Fairfax County Public Schools: https://ror.org/04nrt0320
Frederick Community College: https://ror.org/05c0t8x83
GDP Ayurvedic University: https://ror.org/02s1nfr38
Garden Street Academy: https://ror.org/039e9be94
Garrett–Evangelical Theological Seminary: https://ror.org/03ncber98
Germanna Virginia Community College: https://ror.org/03dgxrg98
Graduate Institute of Applied Linguistics: https://ror.org/02jr43a19
Green River Community College: https://ror.org/04s68af23
Hendrick Hudson School District: https://ror.org/0431j1g69
Institute for Education in International Media: https://ror.org/02mrr4460
Juilliard School: https://ror.org/04g449w06
Kansas City Public Schools: https://ror.org/03pvzeb17
Kellogg Community College: https://ror.org/00q709v87
Kent State University Geauga: https://ror.org/005d5fb76
Kent State University, East Liverpool: https://ror.org/03a5bb278
Kern Community College District: https://ror.org/04zyefw11
Kingswood Oxford: https://ror.org/01ex19q32
Kona Pacific Public Charter School: https://ror.org/04wjnw514
Lafourche Parish School District: https://ror.org/020h7tk57
Lake Region State College: https://ror.org/05grcng38
Lakeland College: https://ror.org/01awa7g66
Language Systems International College of English: https://ror.org/04qfef108
Larkin University: https://ror.org/00zjk7642
Learning Through an Expanded Arts Program: https://ror.org/01yq8nk56
Lees McRae College: https://ror.org/05g1rz111
Lehman College Art Gallery: https://ror.org/04xpe4755
Limón Institute: https://ror.org/03mq02m67
Maine Central Institute: https://ror.org/02z02sq57
MidSchoolMath: https://ror.org/04m0rev75
Mitchell School District: https://ror.org/055kj8f51
National Dance Institute of New Mexico: https://ror.org/049sa5a53
National University System: https://ror.org/00yd8np83
New Mexico Military Institute: https://ror.org/00qc4yc66
Northeast Maritime Institute: https://ror.org/04s36mr71
Northshore Education Consortium: https://ror.org/027nc8m92
Ola Grimsby Institute: https://ror.org/04v51kr79
Oprah's Angel Network: https://ror.org/04dqbhd05
Pacific Arts Association: https://ror.org/00zpw7s04
Pomfret School: https://ror.org/038v0bj29
Port Washington Public Library: https://ror.org/052n2hz50
Purdue University Fort Wayne: https://ror.org/04c4hz115
Purdue University Northwest: https://ror.org/04keq6987
Ramah Navajo School Board: https://ror.org/02ejgsx19
Rochester Community and Technical College: https://ror.org/05pvfsz50
Ross School: https://ror.org/00tpdkh38
Salem City Schools: https://ror.org/03mrd4308
San Diego State University, Imperial Valley Campus: https://ror.org/048bd3118
Seamester: https://ror.org/05rd7y749
Seattle Film Institute: https://ror.org/01v9w5g84
Skin Science Institute: https://ror.org/02j787g88
Southeast Island School District: https://ror.org/05ezypx20
Southern Association of Colleges and Schools: https://ror.org/006gdfw37
Southington Public School: https://ror.org/0280brb18
Southwestern Community College - North Carolina: https://ror.org/03bwbnb24
St. Vrain Valley School District: https://ror.org/00n860n87
Studio in a School: https://ror.org/02dnkgs07
The Association of Boarding Schools: https://ror.org/05ntjbh41
The Harley School: https://ror.org/02a03v538
The Judge Advocate General's Legal Center and School: https://ror.org/03zwqne39
The Northwest School: https://ror.org/024bajv16
The Performance Institute: https://ror.org/00fh64z73
The Reed Institute: https://ror.org/02sncd318
University Bank: https://ror.org/0349geh35
University High School: https://ror.org/01a51dp76
University Resident Theatre Association: https://ror.org/058tkvp17
University School: https://ror.org/05ap66461
University Vascular Associates: https://ror.org/0432s1v23
University of Maryland Extension: https://ror.org/03r8q5f36
Washington Glass School: https://ror.org/05a0w0e26
Wayne-Finger Lakes BOCES: https://ror.org/05n4dxt42
Western Forensic Law Enforcement Training Center: https://ror.org/015mspw86
Westford Academy: https://ror.org/01wag9e37
Westminster Schools: https://ror.org/02ammvg77

The resulting dictionary can be used to find the ROR of an institution based on its name:

institution_rors['Purdue University Fort Wayne']

'https://ror.org/04c4hz115'

3. Searching with Queries and Filters#

The filter and query parameters can both be used in a single request. In this example, we filter the results of the query “Birmingham” to only include institutions from the United States:

# Filter results to the United States
filter = 'country.country_name:United States'

# Search term
query = 'Birmingham'

# URL constructed with the filters
url = f'https://api.ror.org/organizations?query={query}&filter={filter}'
response = requests.get(url).json()

# Display number of results
response['number_of_results']

12

# Filter results to the United States
filter = f'country.country_name:United States'

# Search term
query = 'Birmingham'

# URL constructed with the filters
url = f'https://api.ror.org/organizations?query={query}&filter={filter}'
response = requests.get(url).json()

# Calculate number of pages in result
total_pages = (response['number_of_results'] // len(response['items'])) + 1

# Store resulting names in a dictionary
institution_rors = {}

# Limited to first 5 pages for this tutorial
for page_no in range(total_pages):
    url = f'https://api.ror.org/organizations?query={query}&filter={filter}&page={page_no+1}'
    search_data = requests.get(url).json()

    # Add institution names and ROR IDs to the institution_results list
    for result in search_data['items']:
        institution_rors[result['name']] = result['id']

    # Stagger requests to be nicer on the ROR servers
    sleep(0.5)

# Display first 100 results
for name, ror_id in sorted(institution_rors.items()):
    print(f'{name}: {ror_id}')

Alabama Audubon: https://ror.org/02qbyex13
Birmingham Bloomfield Community Coalition: https://ror.org/004mx7t23
Birmingham Civil Rights Institute: https://ror.org/00fqce595
Birmingham Museum of Art: https://ror.org/030y6zg68
Birmingham Public Library: https://ror.org/05czff141
Birmingham VA Medical Center: https://ror.org/0242qs713
Birmingham–Southern College: https://ror.org/006g42111
St. Vincent's Birmingham: https://ror.org/000crk757
UAB Medicine: https://ror.org/036554539
University of Alabama at Birmingham: https://ror.org/008s83205
University of Alabama at Birmingham Hospital: https://ror.org/01rm42p40
Vision Specialists of Michigan: https://ror.org/02awhp844
Contents