• Give it an asins= list of ASINs (or ISBNs) and it will return an XML document (documentation) or JSON of all the data for those asins.
• If the ASIN does not exist inside the BookMooch data, no data is returned for it in the XML document.
• Optional inc= parameter will restrict the output to only the fields named, ie inc=Edition+ISBN+Binding
• o=json option returns JSON output.

• Pending transactions have the form of "userid/number" as in "johnbuckman/12".
• Give it an ids= list of transaction ids and it will return an XML document (documentation) of all the data for those transaction. If the id does not point to a current pending transaction, no data is returned for it in the XML document.
• Optional inc= parameter will restrict the output to only the fields named, ie inc=status+giver.
• If you call "pending_confidential" instead of "pending", then HTTP-Auth is required (you must be this transaction's sender or receiver) and then postal address information is also included in the XML response.
• You can find out what pending transactions a user has with a call to "/api/userid?userids=buckman_ca&inc=pending_give+pending_receive"
• o=json option returns JSON output.

• The output defaults to XML.
• o=json option returns JSON output.
• Give it an userids= list of user ids and it will return an XML document (documentation) of all the data for those users.
• If the userid does not point to a current BookMooch user, no data is returned for it in the XML document.
• Optional inc= parameter will restrict the output to only the fields named, ie "inc=statusmsg+homepage+displayname".
• An HTTP auth user login is required to use this API, and you must be a valid BM user. If you request information about the same user you are logged in as, an additional "postal" field will be returned in the results, which is your current postal address.

• Give it an asin= list of ASINs (or ISBNs) and it will return a carriage-return separated list of ASINs that are on wishlists at BookMooch.
• n=1 option returns number of people with that book on their wishlist.
• o=xml option returns XML output.
• o=json option returns JSON output.

• Give it an asins= list of ASINs (or ISBNs) and it will return an XML document (documentation) or JSON of all the data for those asins.
• If the ASIN does not exist inside the BookMooch data, no data is returned for it in the XML document.
• You need to specify the store= parameter (one of amazon.com, amazon.co.uk, amazon.ca, amazon.de, amazon.fr, amazon.co.jp).
• Optional inc= parameter will restrict the output to only the fields named, ie inc=LowUsed_Price
• o=json option returns JSON output.

• You need to specify the store= parameter (one of amazon.com, amazon.co.uk, amazon.ca, amazon.de, amazon.fr, amazon.co.jp).
• Returns 1 on success, 0 on failure, 2 if the book already exists in the BookMooch database, in an "asin success" structure, one book per line.
• o=xml option returns XML output.
• o=json option returns JSON output.

• You need to specify the the username and password to the HTTP authentication challenge that this API call returns.
• Returns 1 on success, and no page at all on failure.
• o=xml option returns XML output.
• o=json option returns JSON output.

• Returns 0 if no error occured, or a negative number if an error occured. Each error type has a unique negative number associated with it.
• Also returns a textual description of the error, which you can choose to show the user.
• o=xml option returns XML output.
• o=json option returns JSON output.
• The following fields are all required:
  • username: Your user name, a-z0-9 characters only
  • displayname: Your display name
  • email: Your email address
  • pw: Your password
  • country: Your country (a two digit ISO standard country code)
  • postal: Your postal address on several lines
  • zip: Your zip or postal code
  • secret_question: Your secret question (can be any textual sentence)
  • secret_answer: The answer to your secret question
  • An "appkey=" is required for this functionality, please contact us.

• Give it an asin= list of ASINs (or ISBNs) and it will return a carriage-return separated list of ASINs that were successfully added.
• Requires http-auth name and password of user to add to. target= must be 'inventory' or 'wishlist' or 'savelater'.
• Change action= to 'del' to delete instead of adding.
• Optional: when adding to inventory, the &reserve_days=7 parameter will reserve the book for 7 days. You can specify any number of days you like or &reserve_days=0 to reserve the book forever. You also need to specify &reserve_userids= which is a space-separated list of userids who this book reserved for. Specify &reserve_userids=friends if you want the book to be reserved for all your friends. To remove the reservation via the API, you should remove the book from your inventory and then re-add it without a reservation.
• Note: only works for ASINs that are already in the BookMooch database: to add a book from Amazon into the BookMooch database, use the "amazon_add" api
• o=xml option returns XML output.
• o=json option returns JSON output.

• Give it an asin= list of ASINs (or ISBNs) and it will return a carriage-return separated list of ASINs that are available for mooching (ie, on someone's inventory) at BookMooch.
• n=1 option returns the count of the number of people with that book in their inventory, while n=2 returns a comma-separated list of userids with that book in their inventory.
• o=xml option returns XML output with all fields.
• o=json option returns JSON output with all fields.

• Give it a txt= parameter of what you want to search for.
• The text result is simply a carriage return delimited list a ASINs that match the search criteria
• The db= parameter is either "bm" or "amazon.com", depending on which database of books you want to search. Other Amazon stores, specifically "amazon.co.uk", "amazon.de", "amazon.co.jp", "amazon.fr" and "amazon.ca" are also valid.
• Optional page= parameter is a number between 1 and 99 that indicates the page number in the results set you want to return, allowing you to display "previous/next" results. The first page of results is returned if this is not specified.
• Optional inc= parameter will restrict the xml output to only the fields named, ie &inc=Author+Title+Binding+id
• o=xml option returns XML output. The XML result contains a variety of fields, including author, title, and number of copies available for mooching.
• o=json option returns JSON output. The JSON result contains all the same fields which are in the XML output.

• This API call requires a valid user login, because the information returned is specific to the user doing to the request (ie, which country they are from)
• Optional inc= parameter will restrict the output to only the fields named, ie "inc=asins_listed+statusmsg".
• Optional exc= parameter will restrict the output by excluding the fields named, ie "exc=feedback_score".
• The list of givers of a book is automatically sorted from most-preferable at the beginning, to least preferable at the end (ie, friends and reserved copies first, "ask me first" copies at the end).
• This call is generally used to present a user with a list of people they can mooch a book from. The most important details to display to the user so that they can make a choice are:
  • The giving user's status message: <userid>/<statusmsg>
  • The book condition from each giver is given in the field: <userid>/<asins_listed>/<asins_listed_item>/<condition>
  • The giving user's country: <userid>/</country>
  • The giving user's userid: <userid>/</id> and display name: <userid>/</displayname>
  • The most recent date the user logged into BookMooch is in: <userid>/<lastnow> and is in seconds-since-1970 format.
  • The giver's feedback score is in <userid>/<feedback_score>
  • The date the giving user joined BookMooch: <userid>/<now> and is in seconds-since-1970 format.
  • The date the book was added to this giving user's inventory: <userid>/<asins_listed>/<asins_listed_item>/<now>
• IMPORTANT: if the <userid>/<willsend> field is set to "askme" then you cannot immediately mooch this book from this person, you must instead call the "askme" API to send a request to mooch this book. <userid>/<willsend> will not be present in the returned XML if the book can be mooched immediately. Your user interface should display "ask first" or some other similar message to your user in this case. Note also that "askme" members will be sorted to the end of the XML result set, since they are not as preffered to mooch from.
• o=json option returns JSON output.

• If the output format is text, then the first line is the result code, the 2nd line is a short text version of the result code, and then the HTML resulting from the request is on the 3rd line and thereafter.
• country= should be a two-letter ISO standard country code
• If the output format is XML, these fields are all returned in an XML encoded format.
• Optional comment= is stored in the mooch request and displayed to the book sender in their email and web interface.
• The result code is set to 1 on success, or a number less than zero on failure.
• The "meeting" parameter is optional and is usually left blank or undefined.
  • This field is used to define this as a "meeting mooch", which is a mooch request where the book should not be postal mailed. Instead, the book should be brought to a meeting.
  • If meeting= is defined, the address= field is ignored and meeting information is filled into the mooch request's address field instead.
  • The "meeting" parameter needs to point to a valid meeting name (ie, http://bookmooch.com/forum/meetingname)
  • The book giver needs to be listed as an attendee of the meeting, or the meeting mooch will be rejected by this api.
• Before calling "mooch" you should have called "moochable" to find the userids who are giving this book, and picked the userid you wanted to mooch from.
• If you want to mooch books for only 1 point (ie, no international mooches), be sure to only mooch from userids who are in the same country as you are.
• Requires http-auth name and password of the user you want to be when mooching.
• o=xml option returns XML output.
• o=json option returns JSON output.

• If the output format is text, on the first line a "1" is returned if the call was successful, or a unique negative error code for each error type if not. One the 2nd line (and possibly multiple lines) is the error message.
• country= should be a two-letter ISO standard country code
• If the output format is XML, these fields are all returned in an XML encoded format.
• Optional comment= is stored in the mooch request and displayed to the book sender in their email and web interface.
• The result code is set to 1 on success, or a number less than zero on failure.
• Before calling "mooch" you should have called "moochable" to find the userids who are giving this book, and picked the userid you wanted to mooch from.
• If you want to mooch books for only 1 point (ie, no international mooches), be sure to only mooch from userids who are in the same country as you are.
• Requires http-auth name and password of the user you want to be when mooching.
• o=xml option returns XML output.
• o=json option returns JSON output.

• If the output format is text (which is the default) each line will have the ASIN, followed by a space, the time the book was added (in seconds-since-1970 epochal time) and then the userid of the person giving that book away.
• In XML or JSON output formats, all the book's data is given. In addition there are "added_by", "added_when" and "added_where" fields which give the user who added this book and when they did so, and in what country that person is.
• The books are listed in most-recently-added sort order
• Optional since= parameter lists the time (in seconds-since-1970 epochal format) to only display books added since that time. If ommitted, all books added in the past 24 hours is returned.
• Optional inc= parameter (JSON example) will restrict the output to only the fields named, ie inc=id+added_when+added_by+added_where+Author+Title
• Note that books are correctly removed from this list if they are mooched or otherwise removed from the book owner's inventory

• If the output format is text (which is the default), on the first line a "1" is returned if the call was successful, or -1 if the call was not successful. One the 2nd line (and possibly multiple lines) is the error message, which will be empty on success.
• This API call requires a BM user login. In addition, that user must be approved by the site administrator as having permission to use this API. Email the admin to obtain permission.
• Messages are sent as UTF-8 encoded, so if you want to use "international" characters in your email they should be UTF-8 encoded.
• The email message will be sent From: the user you are logged in as.
• to= is the BookMooch user to send the email message to. You can only send messages to existing BM users, you cannot send them to email addresses.
• subject= is the subject of the email
• body= is the text of the email body
• htmlbody= is an optional HTML version of the text of the email body. If included, the email message is sent as a multipart MIME message, with both the text and HTML versions of the email. Note that the multipart message uses the text "===============" as the MIME separator text, so do not use a long line of equal signs in your email message if you are sending out an HTML message as that will cause a corrupt MIME message.
• As with all BookMooch APIs you can use this API with HTTP GET or POST. HTTP POST is preferable, as there are short Internet standards limits on how much text can be on a URL, which could truncate your email message.
• o=xml option returns XML output.
• o=json option returns JSON output.

• Requires http-auth name and password of the appropriate book giving or receiving member in this pending transaction.
• Possible actions are "accept" "cancel" "delay" "lost" "sent" "reject" "received" "received_forced" "remind_received" "remind_send".
• An id= and action= is always required. All actions can take an optional comment=.
• The output defaults to a text format
• o=xml option causes output in XML format
• o=json option causes output in JSON format
• In text output, the first line is a 0 (success) or negative number (failure) indicating the final status of this action.
• The 2nd line is a one-line text description of the final status.
• The third and following lines is the HTML response for this action that would normally have been displayed in the BookMooch web interface.
• Most pending actions also require param1= or param2= or param3= as follows:
  • for "action=accept"
    • param1="text string describing how soon you think you can send this book"
    • Example URL: pending_action?id=johnbuckman/33&action=accept&comment=x&o=xml
  • for "action=delay"
    • param1="text string describing the length of the delay"
    • Example URL: pending_action?id=johnbuckman/33&action=delay&comment=x¶m1=a+few+days&o=xml
  • for "action=remind_received"
    • No additional parameters are needed, only the id= is used for this call.
    • Example URL: pending_action?id=johnbuckman/32&action=remind_received&o=xml
  • for "action=remind_send"
    • No additional parameters are needed, only the id= is used for this call.
    • Example URL: pending_action?id=johnbuckman/32&action=remind_send&o=xml
  • for "action=received"
    • param1="Feedback score" and should be set to 0="NO OPINION: neither good nor bad (+0 feedback) or -1="UNHAPPY: transaction did not go well (-1 feedback)" or 1="HAPPY: everything ok (+1 feedback)"
    • param2="Optional, publicly viewable comments about this cancelled transaction."
    • Example URL: pending_action?id=johnbuckman/33&action=received&comment=x¶m1=0¶m2=great+condition+thanks&o=xml
  • for "action=received_forced"
    • param1="Feedback score" and should be set to 0="NO OPINION: neither good nor bad (+0 feedback) or -1="UNHAPPY: transaction did not go well (-1 feedback)" or 1="HAPPY: everything ok (+1 feedback)"
    • param2="Optional, publicly viewable comments about this cancelled transaction."
    • Example URL: pending_action?id=buckman_ca/118&action=received_forced&comment=x&o=xml
    • Note: only the book sender can force the book as received, and only after a reminder has been sent (ie action=remind), and only after 42 days have elapsed since the book was marked as sent
  • for "action=cancel"
    • param1="Why are you cancelling?" and should be set to 0="I changed my mind (or some other reason)" or 1="The book owner never responded"
    • param2="Feedback score" and should be set to 0="NO OPINION: neither good nor bad (+0 feedback) or -1="UNHAPPY: transaction did not go well (-1 feedback)"
    • param3="Optional, publicly viewable comments about this cancelled transaction."
    • Note: the "Message to book owner:" field is filled in with the comment= value on the URL.
    • Example URL: pending_action?id=buckman_ca/117&action=cancel&comment=x&o=xml¶m1=0¶m2=-1¶m3=never+heard+back
  • for "action=lost"
    • comment="Any comments you want to write to explain what happened."
    • Example URL: pending_action?id=johnbuckman/33&action=lost&comment=x&o=xml
  • for "action=sent"
    • comment="Any comments you want the requestor to get about your sending of this book."
    • Example URL: pending_action?id=johnbuckman/33&action=sent&comment=x&o=xml
  • for "action=reject"
    • comment="Any comments you want the requestor to get, to explain why you can't send the book." (required)
    • param1=either "r" to mean "Remove this book from your inventory, so that no-one else can ask you for it" or "l" meaning "Put the book back in your inventory for someone else to mooch"
    • Example URL: pending_action?id=johnbuckman/33&action=reject&comment=x¶m1=r&o=xml

• fbuid_set: set the Facebook uid for a single BookMooch user.
• The output is in JSON format or XML format.
• userid= specifies one BookMooch user id
• fbuid= specifies a 64bit Facebook userid
• Passing a blank fbuid will erase the Facebook id from the BookMooch user's record
• An "appkey=" is required for this functionality, please contact us.

• userid: return the Facebook uid of a given BookMooch user.
• A list of userids can be passed, and the output can be in XML or JSON format.
• Consult the "userid" API call earlier in this document for full documentation.

• fbuid2bm: return the BookMooch user ids for the given Facebook user ids.
• The output is in text (default), XML (&o=xml) or JSON (&o=json) format.
• You can optionally pass a list of Facebook userids

All the API calls can take their parameters either on the URL (ie HTTP GET) or in the POST data section.

The GET method has the advantage of being easy to debug.

The POST method has the advantage of being able to pass arbitrarily large fields in, such as a large number of ASINs.



Error handling

When no data is found for an API call or your parameters are missing or invalid, this is indicated with a "result_code" field that has a negative value. For each kind of error, a different negative number is returned. The "result_text" field is a text description of the error. Here is an example for a call to "userid?userids=john_smith"

<?xml version="1.0" encoding="UTF-8"?>
<userids>
<userid>
	<id>john_smith</id>
	<result_code>-1</result_code>
	<result_text>no data found</result_text>
</userid>
</userids>

Feel free to

EMAIL JOHN >

if you have any questions or need something that isn't available