Top-ranked books
get_top_booksReturns the top of one of the ranked book lists published on readingrate.com: the highest-ranked books from a country, in an original language, of a genre or on a subject, by women or by men, or at a difficulty. With no filter it returns ReadingRate's curated canon of 100, ranked by hand. Every other list is computed from literary-regard scores (canonical status, critical acclaim and influence), not readers' votes. Each answer gives the list's page address.
Use when the user asks for the top, greatest or most important books of a country, a language, a genre, a period or a theme, for a ranked reading list, or for the hardest or easiest great books. For books matching a search, use search_books; for prize results, use get_award_winners.
Filters combine: {"country": "Japan", "author_gender": "female"} ranks books by Japanese women. A country or language with no list page is still ranked when the catalog holds books from it, and the answer says how many books the list holds.
Examples:
{"country": "Japan", "limit": 10}
{"country": "Nigeria"}
{"language": "Russian", "genre": "short-fiction"}
{"subject": "death-mortality"}
{"subject": "victorian-19th-century-literature", "author_gender": "female"}
{"difficulty": "hardest", "limit": 5}
{}
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| genre | No | A genre: literary-fiction, historical-fiction, romance, fantasy, science-fiction, mystery-crime, thriller, horror, satire-humor, coming-of-age, short-fiction, war-fiction, poetry, drama, memoir, biography, essays, philosophy, history, science, politics-society, psychology-self, religion, childrens, young-adult, graphic-novels, lgbtq, nonfiction | |
| limit | No | How many books from the top of the list (default 10, max 100) | |
| country | No | The authors' country, e.g. "Japan", "United States", "Nigeria". These have list pages: Italy, Russia, France, Japan, the United States, Britain, Ireland, Germany, Canada, Spain, Poland, India, China, Australia, Norway, Sweden, Nigeria, Austria, South Africa. Another country is ranked from the books the catalog holds by its authors. | |
| subject | No | A period, theme, region or movement, by name or slug, e.g. "death-mortality", "war-conflict", "victorian-19th-century-literature", "magical-realism", "african-literature". A word from the name is enough when it names one ("gothic"). An unknown subject returns the full list of subjects. | |
| language | No | The original language, e.g. "French". These have list pages: French, Spanish, Russian, German, Chinese, Italian, Japanese, Polish. | |
| difficulty | No | A difficulty band ("easy" under 45 of 100, "moderate" 45 to 64, "challenging" 65 and over), still ranked by literary regard; or "hardest" for the hardest books with high literary regard, ranked by difficulty | |
| author_gender | No | Only books by women, or only books by men |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| list | Yes | The list the books come from | |
| note | No | Present when the list is short, empty, or has no page | |
| books | Yes | The top of the list, in rank order | |
| count | Yes | Number of books returned | |
| filters_applied | Yes | Each filter as it was matched, e.g. country: Japan; only set filters appear |