BHL Name Services v.1.0 released
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
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 returning JSON (with and without a user-specified callback):
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 returning JSON (with and without a user-specified callback):
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 returning JSON (with and without a user-specified callback):
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" } ] } ] } ] } ] } }
Chris Freeland served as the BHL Technical Director from 2006-2012. He is currently the Director of the Open Libraries program at Internet Archive. In this capacity he works with libraries & publishers to digitize their collections, working towards the Archive’s mission of providing “universal access to all knowledge.”
Leave a Comment