Biodiversity Heritage Library
API v2 Documentation
Created: April 6, 2010
Revised: January 1, 2013


*** HTTP QUERY INTERFACE ***

The HTTP query interface to the Biodiversity Heritage Library (BHL) API exposes methods for extracting data using HTTP GET requests.

AUTHENTICATION

To use the BHL API you must supply an API Key value with each request. To obtain a key, go to http://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, http://www.biodiversitylibrary.org/api2/httpquery.ashx?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 http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=<method>...&apikey=<key value>&format=xml

An example of returning JSON is http://www.biodiversitylibrary.org/api2/httpquery.ashx?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, http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=<method>...&apikey=<key value>&callback=<function name>

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://www.biodiversitylibrary.org/api2/httpquery.ashx?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 - http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=GetPageMetadata&pageid=1328690&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

GetPageOcrText

Return the OCR-generated text of a page.

Example - http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=GetPageOcrText&pageid=1328690&apikey=<key value>

pageid - the identifier of an individual page in a scanned book

GetPageNames

Return a list of names that appear on a page.

Example - http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=GetPageNames&pageid=1328690&apikey=<key value>

pageid - the identifier of an individual page in a scanned book

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 - http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=GetItemMetadata&itemid=16800&pages=t&ocr=f&parts=f&apikey=<key value>

itemid - the identifier of an individual item (book)
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

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.

Example - http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=GetItemByIdentifier&type=ia&value=animalkingdomarr03cuvi&apikey=<key value>

type - the type of identifier (barcode, ia)
value - the identifier value

GetItemPages

Return a list of an item's pages. You may choose to include the ocr for the pages.

Example - http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=GetItemPages&itemid=16800&ocr=f&apikey=<key value>

itemid - the identifier of an individual item (book)
ocr - "t" or "true" to return the ocr for the item's pages

GetItemParts

Return a list of parts (articles, chapters, etc) associated with an item.

Example - http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=GetItemParts&itemid=35600&apikey=<key value>

itemid - the identifier of an individual item (book)

GetUnpublishedItems

Return a list of the identifiers of all unpublished items.

Example - http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=GetUnpublishedItems&apikey=<key value>

GetPartMetadata

Return metadata about a part.

Example - http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=GetPartMetadata&partid=10409&apikey=<key value>

partid - the identifier of an individual part (article, chapter, etc)

GetPartNames

Return a list of scientific names associated with a part.

Example - http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=GetPartNames&partid=41797&apikey=<key value>

partid - the identifier of an individual part (article, chapter, etc)

GetUnpublishedParts

Return a list of the identifiers of all unpublished parts (articles, chapters, etc).

Example - http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=GetUnpublishedParts&apikey=<key value>

GetPartByIdentifier

Find and return metadata about a part or parts that match a specific identifier.

Example - http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=GetPartByIdentifier&type=doi&value=10.4039/Ent38406-12&apikey=<key value>

type - the type of identifier (doi, oclc, issn, isbn, lccn, ddc, nal, nlm, coden)
value - the identifier value

GetPartBibTex

Return a citation for a part, using the BibTeX format.

Example - http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=GetPartBibTex&partid=1000&apikey=<key value>

partid - the identifier of an individual part (article, chapter, etc)

GetPartEndNote

Return a citation for a part, using the EndNote format.

Example - http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=GetParteEndNote&partid=1000&apikey=<key value>

partid - the identifier of an individual part (article, chapter, etc)

GetTitleMetadata

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

Example - http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=GetTitleMetadata&titleid=1726&items=t&apikey=<key value>

titleid - the identifier of an individual title
items - "t" or "true" to return the title's items

GetTitleItems

Return a list of a title's items (books).

Example - http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=GetTitleItems&titleid=1726&apikey=<key value>

titleid - the identifier of an individual title

GetTitleByIdentifier

Find and return metadata about a title or titles that match a specific identifier.

Example - http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=GetTitleByIdentifier&type=oclc&value=2992225&apikey=<key value>

type - the type of identifier (doi, oclc, issn, isbn, lccn, ddc, nal, nlm, coden)
value - the identifier value

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.

Example - http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=TitleSearchSimple&title=nematocerous&apikey=<key value>

title - full or partial title for which to search

GetTitleBibTex

Return a citation for a title, using the BibTeX format.

