Office of the Historian Ebook Catalog API

Overview

To improve access to data and encourage innovation, the Office of the Historian Ebook Catalog is open to third party developers via an Application Programming Interface (API). This browsable catalog contains all ebooks from the Foreign Relations of the United States (FRUS) series, the official documentary historical record of major U.S. foreign policy decisions and significant diplomatic activity. Use this API to embed our live, up-to-date, searchable, and browsable ebook catalog in your application and to locate download links to the ebooks and their cover images.

Do you have feedback or requests about this API? Use our feedback tracker on GitHub to start the discussion.

Accessing the API

The entry point to API is the following URI (no registration, authentication, or API key is required):

GET https://history.state.gov/api/v1/catalog

This request returns an XML response, using the Atom-based OPDS format (see below for more information about the RESTful OPDS standard), which contains a single Atom <feed> element, metadata about the feed (including a link to an OpenSearch description document that allows keyword querying of the ebook catalog), and three Atom <entry> elements with OPDS navigation-type links to interior resources:

<feed xmlns="http://www.w3.org/2005/Atom" xml:lang="en">
    <id>https://history.state.gov/api/v1/catalog</id>
    <title>Office of the Historian Ebook Catalog</title>
    <updated>2013-05-22T03:10:12.659Z</updated>
    <author>
        <name>Office of the Historian</name>
        <uri>https://history.state.gov/</uri>
    </author>
    <link
        type="application/atom+xml;profile=opds-catalog;kind=acquisition"
        rel="self"
        href="https://history.state.gov/api/v1/catalog"
        title="Office of the Historian Ebook Catalog"/>
    <link type="application/atom+xml;profile=opds-catalog;kind=navigation"
        rel="start"
        href="https://history.state.gov/api/v1/catalog"
        title="Foreign Relations of the United States"/>
    <link type="application/opensearchdescription+xml"
        rel="search"
        href="https://history.state.gov/opensearch.xml"
        title="Search Office of the Historian ebooks"/>
    <entry>
        <title>All Volumes</title>
        <id>all</id>
        <updated>2013-05-22T03:10:12.659Z</updated>
        <summary type="text">
            All Foreign Relations of the United States series ebooks
        </summary>
        <link type="application/atom+xml;profile=opds-catalog;kind=acquisition"
            rel="subsection"
            href="https://history.state.gov/api/v1/catalog/all"
            title="Foreign Relations of the United States Ebook Catalog"/>
    </entry>
    <entry>
        <title>Recently Published</title>
        <id>recent</id>
        <updated>2013-05-22T03:10:12.659Z</updated>
        <summary type="text">10 Most Recently Published Volumes</summary>
        <link type="application/atom+xml;profile=opds-catalog;kind=acquisition"
            rel="http://opds-spec.org/sort/new"
            href="https://history.state.gov/api/v1/catalog/recent"
            title="10 Most Recently Published"/>
    </entry>
    <entry>
        <title>Browse By Keywords</title>
        <id>browse</id>
        <updated>2013-05-22T03:10:12.659Z</updated>
        <summary type="text">Browse By Keywords</summary>
        <link type="application/atom+xml;profile=opds-catalog;kind=navigation"
            rel="subsection"
            href="https://history.state.gov/api/v1/catalog/browse"
            title="Browse By Keywords"/>
    </entry>
</feed>

While additional entries may be added in the future using the same self-describing format, the current entries are worth discussing. The three key URIs in the entries here are:

All Volumes

GET https://history.state.gov/api/v1/catalog/all

Recently Published

GET https://history.state.gov/api/v1/catalog/recent

Browse by Keywords

GET https://history.state.gov/api/v1/catalog/browse

The /catalog/all “All Volumes” URI leads to a listing of all ebooks in the catalog, sorted in “series” order (chronologically by period covered and then by volume number). The /catalog/recent “Recently Published” URI leads to a listing of the ten most recently published ebooks, sorted in reverse chronological order. Both these URIs return an OPDS feed with links to the ebooks. An example ebook entry:

<entry>
    <title>China, 1973–1976</title>
    <id>frus1969-76v18</id>
    <updated>2013-01-06T06:00:27Z</updated>
    <summary type="text">
        Foreign Relations of the United States, 1969–1976, Volume XVIII, China, 1973–1976
    </summary>
    <link type="application/epub+zip"
        rel="http://opds-spec.org/acquisition"
        href="https://static.history.state.gov/frus/frus1969-76v18/ebook/frus1969-76v18.epub"
        title="China, 1973–1976 (EPUB)"/>
    <link type="application/x-mobipocket-ebook"
        rel="http://opds-spec.org/acquisition"
        href="https://static.history.state.gov/frus/frus1969-76v18/ebook/frus1969-76v18.mobi"
        title="China, 1973–1976 (Mobi)"/>
    <link type="application/pdf"
        rel="http://opds-spec.org/acquisition"
        href="https://static.history.state.gov/frus/frus1969-76v18/ebook/frus1969-76v18.epub"
        title="China, 1973–1976 (PDF)"/>
    <link type="image/jpeg"
        rel="http://opds-spec.org/image"
        href="https://static.history.state.gov/frus/frus1969-76v18/covers/frus1969-76v18.jpg"
        title="Cover of China, 1973–1976"/>
    <link type="image/jpeg"
        rel="http://opds-spec.org/image/thumbnail"
        href="https://static.history.state.gov/frus/frus1969-76v18/covers/frus1969-76v18-thumb.jpg"
        title="Thumbnail-sized cover of China, 1973–1976"/>
</entry>

This OPDS entry element contains an ebook’s title, links to the EPUB, Mobi, and PDF editions of the volume, and links to the thumbnail- and full-sized cover images of the volume.

The “Browse by Keywords” URI leads to the main feed for subject keyword-based browsing of the ebooks. The keywords belong to a rich subject taxonomy focusing on the history of U.S. foreign relations, and is organized into three main categories: People, Places, and Topics, with 500 subjects nested hierarchically inside. Browse the taxonomy by accessing the /catalog/browse URI with the “tag” parameter:

GET https://history.state.gov/api/v1/catalog/browse?tag={value}

If an invalid tag is passed to the browse URI, a 404 error will be returned. The results of a browse are returned as links to sub-topics in the keyword taxonomy and links to any books matching the current tag (in the same form as the China volume example above). An example keyword entry returned inside a query for the Human Rights tag is Refugees (here, we excerpt an entry element from the feed):

<entry>
    <title>Refugees</title>
    <id>refugees</id>
    <updated>2013-05-22T04:03:53.436Z</updated>
    <summary type="text">13 volumes</summary>
    <link type="application/atom+xml;profile=opds-catalog;kind=navigation"
        rel="subsection"
        href="https://history.state.gov/api/v1/catalog/browse?tag=refugees"
        title="Refugees"/>
</entry>

Notice that the <summary> element provides a count of the number of ebook volumes that can be found by following the link to /catalog/browse?tag=refugees.

Tags can also be searched using the search URI with a “q” parameter (note: this URI is exposed in the OpenSearch description document above):

GET https://history.state.gov/api/v1/catalog/search?q={value}

A “q” query parameter can be submitted as (Google-style) free text using Lucene Query Syntax, e.g.:

q=China+Nixon

q=for*

The first query searches the subject keywords for (“China” OR “Nixon”) and returns an OPDS feed with entries linking to the /catalog/browse entries for Richard M. Nixon and China. The second query uses the asterisk wildcard to return entries including President Gerald Ford, the topic of Foreign Aid, and Secretary John Forsyth.

Again, all of these resources can be reached by navigating from this main catalog address, and since the entries may grow, we encourage developers to retain the main catalog address.

Please link back to the ebooks files on this server, so that readers can always receive the most up-to-date version of an ebook.

An OPDS-based, RESTful API

This API delivers resources using the Open Publication Distribution System (OPDS) Catalog 1.1, an open standard for encoding catalogs. This format is widely used by organizations that distribute ebooks, and enjoys a growing ecosystem of client applications. As an Atom-based format, OPDS uses the Representational State Transfer (REST) architectural style, and designs resources around media types, links, and link relationships. This means that the API is largely self-describing. Furthermore, the API does not define any new link relationship (“rel”) values, limiting itself to those defined in the OPDS spec.

To learn more about OPDS and the key concepts associated with this standard, visit the Discover OPDS site. The OPDS mailing list is a helpful forum for asking questions and following the evolution of the standard.