Research Organization Registry API in Python

by Michael T. Moen

ROR API Documentation: https://ror.readme.io/docs/rest-api

ROR API License: https://ror.readme.io/docs/ror-basics#what-is-ror

The ROR API is licensed under the Creative Commons’ CC0 license, designating its data as part of the public domain.

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

These recipe examples were tested on January 19, 2023.

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

Setup

ROR Data Dump

When working with larger datasets, consider using the ROR data dump: https://ror.readme.io/docs/data-dump

Import Libraries

This tutorial uses the following libraries:

import requests                     # Manages API requests
from urllib.parse import quote      # URL encodes string inputs
from time import sleep              # Allows staggering of API requests to conform to rate limits

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'

# Use the quote() function to URL encode our search term
url = f'https://api.ror.org/organizations?query={quote(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: 25434
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 was 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'],
 'relationships': [{'label': 'Mississippi Alabama Sea Grant Consortium',
   'type': 'Related',
   'id': 'https://ror.org/04vzsq290'},
  {'label': 'University of Alabama System',
   'type': 'Parent',
   'id': 'https://ror.org/051fvmk98'}],
 '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': 4829764,
     'ascii_name': 'Alabama',
     'code': 'US.AL'},
    'geonames_admin2': {'name': 'Tuscaloosa',
     'id': 4094463,
     'ascii_name': 'Tuscaloosa',
     'code': 'US.AL.125'},
    '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': 6252001}],
 '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']},
  'OrgRef': {'preferred': None, 'all': ['327950']},
  '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:

    # Use the quote() function to URL encode our search term
    url = f'https://api.ror.org/organizations?query={quote(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 Psychiatric Research Center
Oxford: Stockholm Environment Institute
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:

    # Use the quote() function to URL encode our search term
    url = f'https://api.ror.org/organizations?query={quote(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 here: https://ror.org/tutorials/intro-ror-api/#filtering-results

