API

Introduction

The Readgeek API allows developers to include personal book recommendations to their own webservice.

RESTful API

Access is made through GET, POST, PATCH and DELETE request methods, in case of PATCH with a JSON request body

To be able to get recommendations a user user needs to be created and ratings of prior read books need to be saved.

Identification

To gain access to the API identification is needed. You need to create a regular account on Readgeek and ask via email for permission to use the API.

After permission is granted use Basic Access Authentication to verify your identity in every API call. Make sure you always use HTTPS to not compromise your login data.

Response format

All responses are text strings in Javascript Object Notation (JSON)

Example use case

Let's say you have the books a client bought in the past stored . And for some books you also got a response in the form of a star rating system. Now you would like to be able to make matching recommendations to that client.

In a first step create a user and store the Readgeek User ID for the client.

Now transmit all bought books and books with ratings. Use taste_test to have the client rate a couple more books, including the ones they bought.

And already you are able to ask the API for book recommendations and predictions on specific books for your client.

Creating a user

This is done via a POST-request to:
https://www.readgeek.com/api/user
and returns

• user id

The new user has set 'english' as a default language. That can be changed by updating the user.

Getting user statistics and requesting books for subsequent rating

That is done via a GET-request to:

https://www.readgeek.com/api/user/21

21 stands examplary for the user-id. Several URL parameters can be added:

statistics=user

requesting statistical information about the user as

• registration date
• number of rated books
• average of all ratings
• number of bookmarked, bought, books not interested in as well as currently read books
• prior stored spoken languages
• prior stored spoken languages

similarity_userid[]=6&similarity_userid[]=10

requesting the similarity of litarary taste to other users this returns a value in between 0 for no compatibility till 1 for absolute soulmates and an empty value where due to too few mutual books the similarity can't be computed.

books=[bought, bookmarked, rated, not_interested, currently_reading]

if 'books' get requested, the next two are required.

books[offset] = 0
books[limit] = 10

request books of a certain criteria of that user, use offset and limit to give the range of the books ordered by the date of requested book type, latest first. The maximum of simultanious returned books is 50 at a time. Where several book types are requested at the same time, ordered by the earliest date.

returns all books by the user including

• ISBN13
• rating
• date of when the book was bought, rated etc.

prediction[book][]=ISBN:978-1-5420-4752-4&prediction[book][]=ISBN:3596298415

returns a prediction how the user would rate a title including

• the reqested identifyer
• formatted ISBN13
• prediction

If no prediction can be calculated, the value for prediction is left empty.

Invalid ISBN are returned in a sperate array without any further error message.

recommendations[books]=30

returns a set of books with high predictions according on the users ratings, genres, authors and many other data points

returns an array of titles with

• ISBN13
• title in first users language, if not available in second language and so on
• author in first users language, if not available in second language and so on
• prediction of the users rating - a value between of 0 for didn't like it at all till 10 for loved it
• cover - a link to a thumbnail of max 175*300 pixel
• main genres
• a description of the book, most likely the blurb by the publisher

taste_test=6

in order to get book ratings this parameter requests books a user might have read (based on what was rated before) Those books might be rated and send to readgeek by updating the user for better predictions and recommendations. The suggestions are based on the rating history, first language and otherwise marked books i.e. which books where bought in the past.

returns an array of books with

• title
• title language in ISO 639-1 format
• author
• author language
• a link to the cover with dimenstions of 175*300 pixel
• one ISBN13 of possibly several available (we are trying to return one in the language of the api user)
• the readgeek id since not all books have ISBNs

All data requests can also be combined

Example
https://www.readgeek.com/api/user/21?data=user&similarity_userid[]=6&similarity_userid[]=10&taste_test=6&prediction[book][]=ISBN:3596298415&books[]=bought&books[]=rated&books[offset]=0&books[limit]=10

Updating a user and their books

That is done via a PATCH-request to:

https://www.readgeek.com/api/user/21

21 stands examplary for the user-id. Several parameters can be added as a JSON request body:

{
  "languages": {
    "0": "nl",
    "1": "en"
  }
}

this parameter overwrite prior stored languages of the user and stores new ones. The order of the key-value pairs should represend in what language the user wants to read. Here - first language Dutch, if not available return the English title/blurb.

• language codes must be in ISO 639-1 format

{
  "books": {
    "isbn:9789029089975": {
      "rated": 9.5,
      "date_rated": "2017-05-14",
      "date_bought": "2015-01-31",
      "date_bookmarked": "2014-11-04"
    },
    "isbn:978-0-316-06792-8": {
      "date_not_interested": "NULL"
    },
    "isbn:022627618X": {
      "date_bought": "2017-03-14",
      "date_currently_reading": "2017-05-14"
    },
    "editionid:15597303": {
      "rated": 3
    },
    "editionid:13895214": {
      "rated": "NULL"
    }
  }
}

books stores information about a user-book relation. 'rated' represents a value of how much did the user like that book in between of 0 (worst) to 10 (best)

• book identifier will usually be ISBN:97...25. If the taste_test functionality is used, the readgeek-id is provided to be used instead, since not all books have an ISBN. An ISBN is still provided where available
• rated must be a number with up to one digit after the decimal point or NULL to either delete the rating or:
• also rate all books with NULL in the taste_test the user didn't read. Only by rating them with NULL the user won't be asked for some time to that titles
• date format must be of YYYY-MM-DD or NULL to delete the date
• 'date_bought', 'date_bookmarked', 'date_currently_reading' and 'date_not_interested' helps to determine what the user should be presented for rating and what genres the user preferes
• 'date_rated' helps to determine what books to suggest next depending to the order of read books

Invalid ISBN are returned in a sperate array without any further error message.

{
  "returns": {
    "taste_test": 6,
    "statistics": "user"
  }
}

Both parameters reqest the same data as in the GET request.

Deleting a user

https://www.readgeek.com/api/user/21

21 stands examplary for the user-id. Sending this as a DELETE request will delete the user and all thier book information.