Biodiversity Heritage Library
API v2 Documentation
Created: April 6, 2010
Revised: June 12, 2017
*** 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 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/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 https://www.biodiversitylibrary.org/api2/httpquery.ashx?op=<method>...&apikey=<key+value>&format=xml
An example of returning JSON is https://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, https://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, https://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.
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.
pageid - the identifier of an individual page in a scanned book
GetPageNames
Return a list of names that appear on a page.
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.
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.
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.
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.
itemid - the identifier of an individual item (book)
GetUnpublishedItems
Return a list of the identifiers of all unpublished items.
Example - https://www.biodiversitylibrary.org/api2/httpquery.ashx?op=GetUnpublishedItems&apikey=<key+value>
GetPartMetadata
Return metadata about a part.
partid - the identifier of an individual part (article, chapter, etc)
GetPartNames
Return a list of scientific names associated with a part.
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 - https://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.
type - the type of identifier (doi, oclc, issn, isbn, lccn, ddc, nal, nlm, coden, soulsby)
value - the identifier value
GetPartBibTex
Return a citation for a part, using the BibTeX format.
partid - the identifier of an individual part (article, chapter, etc)
GetPartRIS
Return a citation for a part, using the RIS format.
Example - https://www.biodiversitylibrary.org/api2/httpquery.ashx?op=GetPartRIS&partid=2341&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.
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).
titleid - the identifier of an individual title
GetTitleByIdentifier
Find and return metadata about a title or titles that match a specific identifier.
type - the type of identifier (doi, oclc, issn, isbn, lccn, ddc, nal, nlm, coden, soulsby)
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.
title - full or partial title for which to search
GetTitleBibTex
Return a citation for a title, using the BibTeX format.
titleid - the identifier of an individual title
GetTitleRIS
Return a citation for a title, using the RIS format.
titleid - the identifier of an individual title
GetUnpublishedTitles
Return a list of the identifiers of all unpublished titles.
Example - https://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.
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.
SubjectSearch
Return a list of subjects that match (fully or partially) the specified search string.
subject - the full or partial subject for which to search
GetSubjectTitles
Return a list of titles associated with a subject.
subject - the full subject string for which to search
GetSubjectParts
Return a list of parts (articles, chapters, etc) associated with a subject.
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.
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.
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.
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. ***
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. ***
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. ***
namebankid - (not used if "name" specified) NameBank identifier for a name
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. ***
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 - https://www.biodiversitylibrary.org/api2/httpquery.ashx?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/api2/httpquery.ashx?op=GetInstitutions&apikey=<key+value>
GetLanguages
Get a list of languages in which materials in BHL have been written.
Example - https://www.biodiversitylibrary.org/api2/httpquery.ashx?op=GetLanguages&apikey=<key+value>
GetStats
Get the number of Titles, Items, Pages, and Parts currently in BHL.
Example - https://www.biodiversitylibrary.org/api2/httpquery.ashx?op=GetStats&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: https://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 https://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 https://www.biodiversitylibrary.org/api2/soap.asmx.
AuthorSearch
BookSearch
GetAuthorParts
GetAuthorTitles
GetCollections
GetInstitutions
GetItemByIdentifier
GetItemMetadata
GetItemPages
GetItemParts
GetLanguages
GetPageMetadata
GetPageNames
GetPageOcrText
GetPartBibTeX
GetPartRIS
GetPartByIdentifier
GetPartMetadata
GetPartNames
GetStats
GetSubjectParts
GetSubjectTitles
GetTitleBibTex
GetTitleRIS
GetTitleByIdentifier
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/Relationship | Relationship of person to work (editor, illustrator) | 700e |
| Creator/TitleOfWork | Title page title or serial title related to person | 700t |
| 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 soulsby |
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) |
| TitleNote/NoteText | Text of a note associated with a title | Various 5XX fields. |
| TitleNote/NoteSequence | Numerical position of the note | NA |
| TitleNote/NoteTypeName | Description of the note | NA |
| 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/CopySpecificInformation | Information specific to this copy of the book | NA |
| Item/Holding Institution | Institution that contributed the book to BHL | NA |
| Item/RightsHolder | Institution holding the rights to the book | NA |
| Item/ScanningInstitution | Institution performing the scanning of the book | 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/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 |
| Part/Contributors/Contributor/ContributorName | Person/organization that contributed the part to BHL | 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 |
| Institution/InstitutionCode | BHL code for the institution | NA |
| Institution/InstitutionName | The name of the institution | NA |
| Institution/InstitutionUrl | URL for the institution | NA |
| Institution/BHLMember | True if the institution is a member of the BHL consortium | 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) |
| TitleCount | Number of Titles in BHL | NA |
| ItemCount | Number of Titles in BHL | NA |
| PageCount | Number of Titles in BHL | NA |
| PartCount | Number of Titles in BHL | NA |
*** RELEASE NOTES ***
June 12, 2017 - version 2.8.2
March 17, 2017 - version 2.8.1
February 24, 2017 - version 2.8
January 25 2017 - version 2.7.3
September 8, 2016 - version 2.7.2
July 26, 2016 - version 2.7.1
June 14, 2016 - version 2.7
May 12, 2016 - version 2.6
March 24, 2015 - version 2.5.2
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