Awards

Awards

Filename: awards.xml

Sample Feed: awards_small.xml

Contents and Purpose

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

Recommended Background

LibraryThing's awards 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 awards operate. Some useful examples:

Scope

Basic Structure

Example from https://www.librarything.com/award/253/Booker-Prize 

<awardslist>
    <award id="253">
        <name>Booker Prize</name>
		<appliesto>Work</appliesto>
		<awardtype>Awards</awardtype>
		<hascategories>false</hascategories>
		<hasstages>true</hasstages>
		<hasorder>false</hasorder>
		<hasnotes>false</hasnotes>
		<multidate>true</multidate>
		<approved>true</approved>
		<url>https://www.librarything.com/award/253/Booker-Prize</url>
		<workcount>530</workcount>
        
        <organization id="2">
        ...
		</organization>
		<announcements>
		...
		</announcements>
        <names>
        ...
        </names>
        <relationships>
        ...
        </relationships>
        <stages>
        ...
        </stages>
        <categories>
        ...
        </categories>
        <works>
        ...
        </works>
        <links>
        ...
        </links>
        <history>
        ...
        </history>
    </award>
</awardslist>

Elements and Attributes in The Basic Structure

<awardslist> is the top-level element.
  • <award> is repeated, one for each award in the system.
    • attribute id="#" (required) is the unique id of the award.
    • <name> is a field for the "default" name. See the <names> section for the complete award-name data.
    • <appliesto> is a field indicating to what the award applies. Values are Works, Series, and Author.
    • <awardtype> is a field indicating what the type is for this award. Values are Awards, Distinctions, and Notable Lists. (See explanation on LibraryThing's wiki https://wiki.librarything.com/index.php/HelpThing:Awards_and_Honors.)
    • <hascategories> is a field indicating if works associated with this award can have categories defined.
    • <hasstages> is a field indicating if works associated with this award can have stages defined.
    • <hasorder> is a field indicating if works associated with this award can have an order string defined.
    • <hasnotes> is a field indicating if works associated with this award can have notes defined.
    • <multidate> is a field indicating if works associated with this award can have a year defined.
    • <awarddate> is an optional field indicating the year in which the award was awarded if it was only awarded once.

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

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

    • <workcount> is a field indicating the number of works associated with this award.
    • <importance> is a field indicating a rough, subjective measure of the importance of the award.
    • <membercount> is a field indicating the number of members who have cataloged works associated with this award.

      • <organization> ... </organization> is a structure for the organization that sponsors the award.

      <announcements> ... </announcements> is a structure for any announcements associated with the award which can be used to indicate which awards have been recently announced, e.g., winners or nominees.

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

      <relationships> ... </relationships> is a structure for indicating any relationships that exist between awards.

      <stages> ... </stages> is a structure for the stages that are associated with works within this award (e.g., winner, nominee, shortlist, longlist).

      <categories> ... </categories> is a structure for the categories that are associated with works within this award (e.g., Literature, Non-Fiction, etc.).

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

      <links> ... </link> is a structure for links that are associated with this award (e.g., official home pages or announcements).

      <history> ... </history> is a structure for the history of awards that were combined into this award.

The <organization> Section

Example from https://www.librarything.com/award/2318/Academy-Award 

<organization id="1">
	<name>Academy of Motion Picture Arts and Sciences</name>
	<country>United States of America</country>
	<names>
		<name id="1">
			<wording>Academy of Motion Picture Arts and Sciences</wording>
			<language>English</language>
			<type>Primary name</type>
		</name>
		...
		<name id="3">
			<wording>AMPAS</wording>
			<language>English</language>
			<type>Other name</type>
		</name>
	</names>
	<links>
		<link id="754324">
			<shortname>Wikipedia</shortname>
			<url>https://en.wikipedia.org/wiki/Academy_of_Motion_Picture_Arts_and_Sciences</url>
		</link>
	</links>
</organization>

Elements and Attributes in the <organization> Section

<organization> is the containing element for the award organization.
  • attribute id="#" (required) is the unique id of the organization.
  • <name> (required) is the default name of the organization. See the <names> section for the complete organization-name data.
  • <country> (not required) is the country of the organization.
  • <names> is the containing element for all the names of the organization. See the <names> section for awards for field explanations.
  • <links> is the containing element for all the links associated with the organization. See the <links> section for awards for field explanations.

The <announcements> Section

Example from https://www.librarything.com/award/253/Booker-Prize 

<announcements>
	<announcement id="7">
		<stamp>11/26/2023</stamp>
		<awardyear>2023</awardyear>
		<stages>
			<stage id="1">
				<name>Winner</name>
			</stage>
		</stages>
	</announcement>
	...
	<announcement id="9">
		<stamp>10/17/2022</stamp>
		<awardyear>2022</awardyear>
		<stages>
			<stage id="1">
				<name>Winner</name>
			</stage>
		</stages>
	</announcement>
</announcements>

Elements and Attributes in the <announcements> Section

<announcements> is the containing element for all the award announcements.
  • <announcement> is repeated, one for each award announcement.
    • attribute id="#" (required) is the unique id of the announcement.
    • <stamp> (required) is the date of the announcement.
    • <awardyear> (required) is the year being awarded in this announcement.
    • <stages> (not required) is containing element for all the stages being awarded in this announcement. See the <stages> section for awards for field explanations.
    • <categories> (not required) is containing element for all the categories being awarded in this announcement. See the <categories> section for awards for field explanations.

The <names> Section

Example from https://www.librarything.com/award/253/Booker-Prize 

<names>
	<name id="253">
		<wording>Booker Prize</wording>
		<language>English</language>
		<type>Primary name</type>
	</name>
	...
	<name id="13712">
		<text>Man Booker Prize</text>
		<language>English</language>
		<type>Historical name</type>
		<daterange>2002–2019</daterange>
	</name>
</names>

Elements and Attributes in the <names> Section

<names> is the containing element for all the award names.
  • <name> is repeated, one for each award name.
    • attribute id="#" (required) is the unique id of the name.
    • <wording> (required) is the name of the award.
    • <language> (required) is the language of the name. There can be more than one name per language.
    • <type> (required) is the type of the name. Values are Primary name, Nickname, Historical name, and Other name.

      • <daterange> (not required) is a field that indicates the date range during which the name was used when <type> is Historical name.

The <relationships> Section

Example from https://www.librarything.com/award/257/Indies-Choice-Book-Award 

<relationships>
	<relationship id="28">
		<type>Is associated with</type>
		<awardid>1687</awardid>
	</relationship>
	<relationship id="31">
		<type>Is a successor of</type>
		<awardid>239</awardid>
	</relationship>
</relationships>

Elements and Attributes in the <relationships> Section

<relationships> is the containing element for all the award relationships.
  • <relationship> is repeated, one for each award relationship.
    • attribute id="#" (required) is the unique id of the relationship.
    • <type> (required) is the type of relationship. Values are Is associated with, Is a successor of, and Is a predecessor of.
    • <awardid> (required) is the unique id of the other award in the given relationship.

The <stages> Section

Example from https://www.librarything.com/award/253/Booker-Prize 

<stages>
	<stage id="1">
		<name>Winner</name>
		<count>101</count>
	</stage>
	...
	<stage id="3">
		<name>Longlist</name>
		<count>194</count>
	</stage>
</stages>

Elements and Attributes in the <stages> Section

<stages> is the containing element for all the award stages. Works can have multiple stages associated with the same row.
  • <stage> is repeated, one for each stage.
    • attribute id="#" (required) is the unique id of the stage.
    • <name> (required) is the name of the stage.
    • <count> (required) is the number of works in this award with which this stage is associated.

The <categories> Section

Example from https://www.librarything.com/award/2525/Davitt-Award 

<categories>
	<category id="12996">
		<name>Adult Crime Fiction</name>
		<count>7</count>
		<approval>0</approval>
	</category>
	<category id="3365">
		<name>Adult Fiction</name>
		<count>61</count>
		<approval>1</approval>
	</category>
	...
	<category id="4510">
		<name>True Crime</name>
		<count>27</count>
		<approval>1</approval>
	</category>
	<category id="2656">
		<name>Young Adult Novel</name>
		<count>41</count>
		<approval>-1</approval>
	</category>
</categories>

Elements and Attributes in the <categories> Section

<categories> is the containing element for all the award categories.
  • <category> is repeated, one for each category.
    • attribute id="#" (required) is the unique id of the category.
    • <name> (required) is the name of the category.
    • <count> (required) is the number of works in this award with which this category is associated.
    • <approval> (required) is a value indicating if the category has been approved (1=approved, -1=rejected, 0=not approved or rejected).

The <works> Section

Example from https://www.librarything.com/award/2318/Academy-Award 

<works>
	<work id="407900">
		<workcode>29841499</workcode>
		<result>Won</result>
		<stages>
			<stage id="1">
				<name>Winner</name>
			</stage>
			<stage id="2">
				<name>Nominee</name>
			</stage>
		</stages>
		<category>Best Actor</category>
		<year>2022</year>
		<note>Brendan Fraser</note>
	</work>
    ...
    <work id="404575">
		<workcode>4546229</workcode>
		<result>Nominated</result>
		<stages>
			<stage id="2">
				<name>Nominee</name>
			</stage>
		</stages>
		<category>Best Adapted Screenplay</category>
		<year>1927</year>
		<note>play & short story "The Day of Atonement" by Samson Raphaelson</note>
	</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) is the "workcode," or work id, of the work in the award.
    • <result> (not required) is a field that indicates a simple result of this award. Values are Won and Nominated.
    • <stages> (not required) is the containing element for all the stages associated with this work within the award. See the <stages> section for awards for field explanations.
    • <category> (not required) is the category associated with this work within the award.
    • <year> (not required) is the year associated with this work within the award.
    • <orderstring> (not required) is the order associated with this work within the award.
    • <note> (not required) is the note associated with this work within the award.

The <links> Section

Example from https://www.librarything.com/award/253/Booker-Prize 

<links>
	<link id="753360">
		<wording>Wikipedia</wording>
		<url>https://en.wikipedia.org/wiki/Booker_Prize</url>
	</link>
	<link id="753361">
		<wording>Sponsor</wording>
		<url>https://thebookerprizes.com</url>
	</link>
</links>

Elements and Attributes in the <links> Section

<links> is the containing element for all the award links.
  • <link> is repeated, one for each award link.
    • attribute id="#" (required) is the unique id of the link.
    • <wording> (required) is the text of the name of the link.
    • <url> (required) is the url of the link.