Books and Borrowing API V1

• Libraries
  
• Library
  
• Library Top Tens
  
• Borrowers
  
• Borrower
  
• Borrower Titles
  
• Borrower Occupations
  
• Borrower Settlement
  
• Borrower Street
  
• Borrowings Through Time
  
• Book Holdings
  
• Book Holding
  
• Book Editions
  
• Book Edition
  
• Book Work
  
• Author
  
• Genre
  
• Book Edition ESTC
  
• Book Edition Language
  
• Book Edition Publication Place
  
• Book Edition Formats
  
• Book Edition Publication Date Range
  
• Borrower Borrowing Range
  
• Books Autocomplete
  
• Book Editions Autocomplete
  
• Book Holding Borrowings
  
• Book Edition Borrowings
  
• Book Counts By Initial Letter of Title / Author
  
• Borrower Counts By Initial Letter of Surname
  
• Library Registers
  
• Library Register
  
• Library Register Page
  
• Search
  
• Search Results
  
• On This Day
  

All Libraries

Returns summary data for all libraries in the system, or a simple list of library names and IDs.

Arguments:

1. Data type: Should be json or csv. Mandatory.
2. Endpoint identifier libraries. Mandatory.
3. Either the string 'names' to return only names and IDs or blank to return all data. Optional.

Examples:

1. Data for all libraries as a JSON file:
   https://borrowing.stir.ac.uk/api/v1/json/libraries
2. Data for all libraries as a CSV file:
   https://borrowing.stir.ac.uk/api/v1/csv/libraries
3. Name / ID data for all libraries as a JSON file:
   https://borrowing.stir.ac.uk/api/v1/json/libraries/names

Specific Library

Returns summary data for a specific library, identified either by a numeric ID or non-numeric 'slug'.

Arguments:

1. Data type: Should be json or csv. Mandatory.
2. Endpoint identifier library. Mandatory.
3. Either the numeric library ID (lid) OR library slug. Mandatory.

Examples:

1. Data for Advocates library identified by its LID (28) as a JSON file:
   https://borrowing.stir.ac.uk/api/v1/json/library/28
2. Data for Advocates library identified by its slug (advocates) as a CSV file:
   https://borrowing.stir.ac.uk/api/v1/csv/library/advocates

Library Top Tens

Returns summary facts and figures for all libraries or one or more selected libraries identified by slug or numeric ID

Arguments:

1. Data type: Should be json or csv. Mandatory.
2. Endpoint identifier libraryTopTens. Mandatory.
3. One or more library ID (lid) or library slug separated by a bar (|) OR 'all' for all libraries. Mandatory

Examples:

1. Data for all libraries as a JSON file:
   https://borrowing.stir.ac.uk/api/v1/json/libraryTopTens/all
2. Data for Chambers and Advocates libraries identified by their slugs as a JSON file:
   https://borrowing.stir.ac.uk/api/v1/json/libraryTopTens/chambers|advocates
3. Data for Advocates library identified by LID as a CSV file
   https://borrowing.stir.ac.uk/api/v1/csv/libraryTopTens/28

Library Borrowers

Returns a list of borrowers, including counts of borrowings, normalised occupations, additional fields and xrefs for a specific library, identified either by a numeric ID or non-numeric 'slug', or for all libraries by passing 'All'. A subset of borrowers with surnames beginning with a specific letter can also be returned.

Arguments:

1. Data type: Should be json or csv. Mandatory.
2. Endpoint identifier borrowers. Mandatory.
3. Either the numeric library ID (lid) OR library slug (multiple can be passed separated by a bar (|)) OR 'All'. Mandatory.
4. Order type. Must be 'surname' or 'borrowings'. Mandatory
5. Initial letter of surname (e.g. A) or 'Other' for surnames that do not begin A-Z. Optional
6. Date range when borrower was active, consisting of start year and end year separated by a dash (e.g. 1750-1760). Optional or null if a further option is provided.
7. Gender. Either 'Male', 'Female', 'Unclear' or 'Unknown'. Optional

Examples:

1. Data for Chambers library identified by its LID (41) ordered by surname (all data) as a JSON file:
   https://borrowing.stir.ac.uk/api/v1/json/borrowers/41/surname
2. Data for borrowers with surnames beginning with 'S' at the Royal High School identified by its slug as a JSON file:
   https://borrowing.stir.ac.uk/api/v1/json/borrowers/royal-high-school-edinburgh/surname/S
3. Top 100 borrowers at the Advocates Library identified by its slug as a JSON file:
   https://borrowing.stir.ac.uk/api/v1/json/borrowers/advocates/borrowings
4. Data for Chambers library identified by its slug (chambers) as a CSV file:
   https://borrowing.stir.ac.uk/api/v1/csv/borrowers/chambers/surname

Library Borrower

Returns the details for a single borrower, including counts of borrowings, normalised occupations, additional fields and xrefs

Arguments:

1. Data type: Should be json or csv. Mandatory.
2. Endpoint identifier borrower. Mandatory.
3. Numeric borrower ID. Mandatory

Examples:

1. Data for borrower ID 26366 as a JSON file:
   https://borrowing.stir.ac.uk/api/v1/json/borrower/26636

Library borrower titles

Returns a list of distinct borrower titles, including counts of the number of borrowers with each.

Arguments:

1. Data type: Should be json or csv. Mandatory.
2. Endpoint identifier borrowerTitles. Mandatory.

Examples:

1. Borrower titles as a JSON file:
   https://borrowing.stir.ac.uk/api/v1/json/borrowerTitles

Library borrower occupations

Returns a hierarchical list of borrower occupations with counts of associated borrowers

Arguments:

1. Data type: Should be json or csv. Mandatory.
2. Endpoint identifier borrowerOccupations. Mandatory.
3. Borrower active period (e.g. 1750-1800). Optional or 'null' if gender included
4. Borrower gender (Male, Female, Unknown, Unclear). Optional or 'null' if library included
5. Library (slug or ID). Optional

Examples:

1. Borrower occupations as a JSON file:
   https://borrowing.stir.ac.uk/api/v1/json/borrowerOccupations

Library borrower settlement

For use in the autocomplete. Returns a list of settlements that feature the passed string anywhere in the settlement name

Arguments:

1. Data type: Should be json or csv. Mandatory.
2. Endpoint identifier borrowerSettlement. Mandatory.
3. Search string of at least two characters. Mandatory

Examples:

1. Borrower settlements containing the text 'black':
   https://borrowing.stir.ac.uk/api/v1/json/borrowerSettlement/black

Library borrower street

For use in the autocomplete. Returns a list of streets that feature the passed string anywhere in the street name

Arguments:

1. Data type: Should be json or csv. Mandatory.
2. Endpoint identifier borrowerStreet. Mandatory.
3. Search string of at least two characters. Mandatory

Examples:

1. Borrower streets containing the text 'king':
   https://borrowing.stir.ac.uk/api/v1/json/borrowerStreet/king

Borrowings Through Time

The number of borrowings at a library or libraries over time, grouped by top-level occupation and further split by second-level occupation, with the unit of time either being year, or if a year is specified by month within the year.

Arguments:

1. Data type: Should be json or csv. Mandatory.
2. Endpoint identifier borrowingsThroughTime. Mandatory.
3. Unit of time: Either ‘null’ for years or a specific year for months within the year. Mandatory
4. Grouping type: ‘occupation’ or ‘genre’. Mandatory
5. One or more library ID (lid) or library slug separated by a bar (|) OR 'all' for all libraries. Mandatory

Examples:

1. Borrowings through time for occupations at Wigtown library, identified by slug, returning JSON data:
   https://borrowing.stir.ac.uk/api/v1/json/borrowingsThroughTime/null/occupation/wigtown
2. Borrowings through time for months in the year 1790 for all occupations at all libraries, returning CSV data:
   https://borrowing.stir.ac.uk/api/v1/csv/borrowingsThroughTime/1790/occupation/all

Book Holdings

Returns a list of books, including book items, counts of borrowings, additional fields and associated editions / works for a specific library, identified either by a numeric ID or non-numeric 'slug'. Only returns a subset, either alphabetically by initial letter or author surname, or the most borrowed books (currently limited to returning the top 100 books).

Arguments:

1. Data type: Should be json or csv. Mandatory.
2. Endpoint identifier books. Mandatory.
3. Either the numeric library ID (lid) OR library slug. Mandatory.
4. Order type. Must be 'title', 'author' or 'borrowings'. Mandatory
5. The initial letter to return books for (captital A-Z) or 'Other' for book titles / author names that don't begin with an A-Z character. Optional. If omitted for 'title' or 'author' then 'A' will be returned.

Examples:

1. Data for Chambers library books with titles beginning with 'A', with the library identified by its LID (41) as a JSON file:
   https://borrowing.stir.ac.uk/api/v1/json/books/41/title/A
2. Data for Chambers library books that are the 100 most borrowed with library identified by its slug (chambers) as a CSV file:
   https://borrowing.stir.ac.uk/api/v1/csv/books/chambers/borrowings

Book Holding

Returns data for a book holding identified by ID, including book items, counts of borrowings, additional fields and associated editions / works

Arguments:

1. Data type: Should be json or csv. Mandatory.
2. Endpoint identifier bookHolding. Mandatory.
3. Numeric Book Holding ID (bhid).

Examples:

1. Data for bhid 34688 as a JSON file:
   https://borrowing.stir.ac.uk/api/v1/json/bookHolding/34688

Book Editions

Returns a list of book editions, including works, authors and total number of borrowings for book editions. Only returns a subset, either alphabetically by initial letter or author surname, or the most borrowed books (currently limited to returning the top 100 books). A publication date range and a limit to one or more genres can also be supplied

Arguments:

1. Data type: Should be json or csv. Mandatory.
2. Endpoint identifier bookEditions. Mandatory.
3. Order type. Must be 'title', 'author' or 'borrowings'. Mandatory
4. The initial letter to return books for (captital A-Z) or 'Other' for book titles / author names that don't begin with an A-Z character. Optional, but '0' or 'null' must be specified if a range is included. If omitted for 'title' or 'author' then 'A' will be returned.
5. Publication date range. Optional, or a mandatory 'null' if no date range but genre is supplied. If supplied must be a start year and an end year separated by a dash (e.g. 1700-1750)
6. Genre. Optional. If supplied must be one or more numerical genre IDs, separated by a bar (|)

Examples:

1. Data for book editions with titles beginning with 'A' as a JSON file:
   https://borrowing.stir.ac.uk/api/v1/json/bookEditions/title/A
2. Data for the 100 most borrowed book editions as a CSV file:
   https://borrowing.stir.ac.uk/api/v1/csv/bookEditions/borrowings

Book Edition

Returns data for a book edition identified by ID, including book work and authors

Arguments:

1. Data type: Should be json or csv. Mandatory.
2. Endpoint identifier bookEdition. Mandatory.
3. Numeric Book Edition ID (beid).

Examples:

1. Data for beid 580 as a JSON file:
   https://borrowing.stir.ac.uk/api/v1/json/bookEdition/580

Book Work

Returns data for a book work identified by ID, including authors

Arguments:

1. Data type: Should be json or csv. Mandatory.
2. Endpoint identifier bookWork. Mandatory.
3. Numeric Book Work ID (bwid).

Examples:

1. Data for bwid 16 as a JSON file:
   https://borrowing.stir.ac.uk/api/v1/json/bookWork/16

Author

Returns data for an author identified by ID

Arguments:

1. Data type: Should be json or csv. Mandatory.
2. Endpoint identifier author. Mandatory.
3. Numeric authorID (aid).

Examples:

1. Data for aid 419 as a JSON file:
   https://borrowing.stir.ac.uk/api/v1/json/author/419

Genre

Returns a list of all genres, or data for a single genre identified by ID

Arguments:

1. Data type: Should be json or csv. Mandatory.
2. Endpoint identifier genre. Mandatory.
3. Numeric genre ID (gid). Optional

Examples:

1. A list of all genres as a JSON file:
   https://borrowing.stir.ac.uk/api/v1/json/genre/
2. Data for gid 1 as a JSON file:
   https://borrowing.stir.ac.uk/api/v1/json/genre/1

Book Edition ESTC

For use in the autocomplete. Returns a list of ESTC IDs that begin with the passed string

Arguments:

1. Data type: Should be json or csv. Mandatory.
2. Endpoint identifier ESTC. Mandatory.
3. Search string of at least two characters. Mandatory

Examples:

1. ESTC IDs beginning T1001:
   https://borrowing.stir.ac.uk/api/v1/json/ESTC/T1001

Book Edition Language

Returns a list of distinct book edition languages, including counts of the number of book editions with each

Arguments:

1. Data type: Should be json or csv. Mandatory.
2. Endpoint identifier bookEditionLanguages. Mandatory.

Examples:

1. Book edition languages:
   https://borrowing.stir.ac.uk/api/v1/json/bookEditionLanguages

Book Edition Publication Place

For use in the autocomplete. Returns a list of publication placesthat feature the passed string anywhere in the publication place

Arguments:

1. Data type: Should be json or csv. Mandatory.
2. Endpoint identifier bookEditionPublicationPlace. Mandatory.
3. Search string of at least two characters. Mandatory

Examples:

1. Book edition publication places featuring the text 'lon':
   https://borrowing.stir.ac.uk/api/v1/json/bookEditionPublicationPlace/lon

Book edition formats

Returns a list of distinct book edition formats, including counts of the number of editions with each.

Arguments:

1. Data type: Should be json or csv. Mandatory.
2. Endpoint identifier bookEditionFormats. Mandatory.

Examples:

1. Book edition formats as a JSON file:
   https://borrowing.stir.ac.uk/api/v1/json/bookEditionFormats

Book edition publication date range

Returns the earliest and latest publication dates for book editions. Used in the range option on the book edition page.

Arguments:

1. Data type: Should be json or csv. Mandatory.
2. Endpoint identifier bookEditionPubdateRange. Mandatory.

Examples:

1. Publication date range as a JSON file:
   https://borrowing.stir.ac.uk/api/v1/json/bookEditionPubdateRange

Borrower borrowing range

Returns the earliest and latest borrowing dates. Used in the range option on the borrower page.

Arguments:

1. Data type: Should be json or csv. Mandatory.
2. Endpoint identifier borrowerBorrowingRange. Mandatory.

Examples:

1. Borrowing range as a JSON file:
   https://borrowing.stir.ac.uk/api/v1/json/borrowerBorrowingRange

Books Autocomplete

Returns a list of book holding titles (and number of borrowing counts) that match the passed string for a specified library. For use in the autocomplete on the library ‘facts’ page.

Arguments:

1. Data type: Should be json or csv. Mandatory.
2. Endpoint identifier booksAutocomplete. Mandatory.
3. Library slug or numeric ID OR NULL for all libraries. Mandatory
4. String of at least two characters. Mandatory

Examples:

1. Book holdings containing the string 'rome' at Aberdeen library identified by slug
   https://borrowing.stir.ac.uk/api/v1/json/booksAutocomplete/aberdeen-theological/rome

Book Editions Autocomplete

Returns a list of book edition titles (and number of borrowing counts) that match the passed string for one or more specified libraries. For use in the autocomplete on the site-wide ‘facts’ page.

Arguments:

1. Data type: Should be json or csv. Mandatory.
2. Endpoint identifier bookEditionsAutocomplete. Mandatory.
3. One or more library slugs or numeric IDs separated by a bar (|) OR NULL or ALL for all libraries. Mandatory
4. String of at least two characters. Mandatory

Examples:

1. Book editions containing the string 'egypt' at Chambers or Advocates libraries identified slug
   https://borrowing.stir.ac.uk/api/v1/json/bookEditionsAutocomplete/chambers|advocates/egypt

Book Holding Borrowings

For a given book holding ID, returns count of the number of borrowings per year

Arguments:

1. Data type: Should be json or csv. Mandatory.
2. Endpoint identifier holdingBorrowings. Mandatory.
3. Book Holding ID. Mandatory

Examples:

1. Borrowings per year for the book holding with BHID 35177
   https://borrowing.stir.ac.uk/api/v1/json/holdingBorrowings/35177

Book Edition Borrowings

For a given book edition ID at one or more libraries, returns count of the number of borrowings per year

Arguments:

1. Data type: Should be json or csv. Mandatory.
2. Endpoint identifier editionBorrowings. Mandatory.
3. One or more library slugs or numeric IDs separated by a bar (|) OR NULL or ALL for all libraries. Mandatory
4. Book Edition ID. Mandatory

Examples:

1. Borrowings per year for the book edition with BEID 4444 at all libraries
   https://borrowing.stir.ac.uk/api/v1/json/editionBorrowings/all/4444

Library book counts by initial letter of title / author

Returns a count of books by initial letter of the title or author to be used in the letter selection tabs

Arguments:

1. Data type: Should be json or csv. Mandatory.
2. Endpoint identifier bookCount. Mandatory.
3. Either the numeric library ID (lid) OR library slug OR the string 'Edition' to return editions rather than the holdings for a specific library. Mandatory.
4. Order type. Must be 'title' or 'author'. Mandatory
5. Date range. Optional unless a genre is specified in which case 'null' should be used if no date is required. Dates must consist of a start year and an end year separated by a dash
6. Genre. Optional. One or more numeric genre IDs separated by a bar (|)

Examples:

1. Counts of books for Chambers library identified by its LID (41) when books are ordered by initial letter of their title as a JSON file:
   https://borrowing.stir.ac.uk/api/v1/json/bookCount/41/title
2. Counts of books for Chambers library identified by its slug (chambers) when books are ordered by initial letter of author surname as a CSV file:
   https://borrowing.stir.ac.uk/api/v1/csv/bookCount/chambers/author

Library borrower counts by initial letter of surname

Returns a count of borrowers by initial letter of surname to be used in the letter selection tabs

Arguments:

1. Data type: Should be json or csv. Mandatory.
2. Endpoint identifier borrowerCount. Mandatory.
3. Either the numeric library ID (lid) OR library slug OR 'All'. Mandatory.
4. Order type. Must be 'title' or 'author'. Mandatory
5. Date range when borrower was active, consisting of start year and end year separated by a dash (e.g. 1750-1760). Optional or null if a further option is provided.
6. Gender. Either 'Male', 'Female', 'Unclear' or 'Unknown'. Optional

Examples:

1. Counts of borrowers for Royal High School identified by its slug as a JSON file:
   https://borrowing.stir.ac.uk/api/v1/json/borrowerCount/royal-high-school-edinburgh

Library registers

Returns a list of registers, including counts of pages, books, borrowers and borrowings, identified either by a numeric ID or non-numeric 'slug'.

Arguments:

1. Data type: Should be json or csv. Mandatory.
2. Endpoint identifier registers. Mandatory
3. Either the numeric library ID (lid) OR library slug. Optional. If omitted data will be returned for every library register

Examples:

1. Data for Chambers library identified by its LID (41) as a JSON file:
   https://borrowing.stir.ac.uk/api/v1/json/registers/41
2. Data for Chambers library identified by its slug (chambers) as a CSV file:
   https://borrowing.stir.ac.uk/api/v1/csv/registers/chambers

Library register

Returns a list of pages for a specified register, identified by a numeric ID

Arguments:

1. Data type: Should be json or csv. Mandatory.
2. Endpoint identifier register. Mandatory.
3. Numeric register ID (rid)

Examples:

1. Data for Leighton library 'Ledger 1' as a JSON file:
   https://borrowing.stir.ac.uk/api/v1/json/register/15
2. Data for Leighton library 'Ledger 1' as a CSV file:
   https://borrowing.stir.ac.uk/api/v1/csv/register/15

Library register page

Returns a list of borrowing records and associated data for a specific register page, identified by numeric ID

Arguments:

1. Data type: Should be json or csv. Mandatory.
2. Endpoint identifier page. Mandatory.
3. Numeric page ID (pid)

Examples:

1. Data for the page with ID 768 as a JSON file:
   https://borrowing.stir.ac.uk/api/v1/json/page/768
2. Data for the page with ID 768 as a CSV file:
   https://borrowing.stir.ac.uk/api/v1/csv/page/768

Search

Returns a list of borrowing record IDs for a specified quick or advanced search text string. To retrieve the full data for the borrowings a subset of the returned IDs should be queried against the searchResults endpoint as described below. A quick search searches the following fields:

• Author forename
• Author surname
• Book work title
• Book edition title
• Book edition language
• Book edition publication place
• Book edition ESTC
• Book edition format
• Book edition genre
• Book holding original title
• Book holding standardised title
• Borrower forename
• Borrower surname
• Borrower normalised occupation
• Borrowing transcription
• Borrowing date of borrowing (search string must be in the format yyyy-mm-dd or yyyy-mm-dd_yyyy-mm-dd for a range. Dates can omit -mm-dd or -dd)

Arguments:

1. Data type: Should be json or csv. Mandatory.
2. Endpoint identifier search. Mandatory.
3. start point. Either 0 or a multiple of 100. Defines which subset of data to return. Mandatory
4. Filter query. Either 0 or a filter query as chosen by selecting a facet on the search results page, consisting of the type and the value separated by a bar, with multiple pairings separated by two bars, e.g. 'byear|1750||pubplaces|London'. Mandatory
5. Sort. Either 0 (by library, register, page), sortDate (borrowing date), sortBname (borrower name), sortBocc (borrower occupation), sortAname (author name) or sortEdtitle (edition title)
6. search type (either 'quick', 'simple' or 'advanced'. Mandatory
7. Any number of search srings. Mandatory. Must consist of a search field and a value separated by a bar (|). For quick search the search field should be omitted and the value used on its own.

Examples:

1. All borrowing records between February 1790 and September 1792 inclusive:
   https://borrowing.stir.ac.uk/api/v1/json/search/0/0/0/quick/1790-02_1792-09
2. All borrowing records involving the name 'Smith' as the full text of a field:
   https://borrowing.stir.ac.uk/api/v1/json/search/0/0/0/quick/%22smith%22
3. All borrowing records involving the ESTC code 'T155510':
   https://borrowing.stir.ac.uk/api/v1/json/search/0/0/0/quick/%22T155510%22
4. All borrowing records with a field beginning 'ital*':
   https://borrowing.stir.ac.uk/api/v1/json/search/0/0/0/quick/ital%2A
5. All borrowing records with a field that includes the text 'lawyer':
   https://borrowing.stir.ac.uk/api/v1/json/search/0/0/0/quick/lawyer

Search Results

For a passed list of borrowing IDs returns all associated data for each borrowing record. Can accept a maximum of 100 borrowing IDs at a time.

Arguments:

1. Data type: Should be json or csv. Mandatory.
2. Endpoint identifier searchResults. Mandatory.
3. List of IDs (comma separated integers). Mandatory

Examples:

1. Full borrowing data for a set of 100 borrowing IDs
   https://borrowing.stir.ac.uk/api/v1/json/searchResults/28,900,915,925,942,6518,122039,184677,188679,188781,190005,194820,188601,194154,197771,281810,203408,297214,309634,345896,17731,96281,104567,118397,123281,143007,162471,169137,171990,173727,178647,291628,204476,284252,206339,287413,294640,296281,298186,299905,324016,326452,326752,206630,281201,296224,285557,296275,324019,326608,285914,292996,325438,324025,326551,327190,337616,339335,43351,43352,43353,43345,43347,43349,43350,43736,43727,43729,43730,43733,43737,43731,43732,43725,43735,43853,43854,43855,43867,43868,43863,43869,43864,43866,43862,43870,43856,43857,43859,43860,43861,43871,43852,311698,311701,311704,311707,311710,311713,311719

On this day

Returns a complete list of borrowing records for a specific day. Will default to current day unless a day and month are supplied

Arguments:

1. Data type: Should be json or csv. Mandatory.
2. Endpoint identifier onThisDay. Mandatory.
3. Month and Day (MM-DD). Optional
4. Whether a single randomly selected borrowing or the full set. Specify 'full' or leave blank

Examples:

1. Borrowing records for the current day as a JSON file:
   https://borrowing.stir.ac.uk/api/v1/json/onThisDay
2. Borrowing records for the 30th of June as a JSON file:
   https://borrowing.stir.ac.uk/api/v1/json/onThisDay/06-30