Api Documentation
The Biodiversity Heritage Library's API is a set of callable methods that can be accessed either through HTTP Requests (REST) or SOAP Requests.
Authentication
To use the BHL API you must supply an API Key value with each request. To obtain a key please navigate to the Get an API Key sub page. The same key can be used for both HTTP requests and SOAP requests.
HTTP Requests (REST)
The HTTP request root URI is located here:
http://bhl.ala.org.au/api/rest
Output Types
Results can be returned in either XML or JSON format. To return XML, append &format=xml to the method call. To return JSON, append &format=json to the method call. If a format is not specified, XML is returned.
Callbacks
If results are returned as JSON and you need to capture the results of a method call with a callback function, append &callback={function name} to the method call.
Status Code
Each method response contains a status code that indicates the success or failure of the method call. This code is contained in the "Status" field of the response. The valid status codes are:
ok - the method executed successfully
error - an error occurred while executing the method; check the ErrorMessage field for details
unauthorized - the specified api key is invalid or does not have permission to execute the method
Methods
Specify the name of the API method being called with the op={method name} argument. For example: http://bhl.ala.org.au/api/rest?op={method name}
GetPageMetadata
Return metadata about a page. You may choose to include the OCR text and a list of names found on the page.
Arguments:
pageid: the identifier of an individual page in a scanned book
ocr: "t" or "true" to return ocr text of the page
names: "t" or "true" to return the names that appear on the page
Example URL:
http://bhl.ala.org.au/api/rest?op=GetPageMetadata&pageid=1328690&ocr=t&names=t&apikey={key value}
Example Response:
View XML File
GetPageOcrText
Return the OCR-generated text of a page.
Arguments:
pageid: the identifier of an individual page in a scanned book
Example URL:
http://bhl.ala.org.au/api/rest?op=GetPageOcrText&pageid=1328690&apikey={key value}
Example Response:
View XML File
GetPageNames
Return a list of names that appear on a page.
Arguments:
pageid: the identifier of an individual page in a scanned book
Example URL:
http://bhl.ala.org.au/api/rest?op=GetPageNames&pageid=1328690&ocr=t&names=t&apikey={key value}
Example Response:
View XML File
Return metadata about an item. You may choose to include a list of the item's pages.
Arguments:
itemid: the identifier of an individual item (book)
pages: "t" or "true" to return the item's pages
Example URL:
http://bhl.ala.org.au/api/rest?op=GetItemMetadata&itemid=16800&pages=t&apikey={key value}
Example Response:
View XML File
GetItemByIdentifier
Find and return metadata about an item or items that match a specific identifier. If you know the Internet Archive identifier for an item, use this method to look up the equivalent item in BHL.
Arguments:
type: the type of identifier (barcode, ia)
value: the identifier value
Example URL:
http://bhl.ala.org.au/api/rest?op=GetItemMetadata&itemid=16800&pages=t&apikey={key value}
Example Response:
View XML File
GetItemPages
Return a list of an item's pages.
Arguments:
itemid: the identifier of an individual item (book)
Example URL:
http://bhl.ala.org.au/api/rest?op=GetItemPages&itemid=16800&apikey={key value}
Example Response:
View XML File
GetUnpublishedItems
Return a list of the identifiers of all unpublished items.
Example URL:
http://bhl.ala.org.au/api/rest?op=GetUnpublishedItems&apikey={key value}
Example Response:
View XML File
Return metadata about a title. You may choose to include a list of the items (books) associated with the title.
Arguments:
titleid: the identifier of an individual title
items: "t" or "true" to return the title's items
Example URL:
http://bhl.ala.org.au/api/rest?op=GetTitleMetadata&titleid=1726&items=t&apikey={key value}
Example Response:
View XML File
GetTitleItems
Return a list of a title's items (books).
Arguments:
titleid: the identifier of an individual title
Example URL:
http://bhl.ala.org.au/api/rest?op=GetTitleItems&titleid=1726&apikey={key value}
Example Response:
View XML File
GetTitleByIdentifier
Find and return metadata about a title or titles that match a specific identifier.
Arguments:
type: the type of identifier (oclc, issn, isbn, lccn, ddc, nal, nlm, coden)
value: the identifier value
Example URL:
http://bhl.ala.org.au/api/rest?op=GetTitleByIdentifier&type=oclc&value=2992225&apikey={key value}
Example Response:
View XML File
TitleSearchSimple
Perform a simple title search. The full title (as specified in MARC 245a and MARC 245b library records) is searched for the specified string. Basic metadata for all full and partial matches is returned.
Arguments:
title: full or partial title for which to search
Example URL:
http://bhl.ala.org.au/api/rest?op=TitleSearchSimple&title=nematocerous&apikey={key value}
Example Response:
View XML File
GetTitleBibTex
Return a citation for a title, using the BibTeX format.
Arguments:
titleid: the identifier of an individual title
Example URL:
http://bhl.ala.org.au/api/rest?op=GetTitleBibTex&titleid=1726&apikey={key value}
Example Response:
View XML File
GetTitleEndNote
Return a citation for a title, using the EndNote format.
Arguments:
titleid: the identifier of an individual title
Example URL:
http://bhl.ala.org.au/api/rest?op=GetTitleEndNote&titleid=1726&apikey={key value}
Example Response:
View XML File
GetUnpublishedTitles
Return a list of the identifiers of all unpublished titles.
Arguments:
titleid: the identifier of an individual title
Example URL:
http://bhl.ala.org.au/api/rest?op=GetUnpublishedTitles&apikey={key value}
Example Response:
View XML File
SubjectSearch
Return a list of subjects that match (fully or partially) the specified search string.
Arguments:
subject: the full or partial subject for which to search
Example URL:
http://bhl.ala.org.au/api/rest?op=SubjectSearch&subject=diptera&apikey={key value}
Example Response:
View XML File
GetSubjectTitles
Return a list of titles associated with a subject.
Arguments:
subject: the full subject string for which to search
Example URL:
http://bhl.ala.org.au/api/rest?op=GetSubjectTitles&subject=diptera&apikey={key value}
Example Response:
View XML File
AuthorSearch
Return a list of authors that match (fully or partially) the specified search string. The names searched are those contained in MARC 100a, 110a, 111a, 700a, 710a, and 711a library records.
Arguments:
name: full or partial name of the author for which to search (last name listed first, i.e. "Darwin, Charles")
Example URL:
http://bhl.ala.org.au/api/rest?op=AuthorSearch&name=dimmock&apikey={key value}
Example Response:
View XML File
GetAuthorTitles
Return a list of titles associated with a given BHL author identifier. Unless the identifier for a particular BHL author record is known in advance, this method should be used in combination with the AuthorSearch method.
Arguments:
creatorid: BHL identifier for a particular author
Example URL:
http://bhl.ala.org.au/api/rest?op=GetAuthorTitles&creatorid=1970&apikey={key value}
Example Response:
View XML File
NameCount
Return the number of unique names found on pages in BHL. Names both with and without NameBank identifiers are counted.
Arguments:
startdate: (optional) start date of range between which to count names
enddate: (optional) end date of range between which to count names
Example URL:
http://bhl.ala.org.au/api/rest?op=NameCount&startdate=10/15/2009&enddate=10/31/2009&apikey={key value}
Example Response:
View XML File
NameList
List the unique names. By using the startrow and batchsize parameters appropriately, you can pull the list all at once, or in batches (i.e. 1000 names at a time). Names both with and without NameBank identifiers are returned.
Arguments:
startrow: first name to return (if are returning names in batches of 100, specify startrow=1 for the first batch, startrow=101 for the second batch, and so on
batchsize: number of names to return
startdate: (optional) start date of range between which to count names
enddate: (optional) end date of range between which to count names
Example URL:
http://bhl.ala.org.au/api/rest?op=NameList&startrow=1&batchsize=1000&startdate=10/15/2009&enddate=10/31/2009&apikey={key value}
Example Response:
View XML File
NameGetDetailForNameBankID
Get basic title, item, and page metadata for each page on which the specified name appears.
Arguments:
namebankid: NameBank identifier for a name
Example URL:
http://bhl.ala.org.au/api/rest?op=NameGetDetail&namebankid=3501464&apikey={key value}
Example Response:
View XML File
NameGetDetailForName
Get basic title, item, and page metadata for each page on which the specified name appears.
Arguments:
name: a complete name string
Example URL:
http://bhl.ala.org.au/api/rest?op=NameGetDetail&name=poa+annua+supina&apikey={key value}
Example Response:
View XML File
NameSearch
Search for a particular name. Names both with and without NameBank identifiers are returned.
Arguments:
name: a partial or complete name string
Example URL:
http://bhl.ala.org.au/api/rest?op=NameSearch&name=poa+annua&apikey={key value}
Example Response:
View XML File
SOAP Requests
The SOAP interface to the Biodiversity Heritage Library (BHL) API exposes methods for extracting data using SOAP requests. The WSDL document for the API is located here
http://bhl.ala.org.au/api/soap?wsdl
Methods
The SOAP methods available are the same as methods for HTTP Requests, a complete description of each method can be found by browsing the information found at http://bhl.ala.org.au/api/soap
Data Elements
The following table describes the data elements that may be includd in the various API Responses. Included is a mapping of the API data elements to the MARC cataloging standard.
| BHL API |
MARC |
Description |
| Title/TitleID |
NA |
BHL identifier for the title |
| Title/BibliographicLevel |
Leader position 07 |
One of the following values, which identify the 'type' of work:
Collection
Monograph/Item
Monographic component part
Serial
Serial component part |
| Title/FullTitle |
245a,b,c |
The complete title of the work |
| Title/ShortTitle |
245a |
The title proper of the work |
| Title/SortTitle |
NA |
Title of the work, modified for more accurate searching |
| Title/PartNumber |
245n |
Number designation for part of a work used in the title |
| Title/PartName |
245p |
Name of a part of a work used in the title |
| Title/CallNumber |
050a,b |
Classification or call number of the work |
| Title/Edition |
250a,b |
Information about the edition of the work |
| Title/PublisherPlace |
260a |
Place of publication of the work |
| Title/PublisherName |
260b |
Name of publisher/distributor of the work |
| Title/PublicationDate |
260c |
Date of publication of the work |
| Title/PublicationFrequency |
310a |
Frequency of publication of the work |
| Title/TitleURL |
NA |
BHL address for the title |
| Creator/CreatorID |
NA |
BHL identifier for the author |
| Creator/Name |
100/110/111/700/710/711/720a |
Personal, corporate, or meeting name |
| Creator/Role |
NA |
One of the following values, which identify the role of an author:
Main Entry -- Personal Name (MARC 100)
Main Entry -- Corporate Name (MARC 110)
Main Entry -- Meeting Name (MARC 111)
Added Entry -- Personal Name (MARC 700)
Added Entry -- Corporate Name (MARC 710)
Added Entry -- Meeting Name (MARC 711)
Added Entry -- Uncontrolled Name (MARC 720) |
| Creator/Numeration |
100/110/111/700/710/711/720b |
Personal numeration |
| Creator/Unit |
100/110/111/700/710/711/720b |
Corporate unit |
| Creator/Title |
100/110/111/700/710/711/720c |
Personal title |
| Creator/Location |
100/110/111/700/710/711/720c |
Corporate/meeting location |
| Creator/Dates |
100/110/111/700/710/711/720d |
Date of birth/death or Corp/Meeting dates |
| Creator/CreatorUrl |
NA |
BHL address for the author |
| Subject/SubjectText |
Various 6XX fields. Most BHL subjects are from 650. |
Subject term |
| TitleIdentifier/IdentifierName |
NA |
One of the following values, which identify the type of identifier:
oclc
issn
isbn
lccn
ddc
nal
nlm
coden |
| TitleIdentifier/IdentifierValue |
Location depends on the type of identifier:
035 (IdentifierName = oclc)
022 (IdentifierName = issn)
020 (IdentifierName = isbn)
050 (IdentifierName = lccn)
082 (IdentifierName = ddc)
070 (IdentifierName = nal)
060 (IdentifierName = nlm)
030 (IdentifierName = coden) |
Value of an identifier assigned to the title |
| Item/ItemID |
NA |
BHL identifier for the item |
| Item/PrimaryTitleID |
NA |
BHL identifier for the title related to the item |
| Item/ThumbnailPageID |
NA |
BHL identifier of the page that produces the item thumbnail |
| Item/Source |
NA |
System from which the item originated (Internet Archive, Botanicus) |
| Item/SourceIdentifier |
NA |
Originating system identifier |
| Item/Volume |
NA |
Volume assigned to the book |
| Item/Year |
NA |
Year assigned to to a monograph or single item in a journal |
| Item/Contributor |
NA |
Institution that contributed the book to BHL |
| Item/Sponsor |
NA |
Institution that sponsored the scanning of the book |
| Item/Language |
008 |
Primary language in which the work is published |
| Item/LicenseUrl |
NA |
URL to information about the license asserted on the book |
| Item/Rights |
NA |
URL to information about the rights/permissions asserted on the book |
| Item/DueDiligence |
NA |
URL to information about the rights/permissions asserted on the book |
| Item/CopyrightStatus |
NA |
Copyright statement for the book |
| Item/CopyrightRegion |
NA |
Country issuing the copyright on the book |
| Item/ItemUrl |
NA |
BHL address for the item |
| Item/TitleUrl |
NA |
BHL address for the title |
| Item/ItemThumbUrl |
NA |
BHL address for the item thumbnail image |
| Page/PageID |
NA |
BHL identifier for the page |
| Page/ItemID |
NA |
BHL identifier for the item containing the page |
| Page/Volume |
NA |
Volume assigned to the page when multiple volumes bound together. |
| Page/Issue |
NA |
Issue assigned to the page when multiple volumes bound together. |
| Page/Year |
NA |
Year assigned to the page when multiple volumes bound together. |
| Page/PageUrl |
NA |
BHL address for the page |
| Page/ThumbnailUrl |
NA |
BHL address for the thumbnail image of the page |
| Page/FullSizeImageUrl |
NA |
BHL address for the full-size image of the page |
| Page/OcrUrl |
NA |
BHL address for the OCR of the page |
| Page/OcrText |
NA |
Text of the page OCR |
| PageNumber/Prefix |
NA |
Prefix of the number assigned to the page (ex. Page, Plate) |
| PageNumber/Number |
NA |
The number assigned to the page |
| PageType/PageTypeName |
NA |
One of the following values, which identify the type of a page:
Title Page
Text
Illustration
Verso
Recto
Blank
Index
Cover
Appendix
Map
Table of Contents
Article Start
Article End
Foldout
Issue Start
Issue End |
| Name/NameBankID |
NA |
Identifier assigned to a name in uBio's NameBank |
| Name/NameFound |
NA |
Name found on a page |
| Name/NameConfirmed |
NA |
Name found on a page and confirmed in uBio's NameBank |