The following page from Biologia Centrali Americana, Insecta Lepidoptera-Heterocera v. 4 shows an interesting example of a proximity search we’d like to support with BHL Name Services – “find species x within n characters/words of species y.”

http://www.biodiversitylibrary.org/page/593637

Halfway through the entry for Lineodes integra you’ll see a character that looks like a crosshair, followed by “Solanum spp. ^4-5,8, S. radula^4-5, S. jasminifolium^4-5, S. tuberosum (=Potato)⁸.” According to Wolfram Mey, the leading lepidopterist of the Museum of Natural History (MfN), Berlin:

The symbol means that the species has been reared from/on the particular plant. The symbol has been in use particularly by the old British authors, particularly Lord Walsingham, and is also used on the labels attached to the specimens. (translation by Dr. Michael Ohl)

What this tells us is Lineodes integra (Eggplant Leafroller Moth) is reared on a variety of Solanum species, including Solanum tuberosum (Potato). This example was uncovered during a Name search for Solanum tuberosum; the resulting bibliography included a link to this volume on insects from the Biologia Centrali-Americana, which seemed unusual given the search was for a plant species. This demonstrates why we’d want to facilitate proximity searches, so that users could find pages where both Lineodes integra and Solanum tuberosum occurred to aid in the discovery of predator-prey, plant-pollinator, or other coevolutionary relationships.

This example also suggests that our OCR algorithms are woefully inadequate to infer these kinds of relationships through automated means; the crosshair symbol was identified as ©.

“The Biodiversity Heritage Library (BHL) today released a suite of name services that provide deep links into the rich and growing online collection of biodiversity materials. The BHL is a consortium of major natural history and botanical libraries, all of whom are contributing appropriate materials to be digitized and mounted online. These items are also contributed to the Internet Archive, and therefore are freely available for anyone to download. This alone would be worthy of attention, but the name services released today provide an amazing service to anyone interested in the literature of biodiversity.”

Roy Tennant, Library Journal Blog, “Biodiversity Heritage Library Releases Name Services“

Roy Tennant discusses the BHL Name Service in his latest blog posting. Tennant also points out the usefulness of such tools in the digital library world.

Name Services

Last updated: January 28, 2008 Mike Lichtenberg

Overview

The name services are XML-based web services that can be invoked via SOAP or HTTP GET/POST requests. Responses can be received in one of three formats: XML wrapped in a SOAP envelope, XML, or JSON.

If you want to use SOAP to invoke the service methods, you can navigate to http://www.biodiversitylibrary.org/services/name/NameService.asmx to view the available methods. From that page, you can view the WSDL document for the web service, or click on each method to see detailed information about invoking the method and about the data that is returned.

If you are using HTTP to invoke the methods, the services are located at http://www.biodiversitylibrary.org/services/name/NameService.ashx. Note the difference in the extension on the service URL: ASHX for HTTP vs. ASMX for SOAP.

Descriptions of each service, as well as more details on invoking the methods via HTTP follow.

Methods

NameCount

Returns the number of unique confirmed names in the BHL database.

If the optional start and end dates are specified, then only names added or updated between the dates are counted.

Requests

SOAP:

 NameCount()

 NameCountBetweenDates(“01/01/2008”, “01/31/2008”)

HTTP returning XML:

http://www.biodiversitylibrary.org/services/name/NameService.ashx?op=NameCount&format;=xml

http://www.biodiversitylibrary.org/services/name/NameService.ashx?op=NameCount&startDate;=01/01/2008&endDate;=01/31/2008&format;=xml/services/name/NameService.ashx?op=NameCount&startDate;=01/01/2008&endDate;=01/31/2008&format;=xml

HTTP returning JSON (with and without a user-specified callback):

http://www.biodiversitylibrary.org/services/name/NameService.ashx?op=NameCount&format;=json

http://www.biodiversitylibrary.org/services/name/NameService.ashx?op=NameCount&startDate;=01/01/2008&endDate;=01/31/2008&format;=json

http://www.biodiversitylibrary.org/services/name/NameService.ashx?op=NameCount&format;=json&callback;=MyCallback

http://www.biodiversitylibrary.org/services/name/NameService.ashx?op=NameCount&startDate;=01/01/2008&endDate;=01/31/2008&format;=json&callback;=MyCallback

Responses

XML:

http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

 ok

 436445

JSON:

{

  "Status":"ok",

  "ErrorMessage":null,

  "NameResult":436445

}

These responses show that there are 436445 unique names.

NameList

Returns a list of unique names from the BHL database.

There are two required parameters. “startRow” identifies the first name to return, and “batchSize” indicates how many names to return. The maximum allowed “batchSize” is 1000.

Optionally, “startDate” and “endDate” parameters can also be specified. If the dates are specified, then only names added or updated between the dates are returned.

Each of the following request and response examples assumes a startRow value of 1 and a batchSize value of 5.

Requests

SOAP:

 NameList(“1”, “5”)

 NameListBetweenDates(“1”, “5”, “01/01/2008”, “01/31/2008”)

HTTP returning XML:

http://www.biodiversitylibrary.org/services/name/NameService.ashx?op=NameList&startRow;=1&batchSize;=5&format;=xml

http://www.biodiversitylibrary.org/services/name/NameService.ashx?op=NameList&startRow;=1&batchSize;=5&startDate;=01/01/2008&endDate;=01/31/2008&format;=xml

HTTP returning JSON (with and without a user-specified callback):

http://www.biodiversitylibrary.org/services/name/NameService.ashx?op=NameList&startRow;=1&batchSize;=5&format;=json

http://www.biodiversitylibrary.org/services/name/NameService.ashx?op=NameList&startRow;=1&batchSize;=5&startDate;=01/01/2008&endDate;=01/31/2008&format;=json

http://www.biodiversitylibrary.org/services/name/NameService.ashx?op=NameList&startRow;=1&batchSize;=5&format;=json&callback;=MyCallback

http://www.biodiversitylibrary.org/services/name/NameService.ashx?op=NameList&startRow;=1&batchSize;=5&startDate;=01/01/2008&endDate;=01/31/2008&format;=json&callback;=MyCallback

Responses

XML:

http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

 ok



3456919

 Aalius



8498321

 Aamia



1803753

 Aaronsohnia



4053043

 Ababactus



240834

 Abacina

JSON:

{  

   "Status":"ok",

   "ErrorMessage":null,

   "NameResult":[  

      {  

         "NameBankID":3456919,

         "NameConfirmed":"Aalius",

         "Titles":null

      },

      {  

         "NameBankID":8498321,

         "NameConfirmed":"Aamia",

         "Titles":null

      },

      {  

         "NameBankID":1803753,

         "NameConfirmed":"Aaronsohnia",

         "Titles":null

      },

      {  

         "NameBankID":4053043,

         "NameConfirmed":"Ababactus",

         "Titles":null

      },

      {  

         "NameBankID":240834,

         "NameConfirmed":"Abacina",

         "Titles":null

      }

   ]

}

Calling this method repeatedly, you can parse the entire list of names. Here is an example of how that might be accomplished:

x = 1;

numberOfNames = BHLService.NameCount();

while (x <= numberOfNames) {

  // Get the next 1000 names

  Names = BHLService.NameList(x, 1000);

  //do something with Names…

  x += 1000;

}

In this example, “BHLService.NameCount()” and “BHLService.NameList()” represent calls to the Name Service methods. Implementation details for these will vary depending on the toolset (PHP, Java, .NET or other) and method (SOAP or HTTP) used to interact with the web service.

NameSearch

Returns a list of names that match exactly or start with the specified name.

The required “name” parameter identifies the name for which to search.

Each of the following request and response examples assumes a name search for “zea mays”.

Requests

SOAP:

 NameSearch("zea mays")

HTTP returning XML:

http://www.biodiversitylibrary.org/services/name/NameService.ashx?op=NameSearch&name;=zea+mays&format;=xml

HTTP returning JSON (with and without a user-specified callback):

http://www.biodiversitylibrary.org/services/name/NameService.ashx?op=NameSearch&name;=zea+mays&format;=json

http://www.biodiversitylibrary.org/services/name/NameService.ashx?op=NameSearch&name;=zea+mays&format;=json&callback;=MyCallback

Responses

XML:

http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

 ok



3875305

 Zea mays



5416258

 Zea mays ceratina



5416273

 Zea mays convar. ceratina



5416702

 Zea mays convar. mays



5416216

 Zea mays subsp mays



5416216

 Zea mays subsp. mays

JSON:

{  

   "Status":"ok",

   "ErrorMessage":null,

   "NameResult":[  

      {  

         "NameBankID":3875305,

         "NameConfirmed":"Zea mays",

         "Titles":null

      },

      {  

         "NameBankID":5416258,

         "NameConfirmed":"Zea mays ceratina",

         "Titles":null

      },

      {  

         "NameBankID":5416273,

         "NameConfirmed":"Zea mays convar. ceratina",

         "Titles":null

      },

      {  

         "NameBankID":5416216,

         "NameConfirmed":"Zea mays subsp mays",

         "Titles":null

      },

      {  

         "NameBankID":5416216,

         "NameConfirmed":"Zea mays subsp. mays",

         "Titles":null

      },

      {  

         "NameBankID":5416232,

         "NameConfirmed":"Zea mays tunicata",

         "Titles":null

      }

   ]

}

NameGetDetail

Returns the publication details for the specified NameBankID.

The required “nameBankID” parameter identifies the NameBankID for which to retrieve publication details.

Requests

SOAP:

 NameGetDetail("4906323")

HTTP returning XML:

http://www.biodiversitylibrary.org/services/name/NameService.ashx?op=NameGetDetail&nameBankID;=4906323&format;=xml

HTTP returning JSON (with and without a user-specified callback):

http://www.biodiversitylibrary.org/services/name/NameService.ashx?op=NameGetDetail&nameBankID;=4906323&format;=json

http://www.biodiversitylibrary.org/services/name/NameService.ashx?op=NameGetDetail&nameBankID;=4906323&format;=json&callback;=MyCallback

Responses

XML:



http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

 ok



4906323

 Ternatea



340

 b11931073

 Bulletin of the Torrey Botanical Club.

 New York : Torrey Botanical Club, 1870-

 284.15

 8194

 Bull. Torrey Bot. Club

 http://www.biodiversitylibrary.org/title/b11931073%3C/TitleUrl>



8004

 21753000029560

 i12323901

 QK1 .B9673

 1899 v. 26

 http://www.biodiversitylibrary.org/item/21753000029560%3C/ItemUrl>



710633

 1899

 26

 12

 Page

 658

 http://www.biodiversitylibrary.org/page/710633%3C/PageUrl>

 http://images.mobot.org/viewer/viewerthumbnail.asp?cat=botanicus7&client;=b11931073/21753000029560/jp2ℑ=21753000029560_0774.jp2%3C/ThumbnailUrl>

 http://images.mobot.org/viewer/vieweronly.asp?cat=botanicus7&client;=b11931073/21753000029560/jp2ℑ=21753000029560_0774.jp2%3C/ImageUrl>



Text



Index

JSON:

{  

   "Status":"ok",

   "ErrorMessage":null,

   "NameResult":{  

      "NameBankID":4906323,

      "NameConfirmed":"Ternatea",

      "Titles":[  

         {  

            "TitleID":340,

            "MarcBibID":"b11931073",

            "PublicationTitle":"Bulletin of the Torrey Botanical Club.",

            "PublicationDetails":"New York : Torrey Botanical Club, 1870-",

            "Author":null,

            "BPH":"284.15",

            "TL2":null,

            "Abbreviation":"Bull. Torrey Bot. Club",

            "TitleUrl":"http://www.biodiversitylibrary.org/title/b11931073",

            "Items":[  

               {  

                  "ItemID":7997,

                  "BarCode":"31753002261557",

                  "MarcItemID":"i12323834",

                  "CallNumber":"QK1 .B9673",

                  "VolumeInfo":"1892 v. 19",

                  "ItemUrl":"http://www.biodiversitylibrary.org/item/31753002261557",

                  "Pages":[  

                     {  

                        "PageID":653636,

                        "Year":"1892",

                        "Volume":"19",

                        "Issue":"2",

                        "Prefix":"Page",

                        "Number":"56",

                        "PageUrl":"http://www.biodiversitylibrary.org/page/653636",

                        "ThumbnailUrl":"http://images.mobot.org/viewer/viewerthumbnail.asp?cat=botanicus6&client;=b11931073/31753002261557/jp2ℑ=31753002261557_0083.jp2",

                        "ImageUrl":"http://images.mobot.org/viewer/vieweronly.asp?cat=botanicus6&client;=b11931073/31753002261557/jp2ℑ=31753002261557_0083.jp2",

                        "PageTypes":[  

                           {  

                              "PageTypeName":"Text"

                           }

                        ]

                     }

                  ]

               },

               {  

                  "ItemID":8004,

                  "BarCode":"21753000029560",

                  "MarcItemID":"i12323901",

                  "CallNumber":"QK1 .B9673",

                  "VolumeInfo":"1899 v. 26",

                  "ItemUrl":"http://www.biodiversitylibrary.org/item/21753000029560",

                  "Pages":[  

                     {  

                        "PageID":710633,

                        "Year":"1899",

                        "Volume":"26",

                        "Issue":"12",

                        "Prefix":"Page",

                        "Number":"658",

                        "PageUrl":"http://www.biodiversitylibrary.org/page/710633",

                        "ThumbnailUrl":"http://images.mobot.org/viewer/viewerthumbnail.asp?cat=botanicus7&client;=b11931073/21753000029560/jp2ℑ=21753000029560_0774.jp2",

                        "ImageUrl":"http://images.mobot.org/viewer/vieweronly.asp?cat=botanicus7&client;=b11931073/21753000029560/jp2ℑ=21753000029560_0774.jp2",

                        "PageTypes":[  

                           {  

                              "PageTypeName":"Text"

                           },

                           {  

                              "PageTypeName":"Index"

                           }

                        ]

                     }

                  ]

               }

            ]

         }

      ]

   }

}