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
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. Results are limited to the first 100 matches.
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</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</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</PageUrl>
<ThumbnailUrl>
http://images.mobot.org/viewer/viewerthumbnail.asp?cat=botanicus7&client=b11931073/21753000029560/jp2&image=21753000029560_0774.jp2</ThumbnailUrl>
<ImageUrl>
http://images.mobot.org/viewer/vieweronly.asp?cat=botanicus7&client=b11931073/21753000029560/jp2&image=21753000029560_0774.jp2</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"
}
]
}
]
}
]
}
]
}
}