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.

One Response to “API improvements”

  1. Nanci said

    Ooops, saywhat? I understood the English, but not the tech-talk in your post: ie., API, widget, userid (which I guess is user ID), gzip compression, XML,&o XML, inc=, latency, bandwidth. Seems I’m too old for this game.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: