Information about Upcoming Changes to BHL API

The BHL API will be updated on 25 July 2016 to support changes to the BHL site. These changes will accommodate identifying additional Contributors for Items and Parts of items.

First are changes to the API that may affect your existing processes.

The Contributor and ContributorID elements in the result sets of API methods that return “Part” information will move. ContributorID will be included as a PartIdentifier in the Identifiers list. Contributor will be included in a new Contributors list.

These changes are being made to accommodate more than one contributor per part.  For example, if one institution researches/compiles the data and a second institution facilitates the inclusion of that data in BHL, both institutions may be listed as a contributor.  Initially, no more than two contributors per part will be allowed, but by adopting these changes to API responses we allow for additional (unlimited, actually) contributors in the future.

Here is an example that shows how the API responses are changing.  The examples shown here are an output of the GetPartMetadata method, and have been abbreviated for clarity.

Original API Results – highlighted elements are being moved:

<Response>
 <Status>okStatus>
 <Result>
 <PartUrl>
        http://www.biodiversitylibrary.org/part/1
 PartUrl>
 <PartID>1PartID>
 <ItemID>22498ItemID>
 <StartPageID>3190776StartPageID>
 <SequenceOrder>1SequenceOrder>
 <Contributor>BioStorContributor>
 <ContributorID>4443ContributorID>
 <GenreName>ArticleGenreName>
 <Title>
      Notes on certain species of Tetragnatha 
      (Araneae, Argiopidae) in Central America 
      and Mexico
 Title>
 <ContainerTitle>BrevioraContainerTitle>
 <Volume>67Volume>
 <Date>1957Date>
 <PageRange>1--4PageRange>
 <StartPageNumber>1StartPageNumber>
 <EndPageNumber>4EndPageNumber>
 <Authors> [...] Authors>
 <Subjects />
 <Identifiers>
 <PartIdentifier>
 <IdentifierName>ISSNIdentifierName>
 <IdentifierValue>0006-9698IdentifierValue>
 PartIdentifier>
 Identifiers>
 <Pages> [...] Pages>
 <RelatedParts />
 Result>
Response>

Updated API Results – Highlighted elements are the new locations of the moved data:

<Response>
 <Status>okStatus>
 <Result>
 <PartUrl>
        http://www.biodiversitylibrary.org/part/969
 PartUrl>
 <PartID>1PartID>
 <ItemID>22498ItemID>
 <StartPageID>3190776StartPageID>
 <SequenceOrder>1SequenceOrder>
 <GenreName>ArticleGenreName>
 <Title>
        Notes on certain species of Tetragnatha
        (Araneae, Argiopidae) in Central America
        and Mexico
 Title>
 <ContainerTitle>BrevioraContainerTitle>
 <Volume>67Volume>
 <Date>1957Date>
 <PageRange>1--4PageRange>
 <StartPageNumber>1StartPageNumber>
 <EndPageNumber>4EndPageNumber>
 <Authors> [...] Authors>

 <Contributors>
 <Contributor>
 <ContributorName>BioStorContributorName>
 Contributor>
 Contributors>
 <Subjects />
 <Identifiers>
 <PartIdentifier>
 <IdentifierName>BioStorIdentifierName>
 <IdentifierValue>4443IdentifierValue>
 PartIdentifier>
 <PartIdentifier>
 <IdentifierName>ISSNIdentifierName>
 <IdentifierValue>0006-9698IdentifierValue>
 PartIdentifier>
 Identifiers>
 <Pages> [...] Pages>

 <RelatedParts />
 Result>
Response>

Additionally, there will be two additions to the Item metadata.

The new data elements are: RightsHolder and ScanningInstitution.
These will optionally be displayed if there is data for the relevant organizations.

<Response>
 <Status>okStatus>
 <Result>
 <ItemID>59382ItemID>
 <PrimaryTitleID>20770PrimaryTitleID>
 <ThumbnailPageID>17605914ThumbnailPageID>
 <Source>Internet ArchiveSource>
 <SourceIdentifier>bulletin5160hatcSourceIdentifier>
 <Volume>v.51-60 1898-99Volume>
 <Year/>
 <Contributor>
      UMass Amherst Libraries (archive.org)
 Contributor>
 <RightsHolder>
 Biodiversity Heritage Library
 RightsHolder>
 <ScanningInstitution>
 Smithsonian Institution Libraries
 ScanningInstitution>
 <Sponsor>UMass Amherst LibrariesSponsor>
    [...]
 Result>
Response>

Detailed documentation for the BHL APIs is available at http://www.biodiversitylibrary.org/api2/docs/docs.html.  It will be updated to reflect these changes after they are moved into production on 25 July 2016.

Go to http://www.biodiversitylibrary.org/getapikey.aspx to get an API key for BHL.

Information about other BHL developer tools can be found at http://biodivlib.wikispaces.com/Developer+Tools+and+API.

If you have questions, please feel free to submit feedback via this form.