AustLit
-
Explore the AustLit database in a whole new way, using the AustLit API. Please note that this is a preliminary version of the API and major changes will be made in the next 12 months, so please use this for experimentation only, not for production systems. As AustLit is primarily a subscription database, it is understood that the use of this API is for research purposes only, and not for the en masse proliferation of AustLit records.
-
See the AustLit API in action here (patience needed for some browser number crunching!):
BiasEd: Gender bias in Australian publishing: https://www.austlit.edu.au/static/api/biasEd.html
AustLit Title NGrams. Compare the number of occurrences of any two words found in AustLit titles: https://www.austlit.edu.au/static/api/ngrams.html
-
The Javascript for the AustLit API is in this file:
https://www.austlit.edu.au/austlit/static/new/js/austlit-api.js
so this script should be added to your HTML:
<script src="https://www.austlit.edu.au/austlit/static/new/js/austlit-api.js" type="text/javascript"></script>
If your application is not running jQuery, it can be loaded by adding this to your HTML:
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js" type="text/javascript"></script>
-
To use the API, one of two functions can be called.
The user provides a processAustLitAPI function to process the data returned by the API. This function has one mandatory parameter, which is an array of JSON objects returned (as described below in the "JSON Object" section). The passThru parameter is optional, and is the Javascript object provided by the user and passed through the AustLit function.
1. runAustLitAPI(variablesObject, numberOfResults, countFromPoint, passThru, searchType)
This function takes an object that has variables that describe the query, e.g.
runAustLitAPI({ "keyword":"magician", "workForm":"novel" });
The other four parameters are optional, and specify the number of results (defaults to 50), the point from which the results are counted (defaults to 0, i.e. the first result), and a Javascript object that will be passed back to the user as the second parameter in the processAustLitAPI function. The searchType is also optional, and will default to "work" if not specified. To get agent (author) results, specify either "agent" or "author" for this parameter.
2. getAustLitInfo(arrayOfAustLitIds, passThru)
This function takes an array of work or agent ids, e.g.
getAustLitInfo(["C625452","8448404","C389264", "A12345"]);
The other parameter is optional, and is a Javascript object that will be passed back to the user as the second parameter in the processAustLitAPI function.
Both functions return an array of Javascript objects as described below.
-
The variables allowed for the query object sent to runAustLitAPi are:
keyword
authorName
authorId : austlitId of the author
authorBirthYear : Year or Range of Years (YYYY or YYYY-YYYY)
authorBirthPlaceName : eg "Sydney"
authorBirthPlaceId : austlitId of the place
authorGender: must be "female" or "male" or "non-binary" or "unknown" NEW!
workTitle
workForm : must be one of "advertisement", "art work", "autobiography", "bibliography", "biography", "childrens fiction", "column", "correspondence", "criticism", "diary", "drama", "essay", "extract", "fiction unclassified", "film TV", "graphic novel", "index", "information book", "interview", "life story", "lyric song", "multimedia", "musical theatre", "non fiction", "novel", "novella", "obituary", "oral history", "picture book", "poetry", "prose", "radio play", "review", "screenplay", "short story", "thesis".
workGenre : must be one of "adventure", "burlesque", "childrens", "crime", "detective", "fable", "fantasy", "historical fiction", "horror", "humour", "Indigenous story", "manga", "mystery", "myth legend", "opera", "pantomime", "revue revusical", "romance", "satire", "science fiction", "sketch theatrical", "thriller", "travel", "war literature", "western", "young adult".
workType : must be one of "anthology", "collected work", "collection", "extract", "multi chapter work", "newspaper", "newspaper issue", "periodical", "periodical issue", "reference", "selected work", "sequence", "series publisher", "series author", "single work", "website".
workPubDate : Year or Range of Years (YYYY or YYYY-YYYY)
firstKnownDate : Year or Range of Years (YYYY or YYYY-YYYY)
publisherName : name of the publisher of a work
publisherId : austlitId of the publisher of a work
workSubject : Can be a subject such as "Dogs"
workSetting : Can be a place such as "Brisbane"
workSubjectId : Subject as specified by its austlitId
workSettingId : Place as specified by its austlitId
workTemporalSetting : Year or Range of Years (YYYY or YYYY-YYYY)
authorAsSubject : name of the author that is the subject of a work
authorIdAsSubject : austlitId of author that is the subject of a work
containerWorkType: must be "periodical issue", "newspaper issue", "selected work" or "anthology" NEW!
-
An array of objects will be returned through the processAustLitAPI function written by the user.
Each work object may contains the following fields:
- objectType – String – This will be "work" for work objects
- austlitId – String – The unique identifier for the object, used in URLs in the format http://www.austlit.edu.au/austlit/page/[AUSTLIT_ID]
- title – String – Always present
- forms – String Array – Will contain zero or more of the following: advertisement, art work, autobiography, bibliography, biography, childrens fiction, column, correspondence, criticism, diary, drama, essay, extract, fiction unclassified, film/TV, graphic novel, index, information book, interview, life story, lyric/song, multimedia, musical theatre, non-fiction, novel, novella, obituary, oral history, picture book, poetry, prose, radio play, review, screenplay, short story, thesis.
- type – String – Will contain one of the following: anthology, collected work, collection, extract, multi chapter work, newspaper, newspaper issue, periodical, periodical issue, reference, selected work, sequence, series publisher, series author, single work, website.
- genres – String Array – Will contain zero or more of the following: adventure, burlesque, childrens, crime, detective, fable, fantasy, historical fiction, horror, humour, Indigenous story, manga, mystery, myth legend, opera, pantomime, revue revusical, romance, satire, science fiction, sketch theatrical, thriller, travel, war literature, western, young adult.
- partOfSeries – Array of String Arrays – If the work is part of a series - each contained array is a double [austlitId, name]
- containsInSeries – Array of String Arrays – If the work is a series, shows the works in this series - each contained array is a double [austlitId, name]
- newImages & newImages2 – Object Array – May be empty. Each object will contain the following attributes: "fileName" (full image), "thumbnail" (image shown on AustLit pages), and may contain these attributes: , "smaller" (sized between full size and thumbnail), "caption", "note".
- oldImages & oldImages2 – Object Array – May be empty. Each object will contain the following attributes: "NLAImage" (if taken from NLA – will be "http://nla.gov.au/nla.pic–t" if no NLA image exists), "fileName" (full image), "thumbnail" (image shown on AustLit pages, may just be http://www.austlit.edu.au/images/austLit/ if no image is available), "caption".
- firstLine – String - Poems only (form = poetry AND type = single work).
- mainEditors – Array of Objects – Each object contains a date attribute, and an editors attribute, which is an array of doubles [austlitid, name]. This is found in newspaper and periodical issues only (type = periodical issue OR type = newspaper issue).
- authors – Array of String Arrays – Each contained array is a double [austlitId, name].
- directors – Array of String Arrays – Each contained array is a double [austlitId, name]
- editors – Array of String Arrays – Each contained array is a double [austlitId, name].
- illustrators – Array of String Arrays – Each contained array is a double [austlitId, name].
- interviewers – Array of String Arrays – Each contained array is a double [austlitId, name].
- storytellers – Array of String Arrays – Each contained array is a double [austlitId, name].
- translators – Array of String Arrays – Each contained array is a double [austlitId, name].
- alternativeTitles – String Array – Will contain zero or more alternative titles.
- appearsIn – Object Array – Details of any publication in which the main work appears and the page number it appears on or the URL. Each object may have the following attributes: "austlitId", "title", "ISSN" , "volume", "number", "period", "editors" (array of austlitId/name doubles), "placesPublished" (array of austlitId/placeName doubles), "publishers" (array of austlitId/name doubles), "ISBN", "pageInfo", "extRef".
- abstract – HTML String
- firstKnownDate – String – In the format YYYY
- placesPublished – Array of String Arrays – Each contained array is a double [austlitId, placeName]
- publishers – Array of String Arrays – Each contained array is a double [austlitId, name]
- pagination – String – The number of pages in the work. May contain non-numerica characters
- contents – Array of Objects – Each object contains a work attribute (a double [austlitId,title]), an authors attribute (an array of doubles [austlitId,name]), and a pageNum attribute (String - not always a number).
- extRef – String – A link to this work when it is not part of another publication. If it appears within another publication, the link will be found in the "extRef" attribute of the "appearsIn" object.
- issueOf – String Array – For periodical issues and newspaper issues only: [austlitId, title]
- volume – String – For periodical issues and newspaper issues only
- number – String – For periodical issues and newspaper issues only
- period – String – For periodical issues and newspaper issues only
- concepts – Array of String Arrays – Each contained array is a double [austlitId, name]
- subjectWorks – Array of String Arrays – Each contained array is a double [austlitId, name]
- subjectPeople – Array of String Arrays – Each contained array is a double [austlitId, name]
- settingsPlaces – Array of String Arrays – Each contained array is a double [austlitId, name]
- settingsTimes – String Array – When the work is set, usually just a YYYY year.
- subjectOf – Array of String Arrays – The works that talk about this work, including reviews - each contained array is a double [austlitId, name]
-
- objectType – String – This will be "agent" for agent/author objects
- austlitId – String – The unique identifier for the object, used in URLs in the format http://www.austlit.edu.au/austlit/page/[AUSTLIT_ID]
- name – String
- bio – HTML String
- birthYear – String – In the format YYYY
- birthPlace – String Array – [austlitId, name]
- deathYear – String – In the format YYYY
- newImages – Object Array – May be empty. Each object will contain the following attributes: "fileName" (full image), "thumbnail" (image shown on AustLit pages), and may contain these attributes: , "smaller" (sized between full size and thumbnail), "caption", "note".
- oldImages – Object Array – May be empty. Each object will contain the following attributes: "NLAImage" (if taken from NLA – will be "http://nla.gov.au/nla.pic–t" if no NLA image exists), "fileName" (full image), "thumbnail" (image shown on AustLit pages, may just be http://www.austlit.edu.au/images/austLit/ if no image is available), "caption".
You might be interested in...