Client

Functions for searching schools and professors, fetching ratings, and filtering reviews.

All functions communicate with the RateMyProfessors GraphQL API over HTTPS. No authentication is required.

---

Search result types

search_schools returns list[SchoolResult] and search_professors returns list[ProfessorResult]. Both are typed dataclasses -- use attribute access, not dict indexing.

school = search_schools("UC Berkeley")[0]
school.id           # base64 node ID -- pass this to other functions
school.legacy_id    # integer -- only useful for building profile URLs
school.name         # "University of California, Berkeley"

professor = search_professors("John DeNero", school.id)[0]
professor.id        # base64 node ID -- pass this to get_all_ratings, etc.
professor.legacy_id # integer -- only useful for building profile URLs

See Models for the full field list on each type.

---

Error handling

Functions that make network requests return None or [] on failure and print the exception to stdout. They do not raise. If you're getting empty results unexpectedly, check for printed error messages.

---

Caching

search_schools, search_professors, get_courses, and the internal paginator are decorated with lru_cache. Repeated calls with the same arguments return cached results without hitting the network. The cache lasts for the lifetime of the Python process. Call .cache_clear() on any of these functions to invalidate manually.

---

Functions

Functions for searching schools and professors, fetching ratings, and filtering reviews.

search_schools(school_name) cached

Search for schools by name.

Parameters:

Name	Type	Description	Default
school_name	str	Full or partial school name to search.	required

Returns:

Type	Description
list[SchoolResult] | None	List of :class:~models.SchoolResult objects ranked by relevance.
list[SchoolResult] | None	None on request or parsing failure.

search_professors(professor_name, school_id) cached

Search for professors by name within a school.

Parameters:

Name	Type	Description	Default
professor_name	str	Full or partial professor name to search.	required
school_id	str	Base64-encoded RMP school node ID (e.g. "U2Nob29sLTEyMw==") from :func:search_schools.	required

Returns:

Type	Description
list[ProfessorResult] | None	List of :class:~models.ProfessorResult objects ranked by relevance.
list[ProfessorResult] | None	None on request or parsing failure.

get_professor_summary(professor_name, school_id)

Fetch aggregate summary for the top search result matching a professor.

Wraps :func:search_professors and extracts the first result's stats. When no match is found, returns a sentinel ProfessorRating with all numeric fields set to -1 and num_ratings set to 0.

Parameters:

Name	Type	Description	Default
professor_name	str	Full or partial professor name.	required
school_id	str	Base64-encoded RMP school node ID.	required

Returns:

Type	Description
ProfessorRating	ProfessorRating with fields:
ProfessorRating	avg_rating, avg_difficulty, would_take_again_percent,
ProfessorRating	num_ratings, formatted_name, department, link.

get_ratings_page(professor_id, count=20, course_filter=None, cursor=None)

Fetch one page of ratings for a professor.

Parameters:

Name	Type	Description	Default
professor_id	str	Base64-encoded RMP professor node ID.	required
count	int	Max ratings to return per page (default 20).	20
course_filter	str | None	Optional course code string to filter ratings (e.g. "CS61A").	None
cursor	str | None	Opaque pagination cursor from a previous call's end_cursor. None fetches the first page.	None

Returns:

Type	Description
list[Rating]	3-tuple (ratings, has_next_page, end_cursor) where:
bool	ratings is a list of :class:~models.Rating objects,
str | None	has_next_page signals more pages exist,
tuple[list[Rating], bool, str | None]	and end_cursor is passed as cursor in the next call (None on last page).
tuple[list[Rating], bool, str | None]	Returns ([], False, None) on failure.

get_all_ratings(professor_id, course_filter=None, page_size=20)

Fetch all ratings for a professor, auto-paginating until exhausted.

Results are cached per (professor_id, course_filter, page_size) for the lifetime of the process. Call :func:get_all_ratings.cache_clear (via _fetch_all_ratings_cached.cache_clear()) to invalidate manually.

Parameters:

Name	Type	Description	Default
professor_id	str	Base64-encoded RMP professor node ID.	required
course_filter	str | list[str] | None	Optional course code(s) to filter ratings. Accepts a single string (e.g. "CS61A"), a list of strings (e.g. ["CS61A", "CS61B"]), or None for all ratings. When a list is given, one paginated request sequence is made per course and results are concatenated in the same order.	None
page_size	int	Ratings fetched per page (default 20).	20

Returns:

Type	Description
list[Rating]	Combined list of :class:~models.Rating objects across all pages.
list[Rating]	Empty list if the first page fails.

get_representative_ratings(professor_id, n=12, course_filter=None)

Return n ratings evenly sampled across all available ratings.

Ratings are ordered newest -> oldest by the API. Sampling is uniform by index (stride = total // n), so the result spans the full temporal range. If the professor has <= n ratings, all are returned as-is.

Parameters:

Name	Type	Description	Default
professor_id	str	Base64-encoded RMP professor node ID.	required
n	int	Number of representative ratings to return (default 12).	12
course_filter	str | list[str] | None	Optional course code(s) to restrict ratings. Accepts a single string or list of strings (e.g. ["CS61A", "CS61B").	None

Returns:

Type	Description
list[Rating]	List of up to n :class:~models.Rating objects.

get_courses(professor_id) cached

Fetch all courses a professor has taught, as listed in the RMP review filter.

Parameters:

Name	Type	Description	Default
professor_id	str	Base64-encoded RMP professor node ID.	required

Returns:

Type	Description
list[dict] | None	List of dicts with keys courseName (str) and courseCount (int),
list[dict] | None	sorted by courseCount descending.
list[dict] | None	None on request or parsing failure.

filter_ratings_by_keywords(ratings, keywords, match_all=False, case_sensitive=False)

Filter ratings whose comment contains one or more keywords.

Parameters:

Name	Type	Description	Default
ratings	list[Rating]	List of :class:~models.Rating objects to filter.	required
keywords	str | list[str]	Keyword string or list of keyword strings to search for. Each keyword is matched as a substring of the comment.	required
match_all	bool	When True, a rating must contain all keywords (AND logic). When False (default), any single keyword match is sufficient (OR logic).	False
case_sensitive	bool	When True, matching is case-sensitive. Default False (case-insensitive).	False

Returns:

Type	Description
list[Rating]	List of :class:~models.Rating objects whose comment field
list[Rating]	satisfies the keyword filter. Preserves original order.
list[Rating]	Ratings with an empty or None comment are always excluded.