Need help with booksoup?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

126 Stars 14 Forks MIT License 22 Commits 2 Opened issues


Booksoup allows you to analyse and traverse your downloaded facebook data, including features such as sentiment analysis and message frequency analysis over time.

Services available


Need anything else?

Contributors list

# 497,706
18 commits
# 351,693
3 commits


Booksoup allows you to analyse and traverse your downloaded facebook data, including features such as sentiment analysis and message frequency analysis over time.

Booksoup requires BeautifulSoup4 and TextBlob, and requires matplotlib to run the demo graphs.


Initialise a new instance of the

class, passing in the top-level path of your facebook data folder as an argument.

Basic usage

from booksoup import BookSoup

me = BookSoup("facebook-data")

Get a conversation by name

convo = me.load_conversation("Jane Doe")

Print participants of the conversation


Print messages in the conversation

for message in convo.messages: print(, message.timestamp,, message.content)

Interaction frequency

It's possible to see how often messages are sent in a specific conversation at each hour of the day using

. This returns a dict with each key being an hour in the day, and the corresponding value being the number of messages sent at that time over the history of the conversation. ```python me = BookSoup("facebook-data") convo = me.load_conversation("John Smith")

times = convo.interaction_freq() ```

Using the
code, this can be visualised:

Interaction frequency example

Interaction timeline

It's also possible to view how many times a specific person within a conversation sent messages from the beginning to the last point of the conversation using

. The following example shows how often I sent messages within a group conversation.
me = BookSoup("facebook-data")
convo = me.load_conversation("Lewis, Andrew, Michelle and 4 others")

times = convo.interaction_timeline(

Using the
code, I can visualise in one graph how often everyone in the conversation spoke by building a separate timeline for each person.

Interaction timeline example

Another example below with one friend over a longer timeline:

Single user example


Booksoup can also perform sentiment analysis. Average sentiment for a user in a specific conversation can be calculated using

, or a timeline of average sentiment can also be built using
convo = me.load_conversation("David Grocer")

Print the average sentiment of David Grocer in the conversation

print(convo.avg_sentiment("David Grocer"))

Print the timeline dictionary of my average sentiment in the conversation


Loading a conversation

A conversation can either be loaded using either the title of the conversation (as in all the previous examples) or the numerical ID of the conversation (the filename of the conversation's html file).

convo = me.load_conversation(40)

Specifying interval duration

In all of the timeline examples, the interval can be specified as either

, with the default being
. To switch to daily intervals for timeline operations, set the
argument, e.g
convo = me.load_conversation("David Grocer", interval="day")


Booksoup can extract and categorise event information. This includes title, description, location, timestamp and a 2-element array containing the latitude and longitude of the event if available.

me = BookSoup("facebook-data")

events = me.load_all_events()

Events are organised into attending, maybe, declined and no_reply:

for event in events.attending: print(event.title, event.description, event.location, event.timestamp, event.latlon)

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.