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

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

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

<Contributors>
<Contributor>
<ContributorName>BioStor</ContributorName>
</Contributor>
</Contributors>
<Subjects />
<Identifiers>
<PartIdentifier>
<IdentifierName>BioStor</IdentifierName>
<IdentifierValue>4443</IdentifierValue>
</PartIdentifier>
<PartIdentifier>
<IdentifierName>ISSN</IdentifierName>
<IdentifierValue>0006-9698</IdentifierValue>
</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>ok</Status>
<Result>
<ItemID>59382</ItemID>
<PrimaryTitleID>20770</PrimaryTitleID>
<ThumbnailPageID>17605914</ThumbnailPageID>
<Source>Internet Archive</Source>
<SourceIdentifier>bulletin5160hatc</SourceIdentifier>
<Volume>v.51-60 1898-99</Volume>
<Year/>
<Contributor>
      UMass Amherst Libraries (archive.org)
</Contributor>
<RightsHolder>
Biodiversity Heritage Library
</RightsHolder>
<ScanningInstitution>
Smithsonian Institution Libraries
</ScanningInstitution>
<Sponsor>UMass Amherst Libraries</Sponsor>
    [...]
</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.