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.

Specify the name of the API method being called with the "op=<method name>" argument. For example, https://www.biodiversitylibrary.org/api3?op=<method name>

Return metadata about a page. You may choose to include the text and a list of names found on the page.

Example - https://www.biodiversitylibrary.org/api3?op=GetPageMetadata&pageid=3137380&ocr=t&names=t&apikey=<key+value>

pageid - the identifier of an individual page in a scanned book
ocr - "t" or "true" to return text of the page
names - "t" or "true" to return the names that appear on the page

Return metadata about an item. You may choose to include a list of the item's pages, the page text, and a list of the item's parts.

Example - https://www.biodiversitylibrary.org/api3?op=GetItemMetadata&id=16800&pages=t&ocr=f&parts=f&apikey=<key+value>

id - the identifier of an individual item (book)
idtype (OPTIONAL) - "bhl" if the id is a BHL identifier (default value), "ia" if the id is an Internet Archive identifier
pages - "t" or "true" to return the item's pages
ocr - "t" or "true" to return the text for the item's pages
parts - "t" or "true" to return the item's parts

Return metadata about a title. You may choose to include a list of the items (books) associated with the title.

Example - https://www.biodiversitylibrary.org/api3?op=GetTitleMetadata&id=3943&items=t&apikey=<key+value>

id - the identifier of an individual title
idtype (OPTIONAL) - the type of identifier (bhl, doi, oclc, issn, isbn, lccn, ddc, nal, nlm, coden, soulsby). Defaults to "bhl".
items - "t" or "true" to return the title's items

Return metadata about a part. You may choose to include a list of the part's names.

Example - https://www.biodiversitylibrary.org/api3?op=GetPartMetadata&id=2341&pages=t&names=t&apikey=<key+value>

id - the identifier of an individual part (article, chapter, etc)
idtype (OPTIONAL) - the type of identifier (bhl, doi, jstor, biostor, soulsby). Defaults to "bhl".
pages - "t" or "true" to return the part's pages
names - "t" or "true" to return the part's names

Return metadata about a subject. You may choose to include a list of the subject's publications. The BHLType element identifies the type of each publication (Title or Part).

Example - https://www.biodiversitylibrary.org/api3?op=GetSubjectMetadata&subject=water&pubs=t&apikey=<key+value>

subject - the subject for which to return metadata
pubs - "t" or "true" to return the subject's publications

Return metadata about an author. You may choose to include a list of the author's publications. The BHLType element identifies the type of each publication (Title or Part).

Example - https://www.biodiversitylibrary.org/api3?op=GetAuthorMetadata&id=87509&pubs=t&apikey=<key+value>

id - the identifier of an individual author
idtype (OPTIONAL) - the type of identifier (abbreviation, ark, bhl, biostor, dlc, oclc, orcid, tropicos, viaf). Defaults to "bhl".
pubs - "t" or "true" to return the subject's publications

Get basic title, item, and page metadata for each page on which the canonical form of the specified name appears.  For example, assume the name "Poa annua Linnaeus", or an identifier for that name, is specified.  The API method will return title/item/page metadata for all pages on which one of the following names appears:  "Poa annua", "Poa annua L.", "Poa annua Linnaeus", "Poa annua L. (1753)".  Those names all share a canonical form of "Poa annua".

Example - https://www.biodiversitylibrary.org/api3?op=GetNameMetadata&name=poa+annua+linnaeus&apikey=<key+value>

name - a complete name string. Not used if idtype/id are specified.
idtype - the type of identifier (namebank, eol, gni, ion, col, gbif, itis, ipni, worms). Not used if name is specified.
id - an identifier of a name. Not used if name is specified.

Get a list of collections which are used to group titles and items. A single collection may contain either titles or items, but not both.

Example - https://www.biodiversitylibrary.org/api3?op=GetCollections&apikey=<key+value>

Get a list of institutions which have contributed to BHL in some way. These institutions may fill roles such as contributors, rights holders, and scanning institutions.

Example - https://www.biodiversitylibrary.org/api3?op=GetInstitutions&apikey=<key+value>

Get a list of languages in which materials in BHL have been written.

Example - https://www.biodiversitylibrary.org/api3?op=GetLanguages&apikey=<key+value>

Search for publications (titles, items, and parts) that match the specified search term. You can search the catalog metadata only, or the full-text and the catalog metadata combined.  The BHLType element identifies the type of each publication returned (Item or Part).  Up to 200 results are returned at once.  Use the "page" parameter to return the next 200 results.

Example - https://www.biodiversitylibrary.org/api3?op=PublicationSearch&searchterm=cocos+island+costa+rica+birds&searchtype=C&page=1&apikey=<key+value>

searchterm - the text for which to search
searchtype - 'C' for a catalog-only search; 'F' for a catalog+full-text search
page - 1 for the first page of results, 2 for the second, and so on

Search for publications (titles, items, and parts) that match the specified search criteria. Rather than searching across all of the metadata for specified search terms, this method searches specific fields for the terms.  For example, title fields are searched for the "title" parameter value, and the author names are searched for the "authorname" parameter value.  This method searches the catalog metadata only, unless the "text" parameter is specified. Inclusion of a value for the "text" parameter triggers a full-text search over the text of the publications.  The BHLType element identifies the type of each publication returned (Item or Part).    Up to 200 results are returned at once.  Use the "page" parameter to return the next 200 results.

Use the GetLanguages and GetCollections methods to obtain valid language codes and collection identifiers for use as parameters to this method.

Example - https://www.biodiversitylibrary.org/api3?op=PublicationSearchAdvanced&title=cocos+island&titleop=All&authorname=gifford&year=1919&subject=&language=&collection=&notes=&notesop=&text=&textop=&page=1&apikey=<key+value>

title - a title for which to search
titleop - 'all' to search for all specified words in the title fields; 'phrase' to search for the exact phrase specified
authorname - an author name for which to search
year - a four-digit publication year for which to search
subject - a subject for which to search
language - a language code; search will only return publications in the specified language
collection - a collection id; search will only return publications from the specfied collection
notes - one or more words for which to search in the publication notes
notesop - 'all' to search for all specified words in the notes field; 'phrase' to search for the exact phrase specified
text - one or more words for which to search in the text of the publications
textop - 'all' to search for all specified words in the text field; 'phrase' to search for the exact phrase specified
page - 1 for the first page of results, 2 for the second, and so on

Search an item for pages containing the specified text.

Example - https://www.biodiversitylibrary.org/api3?op=PageSearch&itemid=22004&text=dog&apikey=<key+value>

itemid - BHL identifier of the item to be searched
text - the text for which to search

Return a list of subjects that match (fully or partially) the specified search string.

Example - https://www.biodiversitylibrary.org/api3?op=SubjectSearch&subject=diptera&apikey=<key+value>

subject - the full or partial subject for which to search

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.

Example - https://www.biodiversitylibrary.org/api3?op=AuthorSearch&authorname=dimmock&apikey=<key+value>

authorname - full or partial name of the author for which to search

Search for a particular name. Names both with and without NameBank identifiers are returned.

Example - https://www.biodiversitylibrary.org/api3?op=NameSearch&name=poa+annua&apikey=<key+value>

name - a partial or complete name string

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
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/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
Variant/TitleVariantTypeName	One of the following values, which identify the type of variant: Translated Parallel (Translated) Abbreviated Alterative
Variant/Title	The variant title. See MARC 210, 242, and 246.

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.