# Filters are separated by commas
filters = ','.join([
    f'country.country_name:{quote("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']

4296

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([
    f'country.country_name:{quote("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]:

    # Use the quote() function to URL encode our search term
    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}')

American Society for Microbiology: https://ror.org/04xsjmh40
Austin College: https://ror.org/052k56z27
Austin Community College: https://ror.org/044tz3m61
Bacone College: https://ror.org/03rvph505
Bakersfield College: https://ror.org/00tz9e151
Baltimore City Community College: https://ror.org/03b286288
Bank Street College of Education: https://ror.org/04v44vh53
Bay Mills Community College: https://ror.org/005m1kj18
Bellingham Technical College: https://ror.org/03hjr5c64
Bishop State Community College: https://ror.org/036vmnd51
Bismarck State College: https://ror.org/042fn4q48
Bittersweet Farms: https://ror.org/02j7zcz08
Blackfeet Community College: https://ror.org/02kgm7r43
Bloomfield College: https://ror.org/04gdk0x87
Bluffton University: https://ror.org/05pacqm37
Boston Public Schools: https://ror.org/03bj7kr91
Bristol Community College: https://ror.org/05e168j76
Burlington School District: https://ror.org/00zbcp540
Calallen Independent School District: https://ror.org/00p5kvd83
California FarmLink: https://ror.org/02dz8kh28
California Teaching Fellows Foundation: https://ror.org/00j7csj22
College of Central Florida: https://ror.org/0354w0y78
DeKalb County School District: https://ror.org/03ka3vc13
Drummond Public Schools: https://ror.org/003p7hq46
Dublin Independent School District: https://ror.org/04hm48b29
Earth Learning: https://ror.org/01wzgqz67
Eastern Florida State College: https://ror.org/04tw5da48
Ecpi University: https://ror.org/04133ks15
Fielding Graduate University: https://ror.org/04csg5w40
Harding University Main Campus: https://ror.org/00t4cvq91
Hartnell College: https://ror.org/013yab158
Hawkeye Community College: https://ror.org/02b1scj45
Honolulu Community College: https://ror.org/00vpw9h05
Horry County Schools: https://ror.org/021x5j769
Iḷisaġvik College: https://ror.org/00mw3fh49
Judge Baker Children's Center: https://ror.org/05tby3y60
Louisiana State University System: https://ror.org/022gnbj15
Maricopa County Community College District: https://ror.org/004kyan19
Minnesota Agriculture in the Classroom Foundation: https://ror.org/0497prz03
Mobile County Public Schools: https://ror.org/00dtfmh68
Navajo Technical University: https://ror.org/05jkpmg51
New York Academy of Medicine: https://ror.org/00mwdv335
Northwestern Health Sciences University: https://ror.org/00186jw56
Oakton Community College: https://ror.org/020bcb226
Oglala Lakota College: https://ror.org/012y1mj37
Ohio Dominican University: https://ror.org/00pmncr36
Omak School District: https://ror.org/03vp4wk44
Philadelphia College of Osteopathic Medicine: https://ror.org/00m9c2804
Piedmont Technical College: https://ror.org/039y7c549
Piedmont Virginia Community College: https://ror.org/02tw58061
Pima Community College: https://ror.org/00wymkh76
Salus University: https://ror.org/00p82hn55
Social Sciences Innovations: https://ror.org/04b3jmc64
Southern Illinois University School of Medicine: https://ror.org/0232r4451
State University of New York College of Optometry: https://ror.org/02v9m6h26
Tennessee State University: https://ror.org/01fpczx89
Toyota Technological Institute at Chicago: https://ror.org/02sn5gb64
Truckee Meadows Community College: https://ror.org/04c0sqe08
University System of Georgia: https://ror.org/017wcm924
University System of New Hampshire: https://ror.org/0061x0487
University of Houston - Clear Lake: https://ror.org/01t817z14
University of Massachusetts Donahue Institute: https://ror.org/057e34m22
University of Nevada, Las Vegas: https://ror.org/0406gha72
University of Wisconsin–Extension: https://ror.org/05mdm7050
Valparaiso University: https://ror.org/01pp0fx48
Virginia Military Institute: https://ror.org/01ngnm118
Virginia State University: https://ror.org/04esvpn06
Virginia Union University: https://ror.org/02zwyfg51
Viterbo University: https://ror.org/039p8pn96
Wabash College: https://ror.org/00p11pk44
Washburn University: https://ror.org/04sk2ar21
Weber State University: https://ror.org/01epn2q93
Wesleyan University: https://ror.org/05h7xva58
West Virginia University: https://ror.org/011vxgd24
West Virginia University at Parkersburg: https://ror.org/00k5m1279
West Virginia Wesleyan College: https://ror.org/057nqxc22
Western Carolina University: https://ror.org/010h78f45
Western Kentucky University: https://ror.org/0446vnd56
Western Michigan University: https://ror.org/04j198w64
Western New England University: https://ror.org/007cnf143
Western New Mexico University: https://ror.org/00r5mr697
Western Oklahoma State College: https://ror.org/03tktyg33
Western Oregon University: https://ror.org/002xn4752
Westmont College: https://ror.org/00xhcz327
Wheeling Jesuit University: https://ror.org/02z310y44
Whitman College: https://ror.org/05axv8155
Whitworth University: https://ror.org/04j9d0s43
Wichita State University: https://ror.org/00c4e7y75
Wilberforce University: https://ror.org/02b50zn53
Willamette University: https://ror.org/04g9e0f44
William Woods University: https://ror.org/05ktv1y25
Williams College: https://ror.org/04avkmd49
Wilson College: https://ror.org/05japer20
Winston-Salem State University: https://ror.org/049yc0897
Winthrop University: https://ror.org/04mpzkf73
Wittenberg University: https://ror.org/04a23br85
Worcester State University: https://ror.org/04j8de466
Xavier University: https://ror.org/00f266q65
York College, City University of New York: https://ror.org/015a1ak54
Youngstown State University: https://ror.org/038zf2n28

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

institution_rors['Xavier University']

'https://ror.org/00f266q65'

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 = f'country.country_name:{quote("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:{quote("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_number in range(total_pages):

    # Use the quote() function to URL encode our search term
    url = f'https://api.ror.org/organizations?query={query}&filter={filter}&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}')

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