API improvements
October 31, 2007
I’ve added some significant improvements to the BookMooch API, which you can find at http://bookmooch.com/api/
These are provided for programmers who want to integrate their web sites with BookMooch, or provide functionality that BookMooch doesn’t offer.
New API functions
* amazon_add: add the given ASINs from Amazon into the BookMooch database.
* mooch: mooch the given ASIN from the specified user requesting that the book be sent to the specified postal address.
Improved API functions
* A new inc= parameter to asin/pending/userids lets you specify exactly which fields you want returned in the XML response. This greatly reduces the size of the XML response document, lowering the amount of memory you need to parse it, and decreasing latency.
* moochable now has a new option to return the userids of the people who are have the book to send
* asin now includes BookMooch recommended books for that book
API Overview
I’ve written an API Overview to help you get started:
All the API calls support XML output, by adding &o=xml on the GET url line.
A number of the XML APIs support an &inc= parameter, which lets you specify which fields you want returned in your XML reply. This helps you get a very short reply, easier to parts and look at. In most cases, you will want to use inc= on your production code to decrease application latency. All replies are automatically sent via “gzip” compression when your browser-side indicates support for it. Try to use a mechanism that supports gzip compression if you are requesting large amounts of data: it saves about 90% of the bandwidth and radically decreases latency.
Please limit your API calls to no more than 10 per second. If you serialize them, that should be fine — just be careful if you have many threads/processes in your application calling the BookMooch APIs, that you aren’t super busy at times.
===
To add a book to your inventory, wishlist or save for later, use the “userbook” api call.
If the userbook call fails, it is because that ASIN (aka ISBN) is not in the BookMooch database. You can have BookMooch import the book data from an Amazon store with the “amazon_add” call, and then re-call “userbook”
===
To mooch a book, first call “moochable” to find out who is offering the book.
If you want to limit your mooching to people in your country, call “userid” for each of the people who are offering the book and look at “country” field to see that it is the same as your country. You may also want to be smart in your code, and for books that are offered by a lot of people, mooch from people who have the longest history of sending out books, and who also happen to be in your country.
Use the “mooch” call to actually ask for the book to be sent to you.
One of my top priorities over the next few months is helping other web sites offer book-swapping features through the use of the API, widgets, data feeds, and anything else that helps.
If you have any idea about how you might work with BookMooch, and what I have here doesn’t do what you need, please send me an email.
More small stuff
October 31, 2007
Here’s a log of small stuff that was changed in BookMooch today:
If you have enabled the “Allow multiple copies of the same book in your inventory” feature, and you indeed have multiple copies in your inventory, you will now find, next to each book that you have multiple copies of, a button to “remove dupes”:
 |
as well as, at the bottom of your inventory page, a “remove all dupe books” button:
hopefully, the functionality of these buttons is self-explanatory.
The “related editions” page now includes the edition you came from:
 |
I did this so that for other sites linking right into the related editions page, people coming from those links will be able to see what book we’re showing related editions for.
You can now add a book to your wishlist from the book details page, even if the book is available for mooching.
Previously, you couldn’t, because I have this philosophy that you should only use the wishlist for books you can’t get.
However, if the book is only available in another country and you don’t want to spend the 2 points, in that case you would want to add the book to your wishlist, and that seems quite reasonable to me.
The “pending” and “inventory” and “wishlist” pages in the member section now require you to be logged in, in order to view them.
Previously, I had made it so that urls such as http://bookmooch.com/m/inventory/buckman_ca and http://bookmooch.com/m/wishlist/buckman_ca and http://bookmooch.com/m/wishlist/buckman_ca could be seen by non-members of BookMooch.
The problem was that sometimes people would bookmark this page, exit their browser, and when they came directly back to that page without logging in, BookMooch didn’t know who they were, assumed they were non-members, and didn’t display the information that is shown to a member. For example, your pending page would not display postal addresses if you were not logged in.
This definitely confused some people. The problem would go away if you clicked on “member home”, which forced you to log in.
What this tangibly means is that if you want to email someone your inventory or wishlist url, and they are not a bookmooch member, use the URL from the non-member section of the web site, ie the URLs that do *not* have /m/ in them. The equivalent pages are:
As you can see, the URLs are identical, except that the member versions start with /m
Unfortunately, I can’t automatically redirect non-members from the member version to the non-member version, because the server needs to challenge the web browser to produce a name/password, in order to log in. If the server doesn’t issue the challenge, the web browser won’t ask the user to log in.
This is a small thing, but “session management” on the web is a huge and difficult topic, and unfortunately there are always compromises.
Search usability improvements
October 31, 2007
I’ve added some usability improvements to the search results page.
If your search found no available-for-mooching books for your search, but there are some unavailable books that match your search, then the unavailable books are displayed. For example, search for “carding” http://bookmooch.com/s/carding and since there are no available books for that, you are automatically redirected to a “show all” search:
 |
