Version 3 of the BHL API Now Available

Version 3 of the BHL API has been launched.

The development of a new API version was spurred by the recent introduction of full-text search to the BHL web site. In addition to the inclusion of full-text search, the entire API has been examined and updated. New methods have been added, existing methods have been modified, and many methods have been dropped entirely (or incorporated into other methods).

Because of the extent of the changes, version 3 of the BHL API has a separate endpoint from version 2. Both versions live side-by-side with one another, and do not conflict. Therefore, any existing users of the BHL API should see no disruptions.

API v3 endpoint: https://www.biodiversitylibrary.org/api3

API v2 endpoint: https://www.biodiversitylibrary.org/api2/httpquery.ashx

Long-term, it is expected that version 2 of the API will be deprecated and removed, so current API users are urged to look at version 3 and to begin moving to it.

The official documentation for version 3 of the BHL API is available at https://www.biodiversitylibrary.org/docs/api3.html. The remainder of this post describes the differences between version 3 and version 2.

Overall Changes

• No SOAP interface
• All “PrimaryTitleID” response elements have been renamed to “TitleID”
• All “GenreName” response elements have been renamed to “Genre”
• All “BibliographicLevel” response elements have been renamed to “Genre”
• All “Creator” response elements were renamed to “Author” (for example, <Creators> and <Creator> elements became <Authors> and <Author>, and <CreatorID> became <AuthorID>)

New Methods

GetAuthorMetadata

• Replaces and combines the old GetAuthorTitles and GetAuthorParts, as well as provides a way to retrieve basic Author metadata.
• Response includes author metadata, including a list of publications associated with the author.
• Response format:

<Result>
  <Author>
    <AuthorID></AuthorID>
    <Name></Name>
    <CreatorUrl></CreatorUrl>
    <Identifiers>
      <Identifier></Identifier>
      <Identifier></Identifier>
    </Identifiers>
    <Publications>
      <Publication></Publication>
      <Publication></Publication>
      <Publication></Publication>
    </Publications>
  </Author>
</Result>

GetSubjectMetadata

• Replaces and combines the old GetSubjectTitles and GetSubjectParts, as well as provides a way to retrieve basic Subject metadata.
• Response includes subject metadata, including a list of publications associated with the subject.
• Response format:

<Result>
  <Subject>
    <SubjectText></SubjectText>
    <Publications>
      <Publication></Publication>
      <Publication></Publication>
      <Publication></Publication>
    </Publications>
  </Subject>
</Result>

PageSearch

• Searches the text of a particular item (book) for a word/phrase
• Mimics the “Search Inside the Book” feature on the BHL web site
• Response format:

<Result>
  <Page></Page>
  <Page></Page>
  <Page></Page>
</Result>

PublicationSearch

• Replaces the old BookSearch and PartSearch methods
• Searches the text or text+metadata of items and parts
• Returns 200 results at a time; specify “page” to get a specific page of results
• Equivalent to the primary BHL site search
• Response format:

<Result>
  <Publication></Publication>
  <Publication></Publication>
  <Publication></Publication>
</Result>

PublicationSearchAdvanced

• Replaces the old BookSearch and PartSearch methods
• Search only title and part metadata by specifying a combination of “title”, “authorname”, “year”, “subject”, “language”, and “collection”.
• Search the full text of items matching the metadata criteria by including a “text” value.
• Returns 200 results at a time; specify “page” to get a specific page of results
• Equivalent to the “Advanced Search” feature of the web site
• Response format:

<Result>
  <Publication></Publication>
  <Publication></Publication>
  <Publication></Publication>
</Result>

Modified Methods

AuthorSearch

• Changed “name” argument to “authorname”

GetItemMetadata

• Renamed “itemid” parameter to “id”
• Added optional “idtype” parameter that defaults to value “bhl”. Valid values are: bhl, ia
• Defaulted “pages” parameter to “f”
• Defaulted “ocr” parameter to “f”
• Defaulted “parts” parameter to “f”
• Added <Item> container element around search results

<Response>
  <Result>
    <Item>…</Item>
  </Result>
</Response>

GetPageMetadata

• Defaulted “ocr” parameter to “f”
• Defaulted “names” parameter to “f”
• Added <Page> container element around search results

<Response>
  <Result>
    <Page>…</Page>
  </Result>
</Response>

• Moved <Name><NameBankID> and <Name><EOLID> elements into an <Identifiers> element to match how identifiers are formatted in other API responses.

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>

GetPartMetadata

• Renamed “partid” parameter to “id”
• Added optional “idtype” parameter that defaults to value “bhl”. Valid values are: bhl, doi, jstor, biostor, soulsby
• Added “names” parameter to allow names to be included in the response. For example:

<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>

• Added <Part> container element around search results

<Response>
  <Result>
    <Part>…</Part>
  </Result>
</Response>

• Renamed <PartIdentifier> element to <Identifier>

GetTitleMetadata

• Defaulted “items” parameter to “f”
• Added <Title> container element around search results

<Response>
  <Result>
    <Title>…</Title>
  </Result>
</Response>

• Renamed <TitleIdentifier> element to <Identifier>

NameGetDetail

• Renamed to GetNameMetadata
• Removed “namebankid” parameter
• Added “id” parameter
• Added “idType” parameter that accepts values: namebank, eol, gni, ion (index to organism names), col (catalogue of life), gbif, itis, ipni, worms
• To invoke this method, users should supply either a “name” parameter, or “idType” and “id” parameters

Examples:

op=GetNameMetadata&name=poa+annua

op=GetNameMetadata&type=namebank&value=123456

• Added <Name> container element around search results

<Response>
  <Result>
    <Name>…</Name>
  </Result>
</Response>

• Moved <Name><NameBankID> and <Name><EOLID> elements into an <Identifiers> element to match how identifiers are formatted in other API responses.

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>

NameSearch

• Identifiers are no longer included in the response.

Removed Methods

The following methods are not part of API v3, either because they were rarely used in API v2, their functionality was duplicated in other methods, or they were replaced with other methods.  Where appropriate, the replacement for a removed method is noted.

• BookSearch – replaced with PublicationSearch and PublicationSearchAdvanced
• GetAuthorParts – replaced with GetAuthorPublications
• GetAuthorTitles – replaced with GetAuthorPublications
• GetItemByIdentifier – merged with GetItemMetadata
• GetItemPages – same information available from GetItemMetadata
• GetItemParts – same information available from GetItemMetadata
• GetPageNames – same information available from GetPageMetadata
• GetPageOcrText – same information available from GetPageMetadata
• GetPartBibTex
• GetPartByIdentifier – merged with GetPartMetadata
• GetPartNames – same information available from GetPartMetadata
• GetPartRIS
• GetStats
• GetSubjectParts – replaced with GetSubjectPublications
• GetSubjectTitles – replaced with GetSubjectPublications
• GetTitleBibText
• GetTitleByIdentifier – merged with GetTitleMetadata
• GetTitleItems – same information available from GetTitleMetadata
• GetTitleRIS
• GetUnpublishedItems
• GetUnpublishedParts
• GetUnpublishedTitles
• NameCount
• NameCountBetweenDates
• NameList
• NameListBetweenDates
• PartSearch – replaced with PublicationSearch and PublicationSearchAdvanced
• TitleSeachSimple – replaced with PublicationSearchAdvanced (specify title parameter only)