The New York Times maintains a number of APIs for developers that need a programmatic way to access their content. Among these is the Books API, which provides access to the best seller lists.
This document describes an R implementation to access it.
Each function is relegated to its own R file in the R directory. Use source to import them.
Initiation
First, the user must obtain an NYT developer key. I have stored mine in a file ignored by Git called config.R in the variable API_KEY:
“Connect” to the API by inputting the key into the NewYorkTimesBooks object:
Note that there is no real connecting going on here. The NewYorkTimesBooks object is merely a conveniant way to store two pieces of information required by the rest of the methods: the API key, as well as the API’s base URL: https://api.nytimes.com/svc/books/v3.
Bestseller Lists
The paper maintains a number of best seller lists, e.g., hardcover non-fiction. Any user’s first step must be to determine which best seller list they are interested in.
This function enumerates these lists:
## list_name display_name
## 1 Combined Print and E-Book Fiction Combined Print & E-Book Fiction
## 2 Combined Print and E-Book Nonfiction Combined Print & E-Book Nonfiction
## 3 Hardcover Fiction Hardcover Fiction
## 4 Hardcover Nonfiction Hardcover Nonfiction
## 5 Trade Fiction Paperback Paperback Trade Fiction
## 6 Mass Market Paperback Paperback Mass-Market Fiction
## list_name_encoded oldest_published_date
## 1 combined-print-and-e-book-fiction 2011-02-13
## 2 combined-print-and-e-book-nonfiction 2011-02-13
## 3 hardcover-fiction 2008-06-08
## 4 hardcover-nonfiction 2008-06-08
## 5 trade-fiction-paperback 2008-06-08
## 6 mass-market-paperback 2008-06-08
## newest_published_date updated
## 1 2018-11-04 WEEKLY
## 2 2018-11-04 WEEKLY
## 3 2018-11-04 WEEKLY
## 4 2018-11-04 WEEKLY
## 5 2018-11-04 WEEKLY
## 6 2017-01-29 WEEKLYOf particular importance is the column list_name_encoded. It contains how each list is represented in the API; e.g., the ‘Combined Print and E-Book Fiction’ is represented as combined-print-and-e-book-fiction.
Retrieving a List
One a user knows the encoding they want to investigate, they can download the list data with the get_bestseller_list() function.
Note that this function accepts a number of parameters; the nyt object and list_name are required. Optional arguments are documented in the function script, including weeks_on_list, isbn, and others.
Parameters are imputed to the function via a named list:
source('./R/get_bestseller_list.R')
p <- list(published_date='2018-10-01')
print_ebook_list <- get_bestseller_list(nyt, 'combined-print-and-e-book-fiction',
parameters=p)
str(print_ebook_list)## 'data.frame': 15 obs. of 26 variables:
## $ list_name : chr "Combined Print and E-Book Fiction" "Combined Print and E-Book Fiction" "Combined Print and E-Book Fiction" "Combined Print and E-Book Fiction" ...
## $ display_name : chr "Combined Print & E-Book Fiction" "Combined Print & E-Book Fiction" "Combined Print & E-Book Fiction" "Combined Print & E-Book Fiction" ...
## $ bestsellers_date : chr "2018-09-22" "2018-09-22" "2018-09-22" "2018-09-22" ...
## $ published_date : chr "2018-10-07" "2018-10-07" "2018-10-07" "2018-10-07" ...
## $ rank : int 1 2 3 4 5 6 7 8 9 10 ...
## $ rank_last_week : int 0 0 11 1 3 0 0 14 6 7 ...
## $ weeks_on_list : int 1 1 30 2 15 1 1 2 7 3 ...
## $ asterisk : int 0 0 0 0 0 0 0 0 0 0 ...
## $ dagger : int 0 0 0 0 0 0 0 0 0 0 ...
## $ amazon_product_url : chr "https://www.amazon.com/Lethal-White-Cormoran-Strike-Novel-ebook/dp/B07F9N27MH?tag=NYTBS-20" "https://www.amazon.com/Times-Convert-Novel-Deborah-Harkness/dp/0399564519?tag=NYTBS-20" "https://www.amazon.com/Origin-Novel-Dan-Brown-ebook/dp/B01LY7FD0D?tag=NYTBS-20" "https://www.amazon.com/Juror-3-James-Patterson/dp/0316474126?tag=NYTBS-20" ...
## $ isbn10s :List of 15
## ..$ : chr "" "0316422738" "0316422746" "1549119842"
## ..$ : chr "0399564519" "0525641467"
## ..$ : chr "0385514239" "0385542690" "0525434305" "0739319302" ...
## ..$ : chr "0316474126" "0316419850" "0316470066"
## ..$ : chr "0385536976" "0345803787" "0385536984" "1782393315" ...
## ..$ : chr "1488096821" "1335474609" "1335005900"
## ..$ : chr "006285514X" "0062855131"
## ..$ : chr "0735219095" "0735219117" "0525640371"
## ..$ : chr "0804172064"
## ..$ : chr "0062797158" "0062797166" "006287067X"
## ..$ : chr "1455572160" "1455572128" "1455572152"
## ..$ : chr "1250161568" "1250161584" "1536696919" "197860050X" ...
## ..$ : chr "0735219060" "0735219079"
## ..$ : chr "0062497782" "0062878646" "0062497790" "0062658239" ...
## ..$ : chr "0385542232" "052543237X" "0385542240"
## $ isbn13s :List of 15
## ..$ : chr "" "9780316422734" "9780316422741" "9781549119842"
## ..$ : chr "9780399564512" "9780525641469"
## ..$ : chr "9780385514231" "9780385542692" "9780525434306" "9780739319307" ...
## ..$ : chr "9780316474122" "9780316419857" "9780316470063"
## ..$ : chr "9780385536974" "9780345803788" "9780385536981" "9781782393313" ...
## ..$ : chr "9781488096822" "9781335474605" "9781335005908"
## ..$ : chr "9780062855145" "9780062855138"
## ..$ : chr "9780735219090" "9780735219113" "9780525640370"
## ..$ : chr "9780804172066"
## ..$ : chr "9780062797155" "9780062797162" "9780062870674"
## ..$ : chr "9781455572168" "9781455572120" "9781455572151"
## ..$ : chr "9781250161567" "9781250161581" "9781536696912" "9781978600508" ...
## ..$ : chr "9780735219069" "9780735219076"
## ..$ : chr "9780062497789" "9780062878649" "9780062497796" "9780062658234" ...
## ..$ : chr "9780385542234" "9780525432371" "9780385542241"
## $ book_title : chr "LETHAL WHITE" "TIME'S CONVERT" "ORIGIN" "JUROR #3" ...
## $ book_desc : chr "The fourth book in the Cormoran Strike series. Detectives Strike and Ellacott investigate a crime a young man m"| __truncated__ "During his lover's journey to immortality, a vampire's past returns to haunt them both." "After reconnecting with one of his first students, who is now a billionaire futurist, symbology professor Rober"| __truncated__ "Ruby Bozarth defends a college football star charged in a felony case complicated by a second murder." ...
## $ author : chr "Robert Galbraith" "Deborah Harkness" "Dan Brown" "James Patterson and Nancy Allen" ...
## $ contributor : chr "by Robert Galbraith" "by Deborah Harkness" "by Dan Brown" "by James Patterson and Nancy Allen" ...
## $ contributor_note : chr "" "" "" "" ...
## $ price : int 0 0 0 0 0 0 0 0 0 0 ...
## $ age_group : chr "" "" "" "" ...
## $ publisher : chr "Mulholland/Little, Brown" "Penguin" "Doubleday" "Little, Brown" ...
## $ primary_isbn13 : chr "9780316422741" "9780399564529" "9780385542692" "9780316474122" ...
## $ primary_isbn10 : chr "0316422746" "None" "0385542690" "0316474126" ...
## $ book_review_link : chr "" "" "" "" ...
## $ first_chapter_link : chr "" "" "" "" ...
## $ sunday_review_link : chr "" "" "" "" ...
## $ article_chapter_link: chr "" "" "" "" ...Best Seller History of a Book
What if you wanted to retrieve the historical best seller of a particular item or group of items? This is possible with the get_bestseller_history() function. Unlike above, it has no required arguments besides the nyt object, but it accepts a wide variety of parameters, including author, title, publisher, etc., as documented in the function script.
source('./R/get_bestseller_history.R')
p <- list(author='Stephen King')
stephen_king_history <- get_bestseller_history(nyt, parameters=p)
str(stephen_king_history)## 'data.frame': 20 obs. of 15 variables:
## $ title : chr "11/22/63" "A FACE IN THE CROWD" "A GOOD MARRIAGE" "AMERICAN VAMPIRE, VOL. 1" ...
## $ description : chr "An English teacher travels back to 1958 by way of a time portal in a Maine diner. His assignment: Stop Lee Harvey Oswald." "An elderly widower watches baseballt to distract himself from his wife's death, but figures from his past appea"| __truncated__ "An unsuspecting accountant's wife makes a disturbing discovery; first published in 2010, now a movie." "This series, about a new species of vampire that does not have the traditional weakness, shifts to Las Vegas in"| __truncated__ ...
## $ contributor : chr "by Stephen King" "by Stephen King and Stewart O'Nan" "by Stephen King" "by Scott Snyder and Stephen King" ...
## $ author : chr "Stephen King" "Stephen King and Stewart O'Nan" "Stephen King" "Scott Snyder and Stephen King" ...
## $ contributor_note : chr "" "" "" "" ...
## $ price : num 0 0 0 20 25 ...
## $ age_group : chr "" "" "" "" ...
## $ publisher : chr "Pocket Books" "Scribner" "Scribner" "DC Comics" ...
## $ ranks_history :List of 20
## ..$ :'data.frame': 0 obs. of 0 variables
## ..$ :'data.frame': 0 obs. of 0 variables
## ..$ :'data.frame': 0 obs. of 0 variables
## ..$ :'data.frame': 0 obs. of 0 variables
## ..$ :'data.frame': 0 obs. of 0 variables
## ..$ :'data.frame': 0 obs. of 0 variables
## ..$ :'data.frame': 0 obs. of 0 variables
## ..$ :'data.frame': 0 obs. of 0 variables
## ..$ :'data.frame': 0 obs. of 0 variables
## ..$ :'data.frame': 0 obs. of 0 variables
## ..$ :'data.frame': 0 obs. of 0 variables
## ..$ :'data.frame': 5 obs. of 11 variables:
## .. ..$ primary_isbn10 : chr "1451698860" "1451698860" "1451698860" "1451698860" ...
## .. ..$ primary_isbn13 : chr "9781451698862" "9781451698862" "9781451698862" "9781451698862" ...
## .. ..$ rank : int 14 9 9 10 14
## .. ..$ list_name : chr "Mass Market Paperback" "Mass Market Paperback" "Mass Market Paperback" "Mass Market Paperback" ...
## .. ..$ display_name : chr "Paperback Mass-Market Fiction" "Paperback Mass-Market Fiction" "Paperback Mass-Market Fiction" "Paperback Mass-Market Fiction" ...
## .. ..$ published_date : chr "2016-09-11" "2016-09-04" "2016-08-28" "2016-08-21" ...
## .. ..$ bestsellers_date: chr "2016-08-27" "2016-08-20" "2016-08-13" "2016-08-06" ...
## .. ..$ weeks_on_list : int 0 3 2 1 0
## .. ..$ ranks_last_week : logi NA NA NA NA NA
## .. ..$ asterisk : int 0 1 0 0 0
## .. ..$ dagger : int 0 0 0 0 0
## ..$ :'data.frame': 0 obs. of 0 variables
## ..$ :'data.frame': 0 obs. of 0 variables
## ..$ :'data.frame': 0 obs. of 0 variables
## ..$ :'data.frame': 11 obs. of 11 variables:
## .. ..$ primary_isbn10 : chr "1501129740" "1501129740" "1501129740" "1501129740" ...
## .. ..$ primary_isbn13 : chr "9781501129742" "9781501129742" "9781501129742" "9781501129742" ...
## .. ..$ rank : int 18 16 10 9 6 12 5 13 6 4 ...
## .. ..$ list_name : chr "Hardcover Fiction" "Hardcover Fiction" "Hardcover Fiction" "Hardcover Fiction" ...
## .. ..$ display_name : chr "Hardcover Fiction" "Hardcover Fiction" "Hardcover Fiction" "Hardcover Fiction" ...
## .. ..$ published_date : chr "2016-08-28" "2016-08-21" "2016-08-14" "2016-08-07" ...
## .. ..$ bestsellers_date: chr "2016-08-13" "2016-08-06" "2016-07-30" "2016-07-23" ...
## .. ..$ weeks_on_list : int 0 9 8 7 6 6 5 5 4 4 ...
## .. ..$ ranks_last_week : logi NA NA NA NA NA NA ...
## .. ..$ asterisk : int 0 1 0 0 0 0 0 0 0 0 ...
## .. ..$ dagger : int 0 0 0 0 0 0 0 0 0 0 ...
## ..$ :'data.frame': 0 obs. of 0 variables
## ..$ :'data.frame': 0 obs. of 0 variables
## ..$ :'data.frame': 0 obs. of 0 variables
## ..$ :'data.frame': 4 obs. of 11 variables:
## .. ..$ primary_isbn10 : chr "1587676109" "1587676109" "None" "1587676109"
## .. ..$ primary_isbn13 : chr "9781587676109" "9781587676109" "A00B06XC9VTBV" "9781587676109"
## .. ..$ rank : int 13 14 4 7
## .. ..$ list_name : chr "Hardcover Fiction" "Hardcover Fiction" "Combined Print and E-Book Fiction" "Hardcover Fiction"
## .. ..$ display_name : chr "Hardcover Fiction" "Hardcover Fiction" "Combined Print & E-Book Fiction" "Hardcover Fiction"
## .. ..$ published_date : chr "2017-06-18" "2017-06-11" "2017-06-04" "2017-06-04"
## .. ..$ bestsellers_date: chr "2017-06-03" "2017-05-27" "2017-05-20" "2017-05-20"
## .. ..$ weeks_on_list : int 3 2 1 1
## .. ..$ ranks_last_week : logi NA NA NA NA
## .. ..$ asterisk : int 0 1 0 0
## .. ..$ dagger : int 0 0 0 0
## $ isbn10s :List of 20
## ..$ : chr "1451627289" "1451627297" "030795143X" "1594135592" ...
## ..$ : chr "1476713340"
## ..$ : chr "150110442X"
## ..$ : chr "1401229743"
## ..$ : chr "1401228305"
## ..$ : chr "1451678622"
## ..$ : chr "1451608217" "1587672286"
## ..$ : chr "1416524517"
## ..$ : chr "0451160444"
## ..$ : chr "1439170983"
## ..$ : chr "0451167538"
## ..$ : chr "1476727651" "147672766X" "1410462447" "1451698852" ...
## ..$ : chr "0451177096"
## ..$ : chr "074343627X"
## ..$ : chr "1416552960"
## ..$ : chr "1501129740" "1501134159"
## ..$ : chr "0743457358"
## ..$ : chr "1501100076" "1501100130" "1410479501" "1501100122"
## ..$ : chr "1439192561" "1451650604" "143919260X"
## ..$ : chr "1587676109"
## $ isbn13s :List of 20
## ..$ : chr "9781451627282" "9781451627299" "9780307951434" "9781594135590" ...
## ..$ : chr "9781476713342"
## ..$ : chr "9781501104428"
## ..$ : chr "9781401229740"
## ..$ : chr "9781401228309"
## ..$ : chr "9781451678628"
## ..$ : chr "9781451608212" "9781587672286"
## ..$ : chr "9781416524519"
## ..$ : chr "9780451160447"
## ..$ : chr "9781439170984"
## ..$ : chr "9780451167538"
## ..$ : chr "9781476727653" "9781476727660" "9781410462442" "9781451698855" ...
## ..$ : chr "9780451177094"
## ..$ : chr "9780743436274"
## ..$ : chr "9781416552963"
## ..$ : chr "9781501129742" "9781501134159"
## ..$ : chr "9780743457354"
## ..$ : chr "9781501100079" "9781501100130" "9781410479501" "9781501100123"
## ..$ : chr "9781439192566" "9781451650600" "9781439192603"
## ..$ : chr "9781587676109"
## $ book_review_link : chr "https://www.nytimes.com/2011/10/31/books/stephen-kings-11-23-63-review.html" "" "" "" ...
## $ first_chapter_link : chr "" "" "" "" ...
## $ sunday_review_link : chr "https://www.nytimes.com/2011/11/13/books/review/11-22-63-by-stephen-king-book-review.html" "" "" "" ...
## $ article_chapter_link: chr "" "" "" "" ...Retrieve Best Seller Reviews
Users can retrieve an index of reviews via get_bestseller_reviews(). This function requires only the nyt object, but accepts a few parameters to help locate specific works: isbn, title, or author.
source('./R/get_bestseller_reviews.R')
p <- list(author='Stephen King', title='11/22/63')
reviews <- get_bestseller_reviews(nyt, parameters=p)
str(reviews)## 'data.frame': 2 obs. of 7 variables:
## $ url : chr "http://www.nytimes.com/2011/11/13/books/review/11-22-63-by-stephen-king-book-review.html" "http://www.nytimes.com/2011/10/31/books/stephen-kings-11-23-63-review.html"
## $ publication_dt: chr "2011-11-13" "2011-10-31"
## $ byline : chr "ERROL MORRIS" "JANET MASLIN"
## $ book_title : chr "11/22/63" "11/22/63"
## $ book_author : chr "Stephen King" "Stephen King"
## $ summary : chr "Stephen King’s time traveler tries to undo some painful history." "Stephen King’s latest novel, “11/22/63,” tells of a schoolteacher who travels back to 1958 to alter history, an"| __truncated__
## $ isbn13 :List of 2
## ..$ : chr "9780307951434" "9780606351461" "9781442344280" "9781442344303" ...
## ..$ : chr "9780307951434" "9780606351461" "9781442344280" "9781442344303" ...