Penguin Random House Rest Services API
Overview
About
The Penguin Random House Rest Services can be used to get data about books, authors and events.Connection
All RHRS requests are secured via BASIC HTTP authentication over HTTPS.Request Type
At this point in time, all requests use the GET method.Content Type
The RHRS API can return data in one of three formats depending on the content type that is supplied as part of the request.- application/xml
- application/json
- image/*
Definitions
- Author
- Any one of a book's contributors including roles such as author, illustrator, or reader.
- Event
- An author event such as a book signing. Event records reference an author and possibly a title as well as specifications of the time and place of the event.
- Title
- A reference to a specific version of a book identified by an ISBN. For example the Hardcover and Paperback versions of a book are considered separate titles.
- Work
- A collection of titles that share the same content identified by a Penguin Random House-specific Work ID. Different formats of a title are collected under the same Work ID.
Method Summary
Authors
- GET /resources/authors - search for authors
- GET /resources/authors/AUTHORID - details for a specific author
Works
- GET /resources/works - search for works
- GET /resources/works/WORKID - details for a specific work
Titles
- GET /resources/titles - search for titles
- GET /resources/title/ISBN - details for a specific title
Events
- GET /resources/authorevents - search for author events
- GET /resources/authorevents/EVENTID - details for a specific author event
Method Details
Authors
GET /resources/authors -- search for authors
GET /resources/authors/AUTHORID -- details for a specific author
Works
GET /resources/works -- search for works
INPUTS
-
start(required) the position of first record to be returned starting with zero
-
max(required) the position of the last record to be returned; passing zero will return all found records
-
expandLevel(required) the level of detail to be returned
0 = no details returned, just links
1 = return links and details -
search(required) text to search for in the title of a work or the author's name
Examples:
'Grisham' finds 'The Confession by John Grisham' as well as other Grisham titles
'Inheritance' finds both 'Inheritance' by Paolini and 'The Voysey Inheritance' by Mamet
OUTPUTS
The response is a single work element with each result represented by a nested work element.USAGE
bash
# Curl example
curl -X GET -v --basic -u "testuser:testpassword" "https://reststop.randomhouse.com/resources/works?keyword=Grisham%20Christmas"php
// PHP example
$ch = curl.init();curl_setopt($ch, CURLOPT_URL, "https://reststop.randomhouse.com/resources/works?keyword=Grisham%20Christmas");
curl_setopt($ch, CURLOPT_HEADER, FALSE);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "testuser:testpassword");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
$api_return = curl exec($ch);
echo $api_return;
curl close($ch);
?>
java
// Java example
import java.io.BufferedReader;import java.io.OutputStreamWriter;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.Authenticator;
import java.net.PasswordAuthentication;
import java.net.URL;
import java.net.HttpUrlConnection;
public class Api {
static final String kuser = "testuser";
static final String kpass = "testpassword";
static class RHAuthenticator extends Authenticator {
public PasswordAuthentication getPasswordAuthentication() {
return (new PasswordAuthentication(kuser, kpass.toCharArray()));
}
}
public static void main(String[] args) {
Authenticator.setDefault(new RHAuthenticator());
URL url = new URL("https://reststop.randomhouse.com/resources/works?keyword=Grisham%20Christmas");
HttpURLConnection con = (HttpURLConnection) url.openConnection();
InputStream is = con.getInputStream();
BufferedReader reader = new BufferedReader(new InputStreamReader(is));
String str
while((str = reader.readLine()) != null) {
System.out.println(str);
}
reader.close();
}
}
GET /resources/works/WORKID -- details for a specific work
INPUTS
-
workid(required) Penguin Random House work identifier
example value: 72148
OUTPUTS
The response is a single work element composed as follows. All of the fields that say they contain HTML snippets are optional blurbs that can contain large text including carriage returns.-
authorweblist of contributors formatted for display (proper order, proper case)
example value: GRISHAM, JOHN
-
onsaledatethe date that the title was released to the public. Penguin Random House always releases on a Tuesday.
example value: 2001-11-06T00:00:00-05:00
-
series?
example value: John Grisham
-
titleauthA concatenation of the title and author separated by a semi-colon.
example values: Skipping Christmas : John Grisham
-
titleSubtitleAuthA concatenation of the title, subtitle and author separated by semi-colons.
example value: Skipping Christmas : : John Grisham
-
titleshorta version of the title limited to 30 characters, all upper case with articles at the back; suitable for sorting or narrow displays
example value: SKIPPING CHRISTMAS
-
titlewebthe title of the book in proper case with leading articles; suitable for display
example value: Skipping Christmas
-
workidan integer that identifies this work uniquely; versions of the same work in different formats will share the same work ID
example value: 72148
USAGE
bash
# Curl example
curl -X GET -v --basic -u "testuser:testpassword" "https://reststop.randomhouse.com/resources/works/72148/"php
// PHP example
$ch = curl.init();curl_setopt($ch, CURLOPT_URL, "https://reststop.randomhouse.com/resources/works/72148/");
curl_setopt($ch, CURLOPT_HEADER, FALSE);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "testuser:testpassword");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
$api_return = curl exec($ch);
echo $api_return;
curl close($ch);
?>
java
// Java example
import java.io.BufferedReader;import java.io.OutputStreamWriter;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.Authenticator;
import java.net.PasswordAuthentication;
import java.net.URL;
import java.net.HttpUrlConnection;
public class Api {
static final String kuser = "testuser";
static final String kpass = "testpassword";
static class RHAuthenticator extends Authenticator {
public PasswordAuthentication getPasswordAuthentication() {
return (new PasswordAuthentication(kuser, kpass.toCharArray()));
}
}
public static void main(String[] args) {
Authenticator.setDefault(new RHAuthenticator());
URL url = new URL("https://reststop.randomhouse.com/resources/works/72148/");
HttpURLConnection con = (HttpURLConnection) url.openConnection();
InputStream is = con.getInputStream();
BufferedReader reader = new BufferedReader(new InputStreamReader(is));
String str
while((str = reader.readLine()) != null) {
System.out.println(str);
}
reader.close();
}
}
Titles
GET /resources/titles -- search for titles
INPUTS
-
start(required) the position of first record to be returned starting with zero
-
max(required) the position of the last record to be returned; passing zero will return all found records
-
expandLevel(required) the level of detail to be returned
0 = no details returned, just links
1 = return links and details -
onsaleStart(optional) MM/dd/yyyy limit results to just those titles that went on sale on or after this date. On-sale dates are always Tuesdays.
Examples:
'01/18/2011' -
onsaleEnd(optional) MM/dd/yyyy limit results to just those titles that went on sale on or after this date. On-sale dates are always Tuesdays.
Examples:
'02/18/2011' -
ageRangeCodes(optional) one or more age range codes separated by commas. Each code is 4 or 5 position alpha-numeric.
Examples:
'0512' -- ages five to twelve
'10UP,0812' -- ages 10 and up or eight to twelve -
division(optional) one or more division codes separated by commas. Each code is a 2 position alpha-numeric.
Examples:
'70' -- Penguin Random House Group
'72' -- RH Childrens Books -
imprint(optional) one or more imprint codes separated by commas. Each code is a 2 position alpha-numeric.
Examples:
'1A' -- Bantam
'K1' -- Knopf Books for Young Readers -
format(optional) one or more format codes separated by commas. Each code is a 2 position alpha-numeric.
Examples:
'HC' -- Hardcover
'MM' -- Paperback
'EL' -- eBook -
authorid(optional) limit the results to just those titles for whom the specified author is listed as a contributor. If you don't know this number, you should first do a author search and extract the authorid. A zero is treated as a null.
Examples:
3446 -
workid(optional) limit the results to just those titles with the same work ID. This can be used to pull up all the different formats of a previously found title.
Examples:
19309 -
workFamily(optional) a list of single position alpha-numeric codes used to modify a 'workid' search to limit the types of results that are returned. If you don't know what this means, then you probably want 'P' which should represent ISBNs with the same content in different formats.
Examples:
P (default)
R
P,R -
search(optional) exact match of a word in the keyword field, a concatenation of the basic metadata plus some blurb text.
Examples:
'Grisham' finds 'The Confession by John Grisham'
'DaVinci' finds both 'The DaVinci Code' and 'Laughing Matters: Learning to Laugh when Life Stinks' because DaVinci is mentioned in the flap copy. -
theme(optional) case insensitive match of all or a portion of one of the theme categories assigned to a title.
Examples:
'friend' finds titles tagged with the theme 'Friendship'
'roma' finds titles tagged with the theme 'Love & Romance'.
OUTPUTS
The response is a single titles element with each result represented by a nested title element.USAGE
bash
# Curl example
curl -X GET -v --basic -u "testuser:testpassword" "https://reststop.randomhouse.com/resources/titles?keyword=Grisham%20Christmas"php
// PHP example
$ch = curl.init();curl_setopt($ch, CURLOPT_URL, "https://reststop.randomhouse.com/resources/titles?keyword=Grisham%20Christmas");
curl_setopt($ch, CURLOPT_HEADER, FALSE);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "testuser:testpassword");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
$api_return = curl exec($ch);
echo $api_return;
curl close($ch);
?>
java
// Java example
import java.io.BufferedReader;import java.io.OutputStreamWriter;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.Authenticator;
import java.net.PasswordAuthentication;
import java.net.URL;
import java.net.HttpUrlConnection;
public class Api {
static final String kuser = "testuser";
static final String kpass = "testpassword";
static class RHAuthenticator extends Authenticator {
public PasswordAuthentication getPasswordAuthentication() {
return (new PasswordAuthentication(kuser, kpass.toCharArray()));
}
}
public static void main(String[] args) {
Authenticator.setDefault(new RHAuthenticator());
URL url = new URL("https://reststop.randomhouse.com/resources/titles?keyword=Grisham%20Christmas");
HttpURLConnection con = (HttpURLConnection) url.openConnection();
InputStream is = con.getInputStream();
BufferedReader reader = new BufferedReader(new InputStreamReader(is));
String str
while((str = reader.readLine()) != null) {
System.out.println(str);
}
reader.close();
}
}
GET /resources/titles/ISBN -- details for a specific title
INPUTS
-
isbn(required) The 13-digit integer identifying a specific title. May not contain hyphens and does not accept the old 10-digit variety. This is the same as the 'ean' value returned in the title detail. If you don't know the ISBN, you should first do a title search and extract the ean.
example value: 9781400079148
OUTPUTS
The response is a single title element composed as follows. All of the fields that say they contain HTML snippets are optional blurbs that can contain large text including carriage returns.-
acmartflap(optional) HTML snippet that contains the Academic Marketing text
-
agerange(optional) Description of the age range for which this title is appropriate
-
agerangecode(optional) four or five position code that indicates the age range for which this titleis appropriate
-
agerange(optional) Description of the age range for which this title is appropriate
-
authorprimary contributor's name formatted as "LAST, FIRST" in all upper case
example value: BROWN, DAN
-
authorslist of nested <authorId> elements which are the Penguin Random House unique internal identifiers for authors
example value: 11178
-
authorbio(optional) HTML snippet that contains text about the contributors
-
authorweblist of contributors formatted for display (proper order, proper case)
example values:
Dan Brown
Janet Bode and Stan Mack -
contributorfirst1primary contributor's first name in proper case
example value: Dan
-
contributorlast1primary contributor's last name in proper case
example value: Brown
-
divisionname of the division that published the book
example value: Knopf
-
excerpt(optional) HTML snippet taken from the content of the book
-
flapcopy(optional) HTML snippet of the content about the book taken from the flaps; does not repeat the author bio
-
formatCodea code representing the book's format
AU Audio BR Board BX Boxed Set CS Cassette CD Compact Disc DG Digest DN Audio Download EL eBook HC Hardcover MM Paperback MG Multi Media NM New Media NT Non-traditional book MH Package TR Trade Paperback TW Hardcover Library Binding VI Video NA Not Available
-
formatnamedescription of the book's format
example value: Hardcover
-
imprintthe name of the imprint that published the book
example value: Anchor
-
isbn13-digit ISBN without hyphens (aka EAN)
example value: 9781400079148
-
isbn1010-digit ISBN without hyphens
example value: 1400079144
-
isbn10hyphenatedhyphenated 10-digit ISBN
example value: 1-4000-7914-4
-
isbn13hyphenatedhyphenated 13-digit ISBN
example value: 978-1-4000-7914-8
-
jacketquotes(optional) HTML snippet of quotes taken from the back cover or jacket
-
keyworda concatenation of various metadata text including title, author, division, imprint, format, category, various ISBNs, and the flap copy. Since this includes the flap copy, it may include HTML markup.
-
onsaledatethe date that the title was released to the public. Penguin Random House always releases on a Tuesday.
example value: 10/19/2010
-
pagesthe number of pages in the book
example value: 224
-
pricecanadaa decimal number representing the Canadian retail price
example value: 23.95
-
priceusaa decimal number representing the US retail price
example value: 16.95
-
rgabout(optional) HTML snippet that contains the Reading Group introduction
-
rgauthbio(optional) HTML snippet that contains the Reading Group author bio
-
rgcopy(optional) HTML snippet that contains the Reading Group text about the book
-
rgdiscussion(optional) HTML snippet that contains the Reading Group questions for discussion
-
salestatus
AA Active Assortment CA Canceled EL eBooks HB Hot Bklst/Initials HR Hot Bklst/ReOrders HT Hot Title IN Initial IO Import to Order IP In Print ND *Do not Use! NR No Reprints Sched. OP Out of Print OS Out of Stock Indef. PP Postponed RI Re-Issue RM Remainder RR Rights Reverted SC Scrapped SR Short Run Title XD No Longer Dist by RH IA Initial Assortment IR Initial Reorder NO Network-only
-
subjectcategory1A BISAC Subject Category code
example value: FIC000000
-
subjectcategorydescription1The text description of code in subjectcategory1
example value: Fiction - General
-
themes(optional) a list of theme categories
example value: Love & Romance
example value: Death, Dying & Grief -
titleAuthIsbnconcatenation of title, author and various ISBNs
example value: Unbroken : Laura Hillenbrand : 0679603751 : 0-679-60375-1 : 9780679603757 : 978-0-679-60375-7
-
titleSubtitleAuthIsbnconcatenation of title, subtitle, author and various ISBNs
example value: Unbroken : A World War II Story of Survival, Resilience, and Redemption : Laura Hillenbrand : 0679603751 : 0-679-60375-1 : 9780679603757 : 978-0-679-60375-7
-
titleshorta version of the title limited to 30 characters, all upper case with articles at the back; suitable for sorting or narrow displays
example value: LOST SYMBOL, THE
-
titlewebthe title of the book in proper case with leading articles; suitable for display
example value: The Lost Symbol
-
workidan integer that identifies this work uniquely; versions of the same work in different formats will share the same work ID
example value: 19314
USAGE
bash
# Curl example
curl -X GET -v --basic -u "testuser:testpassword" "https://reststop.randomhouse.com/resources/titles/9781400079148/"php
// PHP example
$ch = curl.init();curl_setopt($ch, CURLOPT_URL, "https://reststop.randomhouse.com/resources/titles/9781400079148/");
curl_setopt($ch, CURLOPT_HEADER, FALSE);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "testuser:testpassword");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
$api_return = curl exec($ch);
echo $api_return;
curl close($ch);
?>
java
// Java example
import java.io.BufferedReader;import java.io.OutputStreamWriter;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.Authenticator;
import java.net.PasswordAuthentication;
import java.net.URL;
import java.net.HttpUrlConnection;
public class Api {
static final String kuser = "testuser";
static final String kpass = "testpassword";
static class RHAuthenticator extends Authenticator {
public PasswordAuthentication getPasswordAuthentication() {
return (new PasswordAuthentication(kuser, kpass.toCharArray()));
}
}
public static void main(String[] args) {
Authenticator.setDefault(new RHAuthenticator());
URL url = new URL("https://reststop.randomhouse.com/resources/titles/9781400079148/");
HttpURLConnection con = (HttpURLConnection) url.openConnection();
InputStream is = con.getInputStream();
BufferedReader reader = new BufferedReader(new InputStreamReader(is));
String str
while((str = reader.readLine()) != null) {
System.out.println(str);
}
reader.close();
}
}