An Ebook Catalog for Our Readers; an API for Developers [Updated]
Reading the history of U.S. foreign relations just got a lot more convenient. The Office of the Historian has officially released two contributions to the President’s Digital Government Strategy: (1) an expanded selection of ebooks that are tailor-made for reading on mobile devices like smartphones, ereaders, and tablets, and (2) a new online service that software developers can use to embed our full ebook catalog within their sites and apps.
[Update, May 23, 2013: A third party iOS application, ShuBook, released an update that included the full Office of the Historian ebook catalog in the app. ShuBook [iTunes] (also discussed below in the original post), now includes the ebook catalog in its list of built-in catalogs, dramatically simplifying the task of accessing our catalog from the app, and providing a better experience to readers. We welcome third party developers to incorporate our catalog, in keeping with the spirit of the Digital Government Strategy. Resources for developers are at http://history.state.gov/developer.]
Our ebook program, which began as a pilot project last year, graduates today and now has a full-fledged role in the Office’s publishing endeavors. Now over 100 volumes of the Foreign Relations of the United States (FRUS) series are available for free download from our ebooks page.
But as anyone who has tried loading an ebook from a website onto a device can tell you, those steps can be a little complicated.
Today, we are releasing an online service that allows our ebook catalog to be embedded inside apps. In other words, instead of coming to our website to download ebooks, you can browse our catalog from within your ebook app.
In software developer terminology, this means we have made our catalog into an Application Programming Interface (API). (Are you a developer interested in integrating the catalog into your applications? Visit our new “Developer Resources” page at http://history.state.gov/developer.)
To illustrate how you can use our ebook catalog API—today, and for free—let’s look at how you can add our catalog to a third party application. ShuBook [iTunes] is a free, iOS-based ebook catalog browser and ebook reader application. (This is not an endorsement of ShuBook; we have selected ShuBook merely as an example of functionality that many fine ebook apps offer.) When you download and open ShuBook, you can tap on its Download tab to look at its list of ebook catalogs, which include Project Gutenberg, the Internet Archive, and FeedBooks.
[Update, May 23, 2013: Now the Office of the Historian ebook catalog is built in to ShuBook, and is listed alongside these other fine catalogs. The original instructions in this post for manually adding our catalog are still preserved below, since they illustrate the process of adding our catalog to a third party application.]
Here, ShuBook’s Download tab is shown selected, which reveals the list of built-in catalogs.
Besides browsing these built-in catalogs, ShuBook also lets you add other catalogs by entering their URLs. This is how you can add the Office of the Historian’s catalog to ShuBook. From the Download tab shown above, select the Custom tab and then tap the + icon in the top menu bar.
Here, we have selected the Custom tab, revealing the + icon in the top menu bar.
Now, tap on Add Catalog:
In the Add Catalog dialog box, enter “Office of the Historian” as the Book Source Name. For the Catalog Address, enter http://history.state.gov/api/v1/catalog. For Icon Address, you can leave this blank or enter http://static.history.state.gov/images/HistoryAtState-avatar.jpg:
Then click Save, and ShuBook will show the catalog in the list of custom book sources:
Now you can tap on the new entry for the Office of the Historian catalog, ShuBook will contact our server and retrieve the top-level categories for our catalog, “All Volumes,” “Recently Published,” and “Browse By Keyword”:
Then, if you select a top-level category like “All Volumes,” ShuBook makes another request to our catalog to retrieve the list of all volumes currently available as ebooks. The “Recently Published” entry shows an always up-to-date list of the most recently published ebooks. The most interesting way to browse is using the third option, “Browse by Keywords.” This lets you browse our volumes by People, Places, or Topics (a hierarchical subject keyword of U.S. foreign relations). You can also search the keywords to find volumes by tapping in the search bar at the top of each page of our catalog. (Until we integrate this subject keyword-based functionality into our website, our ebook catalog API is the only place it exists.)
Follow any of these routes to find a volume, and tap on it to see more information:
That is the full size cover image of the Foreign Relations volume on the Cuban Missile Crisis. If you decide you want to download this book to read it on your device, just click the blue “Download” button in the top-right corner, and ShuBook retrieves the latest version of the ebook from the Office of the Historian’s servers and places it in your library, where you can read and search the entire book, whether you are connected to the Internet or not.
We hope our readers enjoy the ebooks and the new ways of browsing our catalog. Please send your comments, questions, and suggestions to email@example.com.
We also look forward to working with third party developers who want to integrate our ebooks and catalog API into their applications and find innovative uses of this data. Please visit our Developer Resources page.
For more information on the Department of State’s participation in the Digital Government Strategy, see the reports at http://www.state.gov/digitalstrategy/.