Series

Series

Filename: series.xml

Sample Feed: series_simple_small.xml

Contents and Purpose

This is a detailed feed for LibraryThing's series data.

Recommended Background

LibraryThing's series data is detailed and more comprehensive than other systems we have seen, but this requires a degree of background understanding on the part of developers who use it. We recommend that customers look at the data on LibraryThing to get a feel for how series operate. Some useful examples:

  • Harry Potter ( https://www.librarything.com/nseries/1/Harry-Potter ). Harry Potter has all the data in the feeds—groups, author(s), related series, other names. Notice the division into "groups" (Core, Harry Potter Schoolbooks, Short Stories, etc.)
  • Twilight Saga ( https://www.librarything.com/nseries/6/Twilight-Saga ). Another good, popular and relatively simple series you may be more familiar with. Notice that, here, the graphic novels are included as a separate group within the series. This is not always the case.
  • True Book ( https://www.librarything.com/nseries/3871/True-Book ). This is a prime example of a large series that has <occasional> set to true. Customers will generally only want to show titles in the series if they have them to sell, lend, etc.
  • Star Wars: Thrawn Trilogy ( https://www.librarything.com/nseries/2017/Star-Wars-Thrawn-Trilogy ). This is a good example of a subseries series. It has three books, which were also collected in an omnibus edition. It has the main "Star Wars" series as a super-series, and another series ("Star Wars: Hand of Thrawn") as a sequel series. As the works belong to both the main and subseries, customers will have to decide which to show. LibraryThing favors the subseries (see https://www.librarything.com/work/11297), although both series are named on the work page, but other use cases may require a different choice.
  • His Dark Materials ( https://www.librarything.com/nseries/42/His-Dark-Materials ) This is a good example of the difference in the "grouped" and "ungrouped" order. In "grouped" order it starts with "Northern Lights" (US title: "The Golden Compass"), which is what most people would say is the start of the series. In "ungrouped" order it starts with "Once Upon a Time in the North." In most cases—as here—the ungrouped order will be the chronological order of the series.

Scope

"Series" is here defined to exclude what LibraryThing calls "publisher series." Harry Potter is a series. It consists of works, not only editions, and can cross publishers. By contrast "The Penguin Classics" is a publisher series, consisting of editions, not whole works. We do not yet have a feed structure for publisher series.

NOTE: Before July 2020, LibraryThing series were part of a different data structure and a much simpler feed. See the deprecated Series Information. This feed has been wholly deprecated and no new information will be added.

Basic Structure

Example from https://www.librarything.com/nseries/5359/The-Deptford-Trilogy 

<serieslist>
    <series>
        <id>5359</id>
        <name>The Deptford Trilogy</name>
        <status>active</status>
        <originallanguage>eng</originallanguage>
        <occasional>false</occasional>
        <approved>true</approved>
        <url>https://www.librarything.com/nseries/5359/The-Deptford-Trilogy</url>
        
        <names>
        ...
        </names>
        ...
        <authors>
        ...
        </authors>
        <works>
        ...
        </works>
        <groups>
        ...
        </groups>
        <relatedseries>
        ...
        <relatedseries>
    </series>
</serieslist>

Elements and Attributes in The Basic Structure

<serieslist> is the top-level element.
  • <series> is repeated, one for each series in the system.
    • <id> (required) is the unique id of the series.
    • <name> is a "convenience" field for the "default" name. See the <names> section for the complete series-name data.
    • <status> is the status of the field. It can have four values, although most commercial users will want to consider all but "active" to be of little interest and not displayed or used.
      • active — a living, functioning series.
      • removed — a defunct series that has been permanently deleted from the system.
      • dormant — a defunct series that has been deleted from the system. Treat "dormant" as equivalent to "removed."
      • aliased — the series is defunct, but its contents have been combined into another series.
    • <aliasedto> is the id of the series that a series with the status "aliased" has been combined into.
    • <originallanguage> (required) is the original language of the series (see "Language abbreviations" in the Introduction).
    • <occasional> (required) is an aid to the best display of the series. It can be true or false. Occasional series are generally large series that have little necessary progression or the requirement to read many titles. The various "Dummies" books, for example, are an occasional series.
      • In Syndetics Unbound, the "occasional" switch is used to decide whether to show gray covers for absent books. A non-occasional series should show all "core" works, even if the library does not have them all. Thus, for example, a library should show Harry Potter 1, 2, 3, 4, 5, 6 and 7, even if the library is missing book 3 and 6. In Syndetics Unbound these books are grayed out. By contrast, as the "Dummies" series is an occasional series, Syndetics Unbound does not show every "Dummy" book that exists, with most of them grayed out, but only shows those held by the library.

      • <approved> is whether the series has been approved. Values are true and false. Series marked as unapproved (i.e., false) may be okay, but they have not been checked.

      <url> is the URL of the series on the main LibraryThing site, LibraryThing.com.

      <names> ... </names> is a structure for all the various names that a series is known by, in multiple languages.

      <authors> ... </authors> is a structure for the series author(s).

      <works> ... </works> is a list of all the works in the series.

      <groups> ... </groups> is a list of the larger segments within a series, such as the core of the series, omnibus editions and spin-offs works.

      <relatedseries> ... </relatedseries> is a list of connected series, including overlapping series and specific relationships, such as one series being a parody of another series.

The <names> Section

Example from https://www.librarything.com/nseries/5359/The-Deptford-Trilogy 

<names>
    <name>
        <wording>The Deptford Trilogy</wording>
        <language>eng</language>
        <default>true</default>
        <defaultforlanguage>true</defaultforlanguage>
        <approved>true</approved>
    </name>
    ...
    <name>
        <wording>La trilogie de Deptford</wording>
        <language>fre</language>
        <defaultforlanguage>true</defaultforlanguage>
        <approved>false</approved>
    </name>
</names>

Elements and Attributes in the <names> Section

<names> is the containing element for all the series names.
  • <name> is repeated, one for each series name.
    • <wording> (required) is the name of the series.

      • <language> (required) is the language of the name (see "Language abbreviations" in the Introduction). There can be more than one name per language.

      <default> (not required) is whether or not the name is the one "default" name for a series. In most cases the default name will be the English name. But, for example, if a French series has no English name, the French name will be the default name.

      <defaultforlanguage> (required) is whether or not the name is the "default" name for the <language> given. Every language given will have one name labelled the <defaultforlanguage>.

      <approved> (required) is whether or not the series name has been approved. At present only the default series name is ever approved, and only series that have been approved can have a default, approved series name.

The <authors> Section

Example from https://www.librarything.com/nseries/5359/The-Deptford-Trilogy 

<authors>
    <author>
        <id>363</id>
        <bsa>daviesrobertson</bsa>
    </author>
</authors>

Elements and Attributes in The <authors> Section

<authors> is the containing element for all the authors.
  • <author> is repeated, one for each author. Series can have more than one author.
    • <id> (required) is the author id. See the "Main Authors (resolvedauthors.xml)" feed below.
    • <bsa> (required) is the "bsa" (a code), for the author. See the "Main Authors (resolvedauthors.xml)" feed below.

The <works> Section

Example from https://www.librarything.com/nseries/5359/The-Deptford-Trilogy 

<works>
    <work>
        <workcode>370</workcode>
        <order>1</order>
        <showifabsent>true</showifabsent>
        <daysactive>1000</daysactive>
        <ordering>
            <groupedorder>1</groupedorder>
            <ungroupedorder>1</ungroupedorder>
            <label>Book 1</label>
            <showlabel>true</showlabel>
        </ordering>
        <group>
            <id>1</id>
            <name>Core</name>
        </group>
    </work>
    ...
    <work>
        <workcode>32421</workcode>
        <order>4</order>
        <showifabsent>true</showifabsent>
        <daysactive>1000</daysactive>
        <ordering>
            <groupedorder>2</groupedorder>
            <ungroupedorder>2</ungroupedorder>
            <label>Book 2</label>
            <showlabel>true</showlabel>
        </ordering>
        <group>
            <id>2</id>
            <name>Collections and Selections</name>
        </group>
    </work>
</works>

Elements and Attributes in the <work> Section

<works> is the containing element for all the works.
  • <work> is repeated, one for each work.
    • <workcode> (required) The "workcode," or work id, to which the review belongs.
    • <order> (required) The suggested order of the work within the series, counting up from 1. This field is the same as the value under <ordering> as <groupedorder>
    • <showifabsent> (required) is either true or false. If false, we recommend the work not be shown in a list of series works if the bookstore/library/website does not have the work to hand. Works with <showifabsent> of false are often obscure works, or collections, selections or omnibus editions. For example, Harry Potter was published in omnibus editions for books, 1-2, 1-3, 1-4, 1-5, etc. It usually doesn't make sense to show all of these, unless you have it to sell/show/lend.
    • <daysactive> (required) is an integer of the number of days since the work was added to the series. For maximum trust, do not show works that have xxx of less than 30 or 60.

      Reasoning When we approve series we approve the series overall, but works may subsequently enter the series without triggering reapproval. As a wiki, however, all changes are seen and followed by users, and incorrect data is generally rapidly fixed. Choosing not to show recently-added works guards against the possibility that someone made a mistake or intentionally vandalized the series.

    • <ordering> houses all the information about the book's ordering.
      • <groupedorder> This is the work's place in the order, counting from 1, when the works are shown in groups. This is the recommended order and the order used by Syndetics Unbound. It is the same as <order>, above.
      • <ungroupedorder> This is the work's place in the order, counting from 1, when the works are shown in ungrouped order.
      • <label> This is the label to be applied to the ordering. It is sometimes a simple number, like 1, 2 or 3. Other times it's a string like "Book 1" or "Prequel."
      • <showlabel> This is LibraryThing's recommendation of whether or not to show the label, especially in a simple product. It is the value used in Syndetics Unbound. The values are true or false. All of the most common labels are marked as true. Some more obscure ones are not.
    • <group> (required, cannot be repeated) is the containing element for the "group" the work belongs to. The main "group" is called the "Core" group. Many series also have a "Collections and Selections" group. Other groups have a bewildering selection of user-entered groups, such as "Non-Fiction Companions," "Short Stories," "Additional Material." We do not recommend the group names be used by customers. We do recommend that customers distinguish between core and non-core groups. Syndetics Unbound puts a vertical dividing line between the core and a combined non-core section.
      • <id> unique id of the group.
      • <name> name of the group.

The <groups> Section

Example from https://www.librarything.com/nseries/5359/The-Deptford-Trilogy 

<groups>
    <group>
        <id>1</id>
        <name>Core</name>
    </group>
    <group>
        <id>2</id>
        <name>Collections and Selections</name>
    </group> 
</groups>

This is a duplicative section. It contains no information not found in the <works> section, above. However it shows all the groups used within the series in one place, which might be useful.

The <relatedseries> Section

Related series are series that either overlap with the series in question or provide some sort of commentary or response to it. Both types are shown below. We do not recommend customers get into the weeds on this, repeating all our various types ("is parodied in"). But this data can be used to refine a recommendation algorithm or add a simple "related series" section to a page, facilitating discovery.

Example from https://www.librarything.com/nseries/1/Harry-Potter 

<relatedseries>
    <series>
        <id>150</id>
        <name>Harry Potter's Schoolbooks</name>
        <relationship>Contains the subseries</relationship>
        <overlap>6</overlap>
    </series>
    ...
    <series>
        <id>11496</id>
        <name>Barry Trotter</name>
        <relationship>Is parodied in</relationship>
        <overlap>0</overlap>
    </series>
</relatedseries>

Elements and Attributes in the <relatedseries> Section

<relatedseries> is the containing element for all the related series.
  • <series> is repeated, one for each related series.
    • <id> (required) is the id of the related series—the same id used elsewhere for the series.
    • <name> (required) is a "convenience" field for the "default" name. See the <names> section for that series for the complete series-name data.
    • <relationship> (required) describes the relationship between the two series. Options include:
      • Contains the subseries

        The most common relationship

      • Is a reordering of

        This is the relationship used for the two orderings of the Chronicles of Narnia. Although we could have tried to maintain such series as a single series, and given it multiple, independent orders and groups, in the end we felt the flexibility of a separate series was best.

      • Is a sequel to
      • Is a prequel to
      • Is a retelling of
      • Is an adaptation of
      • Is a parody of
      • Was inspired by
    • <overlap> (required) is an integer showing the number of works shared between the two series. For example, a subseries will have overlap, but a parody generally will not.