AustLit logo
About AustLit

  • The AustLit API BETA Now Released!

    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.
  • Examples: The API in Action

    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

  • Javascript Files Needed

    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>

  • Javascript Calls

    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.

  • API Parameters

    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!

  • JSON Objects

    The API query can only return one data type at a time, either works or agents/authors. The returned objects will have an objectType parameter which specifies the type of object being returned.

  • JSON Work Object

    An array of objects will be returned through the processAustLitAPI function written by the user.

    Each work object may contains the following fields:

    • objectTypeString – This will be "work" for work objects
    • austlitIdString – The unique identifier for the object, used in URLs in the format http://www.austlit.edu.au/austlit/page/[AUSTLIT_ID]
    • titleString – Always present
    • formsString 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.
    • typeString – 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.
    • genresString 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.
    • partOfSeriesArray of String Arrays – If the work is part of a series - each contained array is a double [austlitId, name]
    • containsInSeriesArray of String Arrays – If the work is a series, shows the works in this series - each contained array is a double [austlitId, name]
    • newImages & newImages2Object 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 & oldImages2Object 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".
    • firstLineString - Poems only (form = poetry AND type = single work).
    • mainEditorsArray 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).
    • authorsArray of String Arrays – Each contained array is a double [austlitId, name].
    • directorsArray of String Arrays – Each contained array is a double [austlitId, name]
    • editorsArray of String Arrays – Each contained array is a double [austlitId, name].
    • illustratorsArray of String Arrays – Each contained array is a double [austlitId, name].
    • interviewersArray of String Arrays – Each contained array is a double [austlitId, name].
    • storytellersArray of String Arrays – Each contained array is a double [austlitId, name].
    • translatorsArray of String Arrays – Each contained array is a double [austlitId, name].
    • alternativeTitlesString Array – Will contain zero or more alternative titles.
    • appearsInObject 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".
    • abstractHTML String
    • firstKnownDateString – In the format YYYY
    • placesPublishedArray of String Arrays – Each contained array is a double [austlitId, placeName]
    • publishersArray of String Arrays – Each contained array is a double [austlitId, name]
    • paginationString – The number of pages in the work. May contain non-numerica characters
    • contentsArray 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).
    • extRefString – 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.
    • issueOfString Array – For periodical issues and newspaper issues only: [austlitId, title]
    • volumeString – For periodical issues and newspaper issues only
    • numberString – For periodical issues and newspaper issues only
    • periodString – For periodical issues and newspaper issues only
    • conceptsArray of String Arrays – Each contained array is a double [austlitId, name]
    • subjectWorksArray of String Arrays – Each contained array is a double [austlitId, name]
    • subjectPeopleArray of String Arrays – Each contained array is a double [austlitId, name]
    • settingsPlacesArray of String Arrays – Each contained array is a double [austlitId, name]
    • settingsTimesString Array – When the work is set, usually just a YYYY year.
    • subjectOfArray of String Arrays – The works that talk about this work, including reviews - each contained array is a double [austlitId, name]
  • JSON Agent (Author) Object

    • objectTypeString – This will be "agent" for agent/author objects
    • austlitIdString – The unique identifier for the object, used in URLs in the format http://www.austlit.edu.au/austlit/page/[AUSTLIT_ID]
    • nameString
    • bioHTML String
    • birthYearString – In the format YYYY
    • birthPlaceString Array – [austlitId, name]
    • deathYearString – In the format YYYY
    • newImagesObject 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".
    • oldImagesObject 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...

X