Example - http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=GetTitleBibTex&titleid=1726&apikey=<key value>

titleid - the identifier of an individual title

GetTitleEndNote

Return a citation for a title, using the EndNote format.

Example - http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=GetTitleEndNote&titleid=1726&apikey=<key value>

titleid - the identifier of an individual title

GetUnpublishedTitles

Return a list of the identifiers of all unpublished titles.

Example - http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=GetUnpublishedTitles&apikey=<key value>

BookSearch

Search for titles and items in BHL. Search criteria includes title, author last name, volume, edition, year of publication, subject, language code, and collection identifier.

Valid language codes and collection identifiers can be obtained from the GetLanguages and GetCollections methods. If year of publication is specified, it should be a 4-digit year.

To execute a search, you must supply at least a title, author last name, or collection identifier.

The metadata returned by this method includes Title Identifier, Title URL, Full Title, Part Number, Part Name, Publisher Place, Publisher Name, Publication Date, complete author data, Item Identifier, Item URL, Volume, Contributor, and collection data. For more information about these data elements, see the "Data Elements" section of this documentation.

Example - http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=BookSearch&title=Selborne&lname=White&volume=2&edition=new&year=1825&subject=&collectionid=4&language=eng&apikey=<key value>

PartSearch

Search for parts of books in BHL, such as articles, chapters, or treatments. Search criteria includes title, container (journal or book title), author, date of publication, volume, series, and issue.

To execute a search, you must supply at least a title or author.

The metadata returned by this method includes Part Identifier, Part URL, Item ID, Page ID for the start page, Genre, Title, Container Title, Publication Details, Volume, Series, Issue, Date, Page Range, Language, rights information, authors, keywords, identifiers, pages, and related parts. For more information, see the "Data Elements" section of this documentation.

Example - http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=PartSearch&title=Critical+approach+to+the+definition+of+Darwinian+units&containerTitle=&author=&date=&volume=&series=&issue=&apikey=<key value>

SubjectSearch

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

Example - http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=SubjectSearch&subject=diptera&apikey=<key value>

subject - the full or partial subject for which to search

GetSubjectTitles

Return a list of titles associated with a subject.

Example - http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=GetSubjectTitles&subject=diptera&apikey=<key value>

subject - the full subject string for which to search

GetSubjectParts

Return a list of parts (articles, chapters, etc) associated with a subject.

Example - http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=GetSubjectParts&subject=frogs&apikey=<key value>

subject - the full subject string 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 - http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=AuthorSearch&name=dimmock&apikey=<key value>

name - full or partial name of the author for which to search (last name listed first, i.e. "Darwin, Charles")

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.

Example - http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=GetAuthorTitles&creatorid=1970&apikey=<key value>

creatorid - BHL identifier for a particular author

GetAuthorParts

Return a list of parts (articles, chapters, etc) 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.

Example - http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=GetAuthorParts&creatorid=39120&apikey=<key value>

creatorid - BHL identifier for a particular author

NameCount

Return the number of unique names found on pages in BHL. Names both with and without NameBank identifiers are counted.

*** This method was a part of version 1 of the BHL API. Its signature and/or return values may have changed. ***

Example - http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=NameCount&startdate=10/15/2009&enddate=10/31/2009&apikey=<key value>

startdate - (optional) start date of range between which to count names
enddate - (optional) end date of range between which to count names

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.

*** This method was a part of version 1 of the BHL API. Its signature and/or return values may have changed. ***

Example - http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=NameList&startrow=1&batchsize=1000&startdate=10/15/2009&enddate=10/31/2009&apikey=<key value>

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

NameGetDetail

Get basic title, item, and page metadata for each page on which the specified name appears.

*** This method was a part of version 1 of the BHL API. Its signature and/or return values may have changed. ***

Example - http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=NameGetDetail&namebankid=3501464&apikey=<key value>

namebankid - (not used if "name" specified) NameBank identifier for a name

Example - http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=NameGetDetail&name=poa+annua+supina&apikey=<key value>

name - (not used if "namebankid" specified) a complete name string

NameSearch

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

*** This method was a part of version 1 of the BHL API. Its signature and/or return values may have changed. ***

Example - http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=NameSearch&name=poa+annua&apikey=<key value>

name - a partial or complete name string

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 - http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=GetCollections&apikey=<key value>

GetLanguages

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

Example - http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=GetLanguages&apikey=<key value>


*** SOAP INTERFACE ***

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 available at this location: http://www.biodiversitylibrary.org/api2/soap.asmx?wsdl

AUTHENTICATION

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

METHODS

The SOAP methods that are available generally map to the methods exposed by the HTTP query interface. The methods names are listed below, and a complete description of each method can be found by browsing the information found at http://www.biodiversitylibrary.org/api2/soap.asmx.

AuthorSearch
BookSearch
GetAuthorParts
GetAuthorTitles
GetCollections
GetItemByIdentifier
GetItemMetadata
GetItemPages
GetItemParts
GetLanguages
GetPageMetadata
GetPageNames
GetPageOcrText
GetPartBibTeX
GetPartByIdentifier
GetPartEndNote
GetPartMetadata
GetPartNames
GetSubjectParts
GetSubjectTitles
GetTitleBibTex
GetTitleByIdentifier
GetTitleEndNote
GetTitleItems
GetTitleMetadata
GetUnpublishedItems
GetUnpublishedParts
GetUnpublishedTitles
NameCount
NameCountBetweenDates
NameGetDetailForName
NameGetDetailForNameBankID
NameList
NameListBetweenDates
NameSearch
PartSearch
SubjectSearch
TitleSearchSimple

*** The Name* methods were a part of version 1 of the BHL API. Their signatures and/or return values may have changed. ***


*** DATA ELEMENTS ***

The following table describes the data elements that may be included in the various API responses. Included is a mapping of the API data elements to the MARC cataloging standard.

BHL API Description MARC
Title/TitleID BHL identifier for the title NA
Title/BibliographicLevel One of the following values, which identify the 'type' of work:
Collection
Monograph/Item
Monographic component part
Serial
Serial component part
Leader position 07
Title/FullTitle The complete title of the work 245a,b,c
Title/ShortTitle The title proper of the work 245a
Title/SortTitle Title of the work, modified for more accurate searching NA
Title/PartNumber Number designation for part of a work used in the title 245n
Title/PartName Name of a part of a work used in the title 245p
Title/CallNumber Classification or call number of the work 050a,b
Title/Edition Information about the edition of the work 250a,b
Title/PublisherPlace Place of publication of the work 260a
Title/PublisherName Name of publisher/distributor of the work 260b
Title/PublicationDate Date of publication of the work 260c
Title/PublicationFrequency Frequency of publication of the work 310a
Title/Doi DOI assigned to the title NA
Title/TitleURL BHL address for the title NA
Creator/CreatorID BHL identifier for the author NA
Creator/Name Personal, corporate, or meeting name 100/110/111/700/710/711/720a
Creator/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)
NA
Creator/Numeration Personal numeration 100/110/111/700/710/711/720b
Creator/Unit Corporate unit 100/110/111/700/710/711/720b
Creator/Title Personal title 100/110/111/700/710/711/720c
Creator/Location Corporate/meeting location 100/110/111/700/710/711/720c
Creator/FullerForm Fuller form of name 100/700q
Creator/Dates Date of birth/death or Corp/Meeting dates 100/110/111/700/710/711/720d
Creator/CreatorUrl BHL address for the author NA
Subject/SubjectText Subject term Various 6XX fields. Most BHL subjects are from 650.
TitleIdentifier/IdentifierName One of the following values, which identify the type of identifier:
doi
oclc
issn
isbn
lccn
ddc
nal
nlm
coden
NA
TitleIdentifier/IdentifierValue Value of an identifier assigned to the title 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)
Item/ItemID BHL identifier for the item NA
Item/PrimaryTitleID BHL identifier for the title related to the item NA
Item/ThumbnailPageID BHL identifier of the page that produces the item thumbnail NA
Item/Source System from which the item originated NA
Item/SourceIdentifier Originating system identifier NA
Item/Volume Volume assigned to the book NA
Item/Year Year assigned to to a monograph or single item in a journal NA
Item/Contributor Institution that contributed the book to BHL NA
Item/Sponsor Institution that sponsored the scanning of the book NA
Item/Language Primary language in which the work is published 008
Item/LicenseUrl URL to information about the license asserted on the book NA
Item/Rights URL to information about the rights/permissions asserted on the book NA
Item/DueDiligence URL to information about the rights/permissions asserted on the book NA
Item/CopyrightStatus Copyright statement for the book NA
Item/CopyrightRegion Country issuing the copyright on the book NA
Item/ExternalUrl Non-BHL address for the item NA
Item/ItemUrl BHL address for the item NA
Item/TitleUrl BHL address for the title NA
Item/ItemThumbUrl BHL address for the item thumbnail image NA
Part/PartID BHL identifier for the part NA
Part/PartUrl BHL address for the part NA
Part/ItemID BHL address for the item related to the part NA
Part/StartPageID BHL address for the first page of the part NA
Part/SequenceOrder Sequential position of the part within the container item. NA
Part/Contributor Person/organization that contributed the part to BHL NA
Part/ContributorID Contributing organization's identifier for the part NA
Part/GenreName One of the following values, which identify the type of the part:
Article
Book
BookItem
Chapter
Journal
Issue
Proceeding
Conference
Preprint
Unknown
Treatment
NA
Part/Title The title of the part NA
Part/TranslatedTitle Translated title of the part NA
Part/ContainerTitle Title of the containing journal/book NA
Part/PublicationDetails Combined publication informatino (publisher name, publisher place, and publication date) NA
Part/PublisherName Name of publisher/distributor of the part NA
Part/PublisherPlace Place of publication of the part NA
Part/Notes Miscellaneous information about the part NA
Part/Volume Volume of the work in which the part appears NA
Part/Series Series of the work in which the part appears NA
Part/Issue Issue of the work in which the part appears NA
Part/Date Publication date of the part NA
Part/PageRange Combined page information (start--end) NA
Part/StartPageNumber Starting page number of the part NA
Part/EndPageNumber Ending page number of the work NA
Part/Language Language of he part NA
Part/ExternalUrl Non-BHL location of the part NA
Part/DownloadUrl Link to a downloadable version of the part NA
Part/RightsStatus Rights status of the part (for example, "out of copyright") NA
Part/RightsStatement Rights statement for the part NA
Part/LicenseName License under which the part is made available NA
Part/LicenseUrl Link to additional licensing details NA
Part/Doi DOI assigned to the part NA
Page/PageID BHL identifier for the page NA
Page/ItemID BHL identifier for the item containing the page NA
Page/Volume Volume assigned to the page when multiple volumes bound together. NA
Page/Issue Issue assigned to the page when multiple volumes bound together. NA
Page/Year Year assigned to the page when multiple volumes bound together. NA
Page/PageUrl BHL address for the page NA
Page/ThumbnailUrl BHL address for the thumbnail image of the page NA
Page/FullSizeImageUrl BHL address for the full-size image of the page NA
Page/OcrUrl BHL address for the OCR of the page NA
Page/OcrText Text of the page OCR NA
PageNumber/Prefix Prefix of the number assigned to the page (ex. Page, Plate) NA
PageNumber/Number The number assigned to the page NA
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
NA
Name/NameBankID Identifier assigned to a name in uBio's NameBank NA
Name/NameFound Name found on a page NA
Name/NameConfirmed Name found on a page and confirmed in uBio's NameBank NA
Collection/CollectionID BHL identifier for the collection NA
Collection/CollectionName The name of the collection NA
Collection/CollectionDescription A description of the contents of the collection NA
Collection/CanContainTitles 1 if the collection can contain titles, 0 otherwise NA
Collection/CanContainItems 1 if the collection can contain items, 0 otherwise NA
Language/LanguageCode BHL code for the language NA
Language/LanguageName The name of the language NA
Variant/TitleVariantTypeName One of the following values, which identify the type of variant:
Translated
Parallel (Translated)
Abbreviated
Alterative
NA
Variant/Title The variant title Location depends on the type of variant:
210 (VariantType = abbreviated)
242 (VariantType = translated)
246 (VariantType = parallel or alternative)


*** RELEASE NOTES ***

January 24, 2014 - version 2.5.1

January 1, 2013 - version 2.5

March 22, 2012 - version 2.3

December 1, 2011 - version 2.2.2

March 1, 2011 - version 2.2.1

February 1, 2011 - version 2.2

November 5, 2010 - version 2.1.1

October 28, 2010 - version 2.1

September 30, 2010 - version 2.0.2

May 7, 2010 - version 2.0.1

April 6, 2010 - version 2.0