note that copies are zero in this search result, and also note the new “show available” button displayed on the top right:
this button will restrict your search to only show search hits for books that are available for mooching.
When you do a normal search that returns results, such as searhing for “Card” you will see a “show all” button on the top right:
this button will repeat your search, but show both moochable and unmoochable books.
If you are logged into BookMooch and do a search, a new button titled “My country” appears on the top right:
this button will repeat the search, but only show you books that are moochable by someone in your country. That is one way to avoid being told that “no-one with this book will send it to your country”, but it’s also a way to conserve your points, and only mooch things for one point, because they’re not international mooches.
Naturally, the opposite of “my country” is an “all countries” button, so you can toggle between the two views:
If your search finds books in multiple fields (such as “topic” or “publisher” or “author”), but you only want one, you can click on this new option at the bottom of the page:
so for example if you want to search for books in the topic of “cooking” you can first search for plain “cooling” then click the “topic” button and you will get books with “cooking” in their topic.
This feature used to exist in BookMooch, about 6 months ago, but I removed it because most of the time you would choose to restrict the search, and no moochable books would be found, and this was confusing and frustrating. Now, however, since BookMooch automatically will show you non-moochable search results if no moochable books are available, I’ve brought this feature back, as it works in a more intuitive way now.
If you search found books that were published in several countries, at the bottom of your search results, you will be find a button row to restrict your search accordingly:
such as this list of books that are published in France, and match the topic “cooking”. I got to this page by first searching for “cooking” then clicking on “topic” and finally clicking on “french”. This is a much easier way to get at the books you want than to use the advanced search form.
 |
All these features were previously available on the “advanced search” page, but that page is complicated to use, and involves a lot of clicking, and I suspect most people never bother. I hope these changes help people find things with the plain old search feature, and do so more easily and quicker than before.
Coffee mugs
October 29, 2007
Last year, I ordered a bunch of BookMooch coffee mugs for my friends.
They are really cute, with the inside color matching the aliens nicely. I didn’t put the words ‘BookMooch’ or a URL, or any text on them, because this way they’re more like “fashion mugs” than “advertising”. I do not make money from the sale of the mugs — that’s just not something I want to do.
Here is the URL to the mug
http://www.zazzle.com/bookmooch/product/168417669972613155
Last year, Zazzle ran a special promotion at the very last minute at the end of the year, lowering the per-mug price to $8.99 (regularly $14.95). I ordered mine on December 20th, 2006 — I’m assuming they had overstocked for xmas because they didn’t make a fuss about the temporarily much lower pricing. Not that you definitely will want to delay until then to buy a mug, but perhaps…
I made a white-background version of the BookMooch graphic, so that it would print well on mugs and other white objects. You can download it from http://bookmooch.com/about/logos and make your own products if you’re so inclined. There are tons of places on the web like zazzle and cafepress where you can make stuff and apply a graphic to it.
Number of copies in search results
October 28, 2007
I’ve started tinkering with the search results page, to make it more help.
For starters, I now show the number of moochable copies for each book. I also sort the books in the same way books are sorted elsewhere: “author + book title”
These two changes make it easier to see the same book title in multiple editions, as well as to see how easy it is to get that book.
I also was playing with the idea of making searches default to finding all books, whether they are moochable or not. The reason, is that many people get confused when they search for a book, and nothing comes up, because no copies of the matching books are moochable.
Here is what he same search for “card” looks like if you should non-moochable books
That doesn’t seem very useful: all those “zero copies” books. So, for now, the default search hit will be for moochable books only. I think perhaps a “15 books were also found, but not displayed because they aren’t moochable [show>]” message might do the trick.
Multiple copies of a book
October 28, 2007
BookMooch now optionally allows you to have more than one copy of the same book.
To enable this optional feature (it defaults to “off”) go to your profile page, and toward the bottom you will see:
the “details” version of your inventory shows if you have more than one copy:
the normal (condensed) inventory page shows multiple copies of the same book in parentheses, after the title. Each time you click the “remove” button, one copy of the book is removed.
the “book details” page also shows this
When you add a book that already exists, the message now tells you how many copies you now have:
the “bulk add” page shows a similar, but terser, message:
it’s a bit weird, but if you go to mooch a book that is offered several times by someone, they appear several times. I think this is actually the right behavior, so that if there are different condition notes for each, you could pick the one you want. Also, the inventory details page will show (copies: 2) if you have one copy in inventory, and one in your pending pile, and then will show just one copy when you postal mail the copy in your pending pile.
Some limitations of this feature:
1) You cannot attach different “condition notes” to each copy of the book. The condition notes are automatically attached to the first copy of the book. I’ll make this work right in the future.
2) You cannot specify which copy you remove when you click the “remove” button. It removes the first copy you have.
3) There may be other other bugs with this feature, simply because it touches so many other features of BookMooch. Leave a comment on this blog entry if you see a bug.
Seen it, read it
October 28, 2007
A number of people asked that recommendations hide books that they’ve previously given away, or are giving away.
I thought that was reasonable, but I wondered: “When you’re looking at books that BookMooch is recommending to someone else, should I hide books you’ve given away, or books the person being recommended is giving away, or don’t hide at all”. I puzzled that one for a while, and came up with a consistent way of handling this issue.
Also, I thought it was kind of interesting to have BookMooch show you that it recommends books that you’ve previously had, as it is a kind of confirmation that the recommendations are working decently.
From now on, all user recommendations will show all books (that weren’t specifically hidden by the user) but any books that you previous mooched/gave away/wishlist are displayed in grey italic, so that it’s easy for you to skip over them. If you don’t want to see the recommendation at all, just hide it. Whenever you are logged in and looking at people’s recommendations, the “hide” button will be available, and clicking that will hide that book from all recommendations that you view.
Here is what the books you’ve already given/wishlist/mooched (ie grey/italic) look like:
A BookMooch member asked on the blog “how many recommendations are there?” — the answer is that there are a max of 500 recommendations. But, if you hide one, another takes its place, so it’s not possible to whittle down the recommendations to a small list.
Some small changes
October 27, 2007
A few small features went up on BookMooch today.
Most of these changes come from comments on the blog. I really do read every comment, but because there are so many, I can’t respond to them (sorry). I mostly don’t have the time to read the bm-discuss forum, since it runs from 100 to 300 messages per day, I just can’t keep up. If you’ve got an idea for an improvement, post it on the blog, or just send me an email.
Next/previous buttons on the “points” page, the wishlist page, and the save-for-later page.
A lot of people complained that these pages could get very large, and their web browsers or computer could crash or just take a long time to show the page.
On the saveforlater/wishlist pages, I’m showing 20 books at a time, and on the points page, I’m showing 50 items at a time. That corresponds to roughly a 100k sized page, which I’m setting as a rough max benchmark for any single page, so that they load quickly and don’t stress out people with not much memory on their computer, or a slow internet connection.
UPDATE an hour later
As you can see below, I received a bunch of feedback from people who don’t like having to page through their wishlist.
So, I’ve now added to the inventory/points/wishlist/saveforlater/recommendations pages an “all” button that will show you everything for that page, no need to do next/previous. I’m *not* offering that on the “browse topics” and other pages where there could be 100,000 books in the ‘all’ view — that would be bad.
The “all” button will only display on page 1 of the data, and only if there is a “next page” button being displayed:
Also, the problem with “related editions” that is mentioned below in the comments should now be fixed.
Recommendation page small improvements
Your “save for later” list is no longer used to build recommendations, as someone correctly pointed out that since that list is private, seeing books recommended because of it could be a small invasion of privacy.
In changing this, I also noticed a bug, where your wishlist was *not* being used to build your recommendations. That should help improve the accuracy of the recommendations page.
The recommendations page now hides books you’ve previously mooched, but only if you’re looking at your own recommendations. When looking at books being recommended to other people, neither your history nor the person being recommended are suppressed from the recommendations. I hope this makes sense.
Change in mooch request email
I was told that the following sentence in Mooch e-mails appears to cause much confusion: “It is always a good idea to review a moocher’s history, bio, and inventory before sending your book.”
this has been changed to:
If you have any questions about the person requesting this book, feel free to email them by replying to this email message. If you suspect something isn’t quite right, click the ‘report abuse’ button on their bio page and a BookMooch volunteer will look into it for you.
ASIN = ISBN
A few people didn’t know that the word “ASIN” is Amazon’s term for “ISBN, when there is one, otherwise it’s Amazon’s own made-up number”
The book details page now makes this clear:
and about 40 other really tiny things that I won’t bother writing about here…
Related searches
October 25, 2007
When you search for something now on BookMooch, you will see some “related searches” shown to you, such as this search for “bukowski”
I was surprised by the high quality of the recommendations, but I guess I shouldn’t be: there is much more data in BookMooch about searches than mooches, since people search for a lot more books than they mooch.
Up to 3 recommendations are displayed on the search results page.
Clicking the “…” link will lead you to a longer list:
leads to:
Here is how the related searches are arrived at:
* for a year now, every search that everyone (who is logged in) makes, has been saved
* so, for a single search, BM first looks to see which other members have also searched for these words you’ve just searched for
* all the words those other members have ever searched for are all aggregated
* search words that occur less than 3 times are discarded as too infrequent to be relevant
* the list of search words is sorted, in order of how often it it is searched by these other members
* searches that would yield “no results” are automatically not displayed. This is a time consuming process for BookMooch, as it means BM actually has to run the full search for each recommendation it would make. For this reason, I’m caching recommendations for 24 hours, and that’s also why only 20 “related searches” are shown at one time (you have to page next/previous through them)
A related feature I’m thinking of adding is “personalized search recommendations”, where BookMooch looks at all the searches you’ve ever done, finds other people who search for these things, and then totals up all the things those other people search for.
And on that same topic, I should be able to add a “find people with similar book tastes to mine” based on both searches you have in common with them, and mooch history (and wishlist). This might be a useful feature for browsing their inventories to see what you might want to mooch.
And about that photograph on the top right of this blog entry, that’s comedian Conan O’Brien, and Finland’s President Tarja Halonen, they definitely seem like a “related search” (grin)
Alas, some data loss
October 25, 2007
I upgraded the BookMooch server today, from 8gb of RAM to 24gb.
This is important because the server was so overloaded that the daily backup, started at 2am, was taking until 3pm to finish (13 hours!).
I just did a full backup now, with the server running, and it took 11 minutes.
Alas, there was some trouble with the server upgrade, and a bit of data was lost. I had a backup from yesterday afternoon, which was used to restore some of the data.
What this means is that for some of you, you may be missing some mooches that you did between yesterday afternoon and today.
If you can figure out what to do on your own (such as re-contacting the person you were mooching with), that would really help us out. If you need help, send an email to tech support and they’ll help you out.
Yes, I know the data loss problem is really awful, believe me, I really feel it. I know what I need to do to fix it, and it’s soon on my todo list, but unfortunately to make the data loss problem go away, BookMooch will have to do more work, and hence be a bit slower, so I need to both proceed carefully, and also make sure that there’s plenty of speed to keep up with daily demand.
BookMooch Blog 