Biodiversity Heritage Library
API v3 Documentation
Overview
Methods
Data Elements
Release Notes

*** OVERVIEW *** Contents
Authentication
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>
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.
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
Callbacks
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>
Status Codes
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 as Building Blocks
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.

*** METHODS *** Contents
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>
GetPageMetadata
Return metadata about a page. You may choose to include the OCR 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 ocr text of the page
names - "t" or "true" to return the names that appear on the page
GetItemMetadata
Return metadata about an item. You may choose to include a list of the item's pages, the page OCR, 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 ocr for the item's pages
parts - "t" or "true" to return the item's parts
GetTitleMetadata
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
GetPartMetadata
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
GetSubjectMetadata
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
GetAuthorMetadata
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 (bhl, biostor, viaf). Defaults to "bhl".
pubs - "t" or "true" to return the subject's publications
GetNameMetadata
Get basic title, item, and page metadata for each page on which the specified name appears.
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.
GetCollections
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>
GetInstitutions
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>
GetLanguages
Get a list of languages in which materials in BHL have been written.
Example - https://www.biodiversitylibrary.org/api3?op=GetLanguages&apikey=<key+value>
PublicationSearch
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
PublicationSearchAdvanced
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=&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
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
PageSearch
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
SubjectSearch
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
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.
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
NameSearch
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

*** DATA ELEMENTS *** Contents
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
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
Subject/SubjectText Subject term. See MARC 6XX.
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/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
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/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/OcrUrl BHL address for the OCR of the page
Page/OcrText Text of the page OCR
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
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.

*** RELEASE NOTES *** Contents
August 27, 2018 - version 3.0.0
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.
Overall Changes
New Methods
<Result>
<Author>
<AuthorID></AuthorID>
<Name></Name>
<CreatorUrl></CreatorUrl>
<Identifiers>
<Identifier></Identifier>
<Identifier></Identifier>
</Identifiers>
<Publications>
<Publication></Publication>
<Publication></Publication>
<Publication></Publication>
</Publications>
</Author>
</Result>
<Result>
<Subject>
<SubjectText></SubjectText>
<Publications>
<Publication></Publication>
<Publication></Publication>
<Publication></Publication>
</Publications>
</Subject>
</Result>
<Result>
<Page></Page>
<Page></Page>
<Page></Page>
</Result>
<Result>
<Publication></Publication>
<Publication></Publication>
<Publication></Publication>
</Result>
<Result>
<Publication></Publication>
<Publication></Publication>
<Publication></Publication>
</Result>
Modified Methods
XML:
<Response>
<Result>
<Item>…</Item>
</Result>
</Response>
JSON:
{
"Status":"ok",
"ErrorMessage":null,
"Result":[
{…}
]
}
XML:
<Response>
<Result>
<Page>…</Page>
</Result>
</Response>
JSON:
{
"Status":"ok",
"ErrorMessage":null,
"Result":[
{…}
]
}
Previous:
<Page>
<Names>
<Name>
<NameBankID></NameBankID>
<EOLID></EOLID>
<NameFound></NameFound>
<NameConfirmed></NameConfirmed>
</Name>
</Names>
</Page>
New:
<Page>
<Names>
<Name>
<Identifiers>
<Identifier>
<IdentifierName>NameBank</IdentifierName
<IdentifierValue></IdentifierValue>
</Identifier>
<Identifier>
<IdentifierName>EOL</IdentifierName
<IdentifierValue></IdentifierValue>
</Identifier>
</Identifiers>
<NameFound></NameFound>
<NameConfirmed></NameConfirmed>
</Name>
</Names>
</Page>
<Part>
<Names>
<Name>
<Identifiers>
<Identifier>
<IdentifierName>NameBank</IdentifierName
<IdentifierValue></IdentifierValue>
</Identifier>
<Identifier>
<IdentifierName>EOL</IdentifierName
<IdentifierValue></IdentifierValue>
</Identifier>
</Identifiers>
<NameFound></NameFound>
<NameConfirmed></NameConfirmed>
</Name>
</Names>
</Part>
XML:
<Response>
<Result>
<Part>…</Part>
</Result>
</Response>
JSON:
{
"Status":"ok",
"ErrorMessage":null,
"Result":[
{…}
]
}
XML:
<Response>
<Result>
<Title>…</Title>
</Result>
</Response>
JSON:
{
"Status":"ok",
"ErrorMessage":null,
"Result":[
{…}
]
}
Examples:
op=GetNameMetadata&name=poa+annua
op=GetNameMetadata&type=namebank&value=123456
XML:
<Response>
<Result>
<Name>…</Name>
</Result>
</Response>
JSON:
{
"Status":"ok",
"ErrorMessage":null,
"Result":[
{…}
]
}
Previous:
<Name>
<NameBankID></NameBankID>
<EOLID></EOLID>
<NameFound></NameFound>
<NameConfirmed></NameConfirmed>
</Name>
New:
<Name>
<Identifiers>
<Identifier>
<IdentifierName>NameBank</IdentifierName
<IdentifierValue></IdentifierValue>
</Identifier>
<Identifier>
<IdentifierName>EOL</IdentifierName
<IdentifierValue></IdentifierValue>
</Identifier>
</Identifiers>
<NameFound></NameFound>
<NameConfirmed></NameConfirmed>
</Name>
Removed Methods
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.