SHARE

Wednesday, December 5, 2007

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

<?xml version="1.0" encoding="utf-8" ?>
<NameResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Status>ok</Status>
<NameResult>436445</NameResult>
</NameResponse>

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:

<?xml version="1.0" encoding="utf-8" ?>
<NameResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Status>ok</Status>
<NameResult>
<Name>
<NameBankID>3456919</NameBankID>
<NameConfirmed>Aalius</NameConfirmed>
</Name>
<Name>
<NameBankID>8498321</NameBankID>
<NameConfirmed>Aamia</NameConfirmed>
</Name>
<Name>
<NameBankID>1803753</NameBankID>
<NameConfirmed>Aaronsohnia</NameConfirmed>
</Name>
<Name>
<NameBankID>4053043</NameBankID>
<NameConfirmed>Ababactus</NameConfirmed>
</Name>
<Name>
<NameBankID>240834</NameBankID>
<NameConfirmed>Abacina</NameConfirmed>
</Name>
</NameResult>
</NameResponse>

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:

<?xml version="1.0" encoding="utf-8"?>
<NameResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Status>ok</Status>
<NameResult>
<Name>
<NameBankID>3875305</NameBankID>
<NameConfirmed>Zea mays</NameConfirmed>
</Name>
<Name>
<NameBankID>5416258</NameBankID>
<NameConfirmed>Zea mays ceratina</NameConfirmed>
</Name>
<Name>
<NameBankID>5416273</NameBankID>
<NameConfirmed>Zea mays convar. ceratina</NameConfirmed>
</Name>
<Name>
<NameBankID>5416702</NameBankID>
<NameConfirmed>Zea mays convar. mays</NameConfirmed>
</Name>
<Name>
<NameBankID>5416216</NameBankID>
<NameConfirmed>Zea mays subsp mays</NameConfirmed>
</Name>
<Name>
<NameBankID>5416216</NameBankID>
<NameConfirmed>Zea mays subsp. mays</NameConfirmed>
</Name>
</NameResult>
<NameResponse>

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:

<?xml version="1.0" encoding="utf-8"?>
<NameResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Status>ok</Status>
<NameResult>
<NameBankID>4906323</NameBankID>
<NameConfirmed>Ternatea</NameConfirmed>
<Titles>
<Title>
<TitleID>340</TitleID>
<MarcBibID>b11931073</MarcBibID>
<PublicationTitle>Bulletin of the Torrey Botanical Club.</PublicationTitle>
<PublicationDetails>New York : Torrey Botanical Club, 1870-</PublicationDetails>
<BPH>284.15</BPH>
<TL2>8194</TL2>
<Abbreviation>Bull. Torrey Bot. Club</Abbreviation>
<TitleUrl>http://www.biodiversitylibrary.org/title/b11931073%3C/TitleUrl>
<Items>
<Item>
<ItemID>8004</ItemID>
<BarCode>21753000029560</BarCode>
<MarcItemID>i12323901</MarcItemID>
<CallNumber>QK1 .B9673</CallNumber>
<VolumeInfo>1899 v. 26</VolumeInfo>
<ItemUrl>http://www.biodiversitylibrary.org/item/21753000029560%3C/ItemUrl>
<Pages>
<Page>
<PageID>710633</PageID>
<Year>1899</Year>
<Volume>26</Volume>
<Issue>12</Issue>
<Prefix>Page</Prefix>
<Number>658</Number>
<PageUrl>http://www.biodiversitylibrary.org/page/710633%3C/PageUrl>
<ThumbnailUrl>http://images.mobot.org/viewer/viewerthumbnail.asp?cat=botanicus7&client=b11931073/21753000029560/jp2&image=21753000029560_0774.jp2%3C/ThumbnailUrl>
<ImageUrl>http://images.mobot.org/viewer/vieweronly.asp?cat=botanicus7&client=b11931073/21753000029560/jp2&image=21753000029560_0774.jp2%3C/ImageUrl>
<PageTypes>
<PageType>
<PageTypeName>Text</PageTypeName>
</PageType>
<PageType>
<PageTypeName>Index</PageTypeName>
</PageType>
</PageTypes>
</Page>
</Pages>
</Item>
</Items>
</Title>
</Titles>
</NameResult>
</NameResponse>

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&image=31753002261557_0083.jp2",
"ImageUrl":"http://images.mobot.org/viewer/vieweronly.asp?cat=botanicus6&client=b11931073/31753002261557/jp2&image=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&image=21753000029560_0774.jp2",
"ImageUrl":"http://images.mobot.org/viewer/vieweronly.asp?cat=botanicus7&client=b11931073/21753000029560/jp2&image=21753000029560_0774.jp2",
"PageTypes":[
{
"PageTypeName":"Text"
},
{
"PageTypeName":"Index"
}
]
}
]
}
]
}
]
}
}

No comments:

Post a Comment