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:
- Booker Prize ( https://www.librarything.com/award/253/Booker-Prize )
- Indies Choice Book Award ( https://www.librarything.com/award/257/Indies-Choice-Book-Award )
- Davitt Award ( https://www.librarything.com/award/2525/Davitt-Award )
- Academy Award ( https://www.librarything.com/award/2318/Academy-Award )
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 areWorks
,Series
, andAuthor
.<awardtype>
is a field indicating what the type is for this award. Values areAwards
,Distinctions
, andNotable 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.<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.
<approved>
is whether the award has been approved. Values aretrue
andfalse
. 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.<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.- attribute
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.
- attribute
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 arePrimary name
,Nickname
,Historical name
, andOther name
.
<daterange>
(not required) is a field that indicates the date range during which the name was used when<type>
isHistorical name
.- attribute
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 areIs associated with
,Is a successor of
, andIs a predecessor of
.<awardid>
(required) is the unique id of the other award in the given relationship.
- attribute
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.
- attribute
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).
- attribute
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 areWon
andNominated
.<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.
- attribute