Overview
Methods
Data Elements
Release Notes

To use the BHL API you must supply an API Key value with each request. To obtain a key, go to https://www.biodiversitylibrary.org/getapikey.aspx. The same key can be used for both the HTTP Query interface and the SOAP interface.

To include the key value with a request, append the argument &apikey=<key+value> to the method call. For example, https://www.biodiversitylibrary.org/api3?op=<method>...&apikey=<key+value>

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.

An example of returning XML is https://www.biodiversitylibrary.org/api3?op=<method>...&apikey=<key+value>&format=xml

An example of returning JSON is https://www.biodiversitylibrary.org/api3?op=<method>...&apikey=<key+value>&format=json

If you need to capture the results of a method call with a callback function, specific the name of the callback function by appending &callback=<function name> to the method call.

For example, https://www.biodiversitylibrary.org/api3?op=<method>...&apikey=<key+value>&callback=<function name>

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

API methods are intended to be used as building blocks, rather than one-stop shops. For example, a method like GetTitleMetadata will return complete metadata about the specified Title, but only summary information (including BHL identifiers) for any related Items. To get the complete metadata for the related Items, the GetItemMetadata method will need to be called for each Item associated with the original Title.

The idea is that API users will not automatically get a lot of unnecessary information from API methods that return everything all at once, but by chaining several API methods call together can get as much or as little information as needed.

The following table describes the data elements that may be included in the various API responses.

BHL API	Description
Title/TitleID	BHL identifier for the title
Title/Genre	One of the following values, which identify the bibliographic level of work: Collection Monograph/Item Monographic component part Serial Serial component part Derived from MARC leader position 07.
Title/MaterialType	One of the following values, which identify the characteristics of the work: Archival material Audio Computer file Maps Mixed materials Music Published material Video Visual resource Derived from MARC leader position 06
Title/FullTitle	The complete title of the work. See MARC 245a|b.
Title/ShortTitle	The title proper of the work. See MARC 245a.
Title/SortTitle	Title of the work, modified for more accurate searching
Title/PartNumber	Number designation for part of a work used in the title. See MARC 245n.
Title/PartName	Name of a part of a work used in the title. See MARC 245p.
Title/CallNumber	Classification or call number of the work. See MARC 050a|b.
Title/Edition	Information about the edition of the work. See MARC 250a|b.
Title/PublisherPlace	Place of publication of the work. See MARC 260a.
Title/PublisherName	Name of publisher/distributor of the work. See MARC 260b.
Title/PublicationDate	Date of publication of the work. See MARC 260c.
Title/PublicationFrequency	Frequency of publication of the work. See MARC 310a.
Title/Doi	DOI assigned to the title
Title/TitleURL	BHL address for the title
Title/CreationDate	Date and time the title was created in BHL
Title/Associations/TitleAssociation/TitleAssociationTypeName	One of the following values, which identify the type of association: Series Statement - Added Entry Series Statement Preceding Entry: Continues Preceding Entry: Continues in part Preceding Entry: Supercedes Preceding Entry: Supercedes in part Preceding Entry: Formed by the union of Preceding Entry: Absorbed Preceding Entry: Absorbed in part Preceding Entry: Separated from Succeeding Entry: Continued by Succeeding Entry: Continued in part by Succeeding Entry: Superceded by Succeeding Entry: Superceded in part by Succeeding Entry: Absorbed by Succeeding Entry: Absorbed in part by Succeeding Entry: Split into Succeeding Entry: Merged with Succeeding Entry: Changed back to Series Statement - Added Entry Uniform Title Host Item Entry Supplement/Special Issue Entry Supplement Parent Entry Other Edition Entry Issued With Entry Other Relationship Entry Uncontrolled Related/Analytical - Added Entry
Title/Associations/TitleAssociation/Title	The associated title. See MARC Series Statement Fields and MARC Linking Entries
Title/Associations/TitleAssociation/AssociatedTitleID	BHL Title Identifier for the associated title.
Title/Variants/TitleVariant/TitleVariantTypeName	One of the following values, which identify the type of variant: Translated Parallel (Translated) Abbreviated Alterative
Title/Variants/TitleVariant/Title	The variant title. See MARC 210, 242, and 246.
Author/AuthorID	BHL identifier for the author
Author/Name	Personal, corporate, or meeting name. See MARC 1XX and MARC 7XX.
Author/Role	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)
Author/Numeration	Personal numeration. See MARC 1XX and MARC 7XX.
Author/Unit	Corporate unit. See MARC 1XX and MARC 7XX.
Author/Title	Personal title. See MARC 1XX and MARC 7XX.
Author/Location	Corporate/meeting location. See MARC 1XX and MARC 7XX.
Author/FullerForm	Fuller form of name. See MARC 1XX and MARC 7XX.
Author/Relationship	Relationship of person to work (editor, illustrator). See MARC 1XX and MARC 7XX.
Author/TitleOfWork	Title page title or serial title related to person. See MARC 1XX and MARC 7XX.
Author/Dates	Date of birth/death or Corp/Meeting dates. See MARC 1XX and MARC 7XX.
Author/CreatorUrl	BHL address for the author
Author/CreationDate	Date and time the author was created in BHL
Subject/SubjectText	Subject term. See MARC 6XX.
Subject/CreationDate	Date and time the subject was created in BHL
TitleNote/NoteText	Text of a note associated with a title. See MARC 5XX.
TitleNote/NoteSequence	Numerical position of the note
TitleNote/NoteTypeName	Description of the note
Item/ItemID	BHL identifier for the item
Item/TitleID	BHL identifier for the title related to the item
Item/ThumbnailPageID	BHL identifier of the page that produces the item thumbnail
Item/Source	System from which the item originated
Item/SourceIdentifier	Originating system identifier
Item/Volume	Volume assigned to the book
Item/Year	Year assigned to to a monograph or single item in a journal
Item/EndYear	End Year assigned to to a monograph or single item in a journal (when the publication covers a range of years)
Item/CopySpecificInformation	Information specific to this copy of the book
Item/Holding Institution	Institution that contributed the book to BHL
Item/RightsHolder	Institution holding the rights to the book
Item/ScanningInstitution	Institution performing the scanning of the book
Item/Sponsor	Institution that sponsored the scanning of the book
Item/Language	Primary language in which the work is published. See MARC 008 positions 35-37.
Item/LicenseUrl	URL to information about the license asserted on the book
Item/Rights	URL to information about the rights/permissions asserted on the book
Item/DueDiligence	URL to information about the rights/permissions asserted on the book
Item/CopyrightStatus	Copyright statement for the book
Item/CopyrightRegion	Country issuing the copyright on the book
Item/ExternalUrl	Non-BHL address for the item
Item/ItemUrl	BHL address for the item
Item/TitleUrl	BHL address for the title
Item/ItemThumbUrl	BHL address for the item thumbnail image
Item/ItemTextUrl	BHL address for the item text
Item/ItemPDFUrl	BHL address for the item PDF
Item/ItemImagesUrl	BHL address for the item images
Item/CreationDate	Date and time the item was created in BHL
Part/PartID	BHL identifier for the part
Part/PartUrl	BHL address for the part
Part/ItemID	BHL address for the item related to the part
Part/Source	System from which the part originated
Part/SourceIdentifier	Originating system identifier
Part/StartPageID	BHL address for the first page of the part
Part/SequenceOrder	Sequential position of the part within the container item.
Part/Genre	One of the following values, which identify the type of the part: Article Book BookItem Chapter Journal Issue Proceeding Conference Preprint Unknown Treatment
Part/Title	The title of the part
Part/TranslatedTitle	Translated title of the part
Part/ContainerTitle	Title of the containing journal/book
Part/PublicationDetails	Combined publication informatino (publisher name, publisher place, and publication date)
Part/PublisherName	Name of publisher/distributor of the part
Part/PublisherPlace	Place of publication of the part
Part/Notes	Miscellaneous information about the part
Part/Volume	Volume of the work in which the part appears
Part/Series	Series of the work in which the part appears
Part/Issue	Issue of the work in which the part appears
Part/Date	Publication date of the part
Part/PageRange	Combined page information (start--end)
Part/StartPageNumber	Starting page number of the part
Part/EndPageNumber	Ending page number of the work
Part/Language	Language of he part
Part/ExternalUrl	Non-BHL location of the part
Part/DownloadUrl	Link to a downloadable version of the part
Part/RightsStatus	Rights status of the part (for example, "out of copyright")
Part/RightsStatement	Rights statement for the part
Part/LicenseName	License under which the part is made available
Part/LicenseUrl	Link to additional licensing details
Part/Doi	DOI assigned to the part
Part/CreationDate	Date and time the part was created in BHL
Part/Contributors/Contributor/ContributorName	Person/organization that contributed the part to BHL
Page/PageID	BHL identifier for the page
Page/ItemID	BHL identifier for the item containing the page
Page/Volume	Volume assigned to the page when multiple volumes bound together.
Page/Issue	Issue assigned to the page when multiple volumes bound together.
Page/Year	Year assigned to the page when multiple volumes bound together.
Page/PageUrl	BHL address for the page
Page/ThumbnailUrl	BHL address for the thumbnail image of the page
Page/FullSizeImageUrl	BHL address for the full-size image of the page
Page/TextSource	Source of the text of the page. Values include "OCR", "Text Import" (usually indicating transcriptions), and "Purposeful Gaming" (corrected OCR).
Page/OcrUrl	BHL address for the OCR of the page
Page/OcrText	Text of the page OCR
Page/CreationDate	Date and time the page was created in BHL
PageNumber/Prefix	Prefix of the number assigned to the page (ex. Page, Plate)
PageNumber/Number	The number assigned to the page
PageType/PageTypeName	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
Publication/BHLType	Publication type: Title, Item, or Part
Publication/FoundIn	Indicates where in the publication the search term(s) were found: Metadata, Text, or Both
Publication/ItemID	BHL Identifier for the publication (if BHLType is Item) or the related BHL Item.
Publication/TitleID	BHL Identifier for the publication (if BHLType is Title)
Publication/Volume	Volume of the publication or the publication's parent work.
Publication/ExternalUrl	Non-BHL address for the publication
Publication/ItemUrl	BHL address for the publication (if BHLType is Item) or the related BHL Item.
Publication/TitleUrl	BHL address for the publication (if BHLType is Title)
Publication/MaterialType	One of the following values, which identify the characteristics of the work: Language material Notated music Manuscript notated music Cartographic material Manuscript cartographic material Projected medium Nonmusical sound recording Musical sound recording Two-dimensional nonprojectable graphic Computer file Kit Mixed materials Three-dimensional artifact or naturally occuring object Manuscript language material
Publication/PublisherPlace	Place of publication
Publication/PublisherName	Publisher of the publication
Publication/PublicationDate	Publishing date of a book or journal publication
Publication/Date	Publishing date of a part publication
Publication/PartUrl	BHL address for the publication (if BHLType is Part)
Publication/PartID	BHL Identifier for the publication (if BHLType is Part)
Publication/Genre	Value identifying the genre of the publication. Examples include the following: Collection, Monograph/Item, Serial, Article, Chapte,  Journal, Issue, Proceeding Conference, Preprint, Treatment
Publication/Title	The title of the publication
Publication/ContainerTitle	The title of the parent work of the publication. If the publication is an article, the ContainerTitle will be the journal in which the article appears.
Publication/Series	Series of the publication or the publication's parent work.
Publication/Issue	Issue of the publication or the publication's parent work.
Publication/PageRange	Combined start and end page information (applies when BHLType is Part)
Name/NameFound	Name found on a page
Name/NameConfirmed	Name found on a page and confirmed in uBio's NameBank
Name/NameCanonical	The canonical form of a name found on a page.  For example, "Poa annua" is the canonical form of the name "Poa annua L. (1753)".
Name/CreationDate	Date and time the name was created in BHL
Identifier/IdentifierName	One of the following values, which identify the type of identifier: bhl ia doi issn isbn lccn ddc nal nlm coden soulsby biostor viaf namebank eol gni
Identifier/IdentifierValue	Value of the identifier.
Collection/CollectionID	BHL identifier for the collection
Collection/CollectionName	The name of the collection
Collection/CollectionDescription	A description of the contents of the collection
Collection/CanContainTitles	1 if the collection can contain titles, 0 otherwise
Institution/InstitutionCode	BHL code for the institution
Institution/InstitutionName	The name of the institution
Institution/InstitutionUrl	URL for the institution
Institution/BHLMember	True if the institution is a member of the BHL consortium
Collection/CanContainItems	1 if the collection can contain items, 0 otherwise
Language/LanguageCode	BHL code for the language
Language/LanguageName	The name of the language

Documentation for the previous version of the BHL API can be found at https://www.biodiversitylibrary.org/api2/docs/docs.html.

Following is a summary of the changes from version 2.x to version 3.0.0 of the API.

The following methods are no longer part of the API, either because they were rarely used, their functionality was duplicated in other methods, or they were replaced with other methods. Where appropriate, the replacement for a removed method is noted.