William’s Comments (group member since Jul 19, 2011)

William’s comments from the Goodreads Developers group.

Okay, I see the problem. Will try to get this fixed soon. I'll post back in this thread when I have an update. Sorry for the hassle.

Sorry you're having trouble, Anton. Can you link an example of a page where the "Add to My Books" button isn't working? Also, which Web browser are you using?

Like Michael posted near the top of this thread, offering an expanded JSON response is not something we'll be able to do soon. Sorry. :\

Publishing your notes (output examples, et cetera) on GitHub as part of the Ruby API wrapper might be a good place to start. Maybe as part of a "HACKING" file or a set of wiki pages for developers working on that library. Making them part of an existing project increases the chance that more people will see and help maintain them. That would also make them something we could also link to from here in the developers group (in a sticky forum thread).

From there, with your permission, maybe I can copy some of the examples into the official Goodreads documentation. I hesitate to dump too much more info. into our docs without first cleaning up the design to make them more readable. But it's probably worth adding examples for some of the most commonly used methods.

Is it easy for you to adapt your notes for publication on GitHub like that? Does that seem like a good plan?

Again, I think it's great you're volunteering to help improve our docs — thank you. :) I just think it's a good idea to publish your work somewhere that doesn't completely depend on Goodreads, on top of whatever you send to us.

Adam, can you please show us an example request that's breaking? You can omit your developer key.

You can reply in the thread dedicated to search.authors.

Sorry, Adam, but our API doesn't supply author genre information.

It would help to know up front that currently the XML and JSON responses are different.

Indeed. :) The documentation for the book.show method will reflect this shortly.

Is the documentation only editable by the Goodreads staff? I am working to extend the Ruby API wrapper, and would love to help update documentation to reflect request/response information.

The docs. are only editable by GR staff, but we're happy to receive corrections/additions/revisions/suggestions by outside developers — as you've probably seen in other threads. That said, our time available for reviewing and incorporating submissions is pretty limited. So, I caution would-be contributors against sending us large revisions or additions. Full request/response examples for every method, for instance, might be nice, but it could be a long time before we vet them and incorporate them into the docs.

The docs. could definitely use more tending, Nate, and you are kind to offer to help. Can you tell me more about what updates you have in mind?

For books that are user provided...should this information be available or is it filtered out of all calls, regardless, due to the Amazon/BN constraints?

Nate, I think I answered your question in the other thread, but for other developers who wind up here: it's not a blanket filtering. We filter each field based on the data source for that field. If a field is supplied by a Goodreads user (librarian), or from a third party that allows us to re-distribute their data in our API, then that field should be included in our API response.

Are there other restrictions from Amazon and Barnes and Noble where you can't share the data through the API? I have noticed some other missing data when working with books.

Our data sources have changed a lot since this thread was opened. We no longer use Amazon-supplied data, except for a handful of books only available as Kindle e-books.

However, we must still follow our data partners' licensing rules, which means that book records retrieved with our API will continue to omit some fields. Moreover, because book records can include data pulled from multiple sources, individual fields within a book (e.g., cover image, publisher name) might have different restrictions; and which fields come from which sources will vary from book to book.

The upside is that our code can now check the data source for individual fields, so we can supply you with as much information as we can for each book. The downside is that there's no simple answer to the question, "Which book fields can I retrieve through the API?" The available fields will vary from book to book, and they can change over time as new data are imported from our partners or updated by our librarians.

I'll update the documentation to address this.

Andy, I'm not sure what Twitter sample code you're referring to. Maybe you could provide a link? Or paste some of your code here.

What callback URL are you supplying in your request to /oauth/authorize?

Sudharsan, that looks like a bug to me. I'll open a ticket about it. Sorry for the bother.

Signing a user out of Goodreads but leaving them signed into Facebook will tend to be problematic, I think. You've already encountered our auto-login feature (visitors who are signed into Facebook are automatically logged into their linked Goodreads account). There are other tricky situations that could arise with different GR/FB signed in/out states. E.g., signing into Facebook account A, then signing into a Goodreads account that's linked to Facebook account B.

To sign an app. user out of Goodreads, I think you'll have to sign them out of Facebook, too.

You probably already knew this, but Facebook-connected Goodreads users’ activity is already published to Facebook automatically using Facebook's Open Graph API (subject to the user's account settings). So your app. doesn't have to interact with Facebook at all unless you're building sharing features that go beyond what we already do.

Robert, it sounds like you want to have the user sign out completely. To do so, have your app forget the user's cookies, and then prompt the user to re-authenticate.

Patrick, faceted search has been on our list of "features we want to add" for a long time. Unfortunately, addressing more basic issues with search is more important at the moment. I've added your “+1” to our faceted search ticket, though.

One workaround that I see is to call our reviews.list method for a shelf, and then use the elements in the response to see all the shelves for each book. I think that gives you a straightforward way to narrow by shelf.

I thought the ISBNs had a check-digit which made their validation easy, no?

Correct, but our existing catalog is huge, and we can't casually delete potentially thousands of non-conforming ISBN data. There could be lots of user data and URLs that rely on them, even if they're incorrect.

There are solutions, to be sure, e.g., start by validating all new, incoming ISBNs. But like I said, that's just one step of a bigger job. :)

Cool. :)

I was accidentally calling isbn_to_id for a value of '0' but my script didn't notice it since it was returning a valid id (lucky book # 11775988).

It looks like that book's record had an ISBN of '0', which is why you got it in your response. I removed that (invalid) ISBN. If you find more incorrect book records, you can request corrections by posting in "Book Issues" section of our librarians group.

You might also consider validating ISBNs in your application. Sorry, I know that's a little inconvenient. We'd like to do the same thing throughout our catalog, but it's not a simple or straightforward job.

I tried with a few other short numerics just to see what would happen and they also returned values (but seems to be just mirrors of the bad values -- e.g. call it with '1' and it returns '1'

This API method falls back to matching on book ID if it can't match on ISBN. This behavior is undocumented and (clearly) unexpected. I ran into this same problem myself a few months ago. I'm inclined to call it a bug, but it's long-standing behavior that we can't casually alter.

You can work around it by taking the ID given by the response, requesting that book record, and checking whether its ISBN matches your original request parameter. If not, that means we fell back to matching on ID.

Robert, it looks like there's no way to get the full text of a user's own reviews. I've ticketed this as a bug, but I can't give you any estimate of when it will be fixed.

If you want to offer this feature, then you should request full review access. See this thread, which I also linked above.

On a related note, if I send in a review with newlines (\n) in the the text, when I retrieve the review these are being returned as "br" tags.

The API returns sanitized review contents (only a subset of HTML allowed, line breaks converted to br tags, et cetera). There's no way to return the "raw" contents for editing, even for developers with full review access, which is another shortcoming that I have ticketed.

Sorry, I know that's inconvenient.

BTW, there's actually bug there. The character counter is off by one and implies you can enter 20,001 character, but when you submit the form, validation logic enforces 20,000.

Oops, thanks for catching that.

Am I using the wrong API to retrieve the existing review?

The ability to retrieve reviews' complete text was abused to the point where we had to disable it by default. Unfortunately, that creates an awkward situation if you want to let users edit existing reviews through your application.

You can request access to complete reviews using the instructions in the page I linked above. Another solution is to present your users with a Web browser frame displaying our HTML page for editing reviews. Our native iOS app. takes that approach in the handful of cases where we don't have an API method for something.

Edit: Hmm, except I would think we would still let a user edit her own reviews. Let me investigate some more...

Before the search API method I was trying to use the book.title API method which accepts title and author as different parameters. The book.title API method results have different issues. For example, that API method doesn't find certain books that the search API method does. Also, the search API method can properly find books when provided a "lastname, firstname" author string but the book.title API method can't...so I switched to the search API.

Did you encounter this with your first examples, e.g., "around the world in eighty days jules verne", or are there other title/author combinations that illustrate this better?