The web's reading platform.

Readability Python 0.2.0

Are you a developer? Do you write Python? Great! We’ve made some big changes and additions to the Readability Python library. We’ve simplified interactions with the Reader API and added support for the Parser API.

First, The (small bit of) Bad News

With this new release, we’re dropping Python 2.5 support. Hopefully, this isn’t a shock. We’d like to look to start putting effort towards supporting Python 3 rather than worry about supporting past versions of Python.

The Important Stuff

The philosophy behind simplifying the code was to bring HTTP to the surface. We ditched the idea of models and now expose the raw JSON from the server as dicts. All calls will return an instance of httplib2’s Response class with a slight modification. Each instance has an added ‘content’ attribute that contains the server’s JSON response encoded with the standard lib’s json.loads. This gives the user direct access to the data in a convenient dict.

from readability import ReaderClient
rdb_client = ReaderClient('my_reader_token', 'my_reader_secret', 'user_key', 'user_secret')
bookmarks_response = rdb_client.get_bookmarks(favorite=True)
print bookmarks_response.content

>>> {
'bookmarks': [{
'read_percent': u'0.00',
u'tags': [],
}, ...

If you used past versions of the library, you might notice that XAuth still exists but OAuth is gone. The OAuth implementation was never fully baked. Instead of trying to maintain our own, we decided to let the community leverage the great libraries that are already out there. Simple Geo’s oauth2 library is great. If you’re using Django, we added Readability support to django-social-auth to help with the process.

Parser API Support

Recently, all Readability users were given access to the Parser API.

After the Readability package is installed, getting parsed content is as easy as:

from readability import ParserClient
parser_client = ParserClient('your_parser_token')
parser_response = parser_client.get_article_content('http://www.some-web-page/blog.html')
print parser_response.content['content']

>>> {
"content":  "I'm idling outside Diamante's, [snip] ...",
"domain": "",
"author": "Rafi Kohan",
"url": "http://www.some-web-page/blog.html",
"short_url": "", ...

Note, the use of ‘content’ looks a bit redundant. It’s necessary due to the response content being in an attribute called ‘content’ and the article content being returned with the key ‘content’.

Check out the documentation and the terms of use for more information on the Parser API.

Get Started

Take a look at the code on Github. Feel free to submit feedback, feature requests, contributions and bug reports. Don’t forget to let us know if you build something! A Birds-Eye View Into What Everyone is Reading

Thousands of times every minute, somebody uses Readability to have a better reading experience. Nearly five million people do it every month. We expect that activity to ramp up even further thanks to the hundreds of apps connected to our network.

Every single major publisher on earth has readers who find that content more engaging when delivered through our platform. And we’re the first service in history to be able to deliver that content consistently across a vast array of apps on nearly every device in use today.

From the outset, we wanted to put energy towards finding patterns and trends in all that activity that would be truly valuable to everyone. We didn’t want just another “trending” list. We knew that the reading view represented a greater commitment to shut the world out and focus on reading something—an incredible valuable behavior to pay attention to.

Today, we’re introducing a new, more sophisticated version of Top Reads. We’ve completely redesigned the experience and made the intelligence behind it even more compelling. It’s an incredibly powerful way to discover great content that’s worth your time. Just visit to get a birds-eye view of what people are reading on the web.

Screenshot of the redesigned Top Reads in Chrome, and Top Reads on iPad

If you’re not a fan of constantly visiting the same web page, just follow @topreads on Twitter. It’ll tweet out articles as soon as they heat up on the Readability service. iOS users can access Top Reads at any time right inside the Readability iOS app.

In the near future, we’ve got big plans to mine even more gold from all the amazing activity happening on Readability every minute of every day. We’re the only reading platform and network that has that insight— and we look forward to sharing more of it.

Happy reading!

Introducing: The New Readability for Chrome and Tags in iOS

Today, we’re excited to announce two big releases; the fastest, most feature-rich version of the Readability extension for Google Chrome and Readability 1.2.5 for iOS

The New Chrome Extension

With this version, our highest priority was to make drastic improvements to the existing features. Read Now, Read Later, and Send to Kindle have all been reworked to be faster, more responsive, and more dependable. Our second priority was to introduce a select number of new features to make reading with Readability even easier.

Screenshot of the Readability extension for Google Chrome


We’ve made it easier than ever to keep your Reading List organized. Each time you bookmark an article for Reading Later you will have the option to add tags.

Context Menu Items

Want to quickly bookmark a handful of articles for Reading Later? Now you can just right-click on any link and select Read Later. You can also Send a page or a link to your Kindle, Read Now in a New Tab or Window, or quickly jump to your Reading List from the context menu.


You can now log into your Readability account directly from the extension. No more being taken to a new page to log in if you Read Later on an article and are not logged in; the extension will bring the login form to you. Even better, the extension will remember what you were doing and complete that action once you’ve logged in.

Improved Speed

This thing is fast. Really fast. We’ve built a robust, dedicated server-side component whose #1 priority is to handle requests from the extension and to do so without you noticing.


When you click a button or press a key, you expect something to happen. We’ve re-imagined how the extension communicates with you to make it crystal clear what’s happening each step of the way. In the event that something goes wrong, the extension will make you aware of the issue and give you options for what you can do.


In previous versions of the extension you’ve had the option to set custom keyboard shortcuts. We’ve kept that in place and we now offer a couple of other customizations. You can now choose between two different icons styles; red or grey and if you don’t plan on adding tags, you can turn off the tag prompt after a Read Later. We’ve also made the options easier to find; just click the gear icon at the bottom of the extension.

Head over to the Chrome Web Store to install The New Readability for Chrome, you’re going to love it.

A note to our Firefox, Safari, and Opera users: We haven’t forgotten about you! We’ll be bringing all of these new features and improvements to you soon.

Tags and Improved Sharing in Readability 1.2.5 for iOS

The newest release of our award-winning app puts a handful of oft-requested features and improvements into your hands making it an ever-more indispensable tool for reading the web in comfort.


We’ve brought the organizational power of tags to the App. Tags that you’ve added to articles on the web site or through the new Chrome Extension will now be available for you to filter your Reading List.

Native Twitter and Facebook sharing

We’ve made sharing what you’re reading easier than ever. Readability will now recognize and use any Twitter or Facebook accounts that are stored in your device settings.

More fixes and improvements

Along with exciting new features, we’ve also made a number of bug fixes and improvements. Including; full Accessibility and VoiceOver support and fixes to article syncing.

Readability 1.2.5 for iOS is available in the App Store.

These releases are another example of the high quality work that we’ll continue to provide, making reading on the web an easier and more enjoyable experience.

Thanks for reading

Get Rolling With The Readability API

Since day one of Readability’s launch as a service we’ve made the entire platform’s feature set available through the Readability API. The results ever since have been amazing. From full-featured clients like Reeder and ReadKit to send-to integration in tons of apps, Readability has truly evolved beyond our own apps into a full-fledged reading platform.

Today, we’re excited to unveil an updated simple one-click step for developers and partners to get rolling with any one of our three APIs: the basic feature set, the content parser or the URL shortener (note the API requires no key). When you visit the Readability APIs home page, you’ll be greeted with the proverbial first step: get your API keys!

Getting your API Keys

After registering (or logging in if you’re an existing user) you’ll be handed your own unique API keys to get started.

If you’re an existing Readability user, just visit your My Account page and navigate to the API tab. From there, you’re asked to fill out a brief form and voilà:

API Keys

To date, we’ve granted over 2,000 keys and watched an amazing ecosystem develop around Readability. Now that we’ve made it so much easier for developers to get started, we can’t wait to see what you come up with next.

Facebook and Readability – Together at Last

We’re excited to announce the latest version of Readability with Facebook integration. Now, you can automatically share what you’re reading with your friends by connecting your Facebook account. Once connected and turned on, articles sent to your queue are also shared with your friends. Also, if you favorite an article in Readability, it registers as a Facebook “Like”. If you’re worried about cluttering your friends’ Facebook streams, rest assured. Multiple articles will be grouped into a single, neat Facebook post.

Facebook integration

Registered users of Readability can link their account to Facebook by visiting their Connections page. Down the road, we plan to continue to enhance the social experience of reading on Readability. We’re committed to not only delivering the best reading experience around but the best social experience around what you’re reading. Stay tuned!

Top Reads Tuesday — Remembering Aaron Swartz

On January 11, Aaron Swartz, a brilliant young programmer and activist, committed suicide while facing federal trial for downloading JSTOR documents using a laptop he snuck into a utility closet on MIT’s campus. Four articles about the tragedy, and the case surrounding it, have landed on Top Reads, our constantly updated snapshot of what’s popular on Readability:

RIP, Aaron Swartz.

Create Better Instruction Manuals With Readlists

When purchasing a new appliance or device, the first thing most of us do is read the instructions. Take the AeroPress, a nifty coffee brewing device, for instance. Its instructions are simple, and that’s part of its charm, but if you do some research online, you’ll find they’re only the beginning.

After experimenting and developing new techniques for better brewing, enthusiasts share their findings online. There’s a lot of great information out there, but it’s all over the place. A Readlists user, eimer, decided to pull some of the best articles he found together to make his own Intro to AeroPress instruction manual.


With the holiday season well on its way, there’s a good chance you’ll find yourself stuck reading incomplete or unsatisfactory instructions. With a little research, and the help of Readlists, you can do better. And since you can send your improved instruction manual to your iPhone, iPad, Kindle, or other compatible device with the click of a button, you’ll never have to worry about losing it in a drawer somewhere.

Readlists Makes it Easy to Collaborate

Recently, Craig Mod wrote a very popular blog post about simple tools and systems for digital publishing in the time of tablets. Aaron Lammer of Longform decided to pull together a readlist, where he linked to Craig’s essay and included some useful supporting material. When he shared it on Twitter, he used Readlists’ public edit link option, letting others add their own links to the list as they found them. It’s exactly the kind of collaboration that Readlists makes super easy.

Here’s How You Can Start Collaborating

Collaborating on a readlist is dead simple. Readlists provides two URLs on every list. One is a direct link you can email and share however you like. The other is a “public edit link”. That’s where the magic happens.

When you click the public edit link, a little window with a special link will appear. Share that link, and you’re giving anyone who clicks it the ability to edit and build onto your readlist. (Remember that anyone who has that link can edit your readlist any way they want.)

Sharing a Public edit link is a great way to work with others, and we’re thrilled to see all the inventive lists our users have been building and sharing. Sign in with your Readability account and get started collaborating on your own readlists today.

Full Tagging Support Now Available in the Readability API

Just a quick update to let all of our developer friends know that we’ve rolled full tagging support into the Readability API, including support for tag creation via your third-party apps. It’s already live, and you can check out all the details over in our API docs. Better yet, sign up for a free Readability account and grab an API key for instant access.

Readability has grown into a reading platform in the truest sense. Beyond our our own site and apps for iOS and Android, the lion’s share of our traffic comes from great third-party apps like Pulse, Reeder, Tweetbot, Longform, and many, many others. Continuing to grow one of the best reading APIs on the market is at the heart of what we do, and we can’t wait to see what you’ll build with it.

Top Reads Tuesday — Variety Pack

Top ReadsIt’s been a fun week in Top Reads. With the U.S. elections over, and the bulk of the Fall tech announcements out of the way, we’re seeing a full spread of interesting topics bubbling up every day.

Here are the most popular articles on Readability right now:

Plenty of these articles were featured on Longform—a consistently great source of high quality, long form articles. If you happen to exhaust everything on Top Reads (hard to imagine), check out Longform Picks in our iOS apps. Happy reading!