ODL Search Service Documentation
The DLESE Open Digital Library (ODL) Search Service is an API that extends the Open Archives Initiative Protocol for Metadata Harvesting (OAI-PMH) to allow for textual searching of the DLESE library metadata and resource content. This service is similar, but not equivalent, to the Open Digital Library (ODL) search specification (odlsearch1).
Note that the DLESE ODL Search Service is offered here for compatibility with existing applications that use the API, however developers should consider using the DLESE Search Web Service (DDSWS), which offers additional features, for new application development.
The service allows clients to use the OAI-PMH to perform keyword and fielded Information Retrieval (IR) search queries over the metadata repository. Because ODL search (and OAI in general) leverages existing Internet technologies such as HTTP, it may be defined as a REpresentational State Transfer (REST) style web service. After issuing a search request, clients receive raw metadata back as an ordered set of results within the standard ListRecords or ListIdentifiers response containers. Results are ordered by relevance, which is determined by relative term frequency and proximity. The metadata may then be used to render custom interfaces or be embedded in remote clients on the fly.
Search query syntax
To perform a search, clients must provide a search query in the set argument of either a ListRecords or ListIdentifiers request. The set argument must conform to the following syntax: dleseodlsearch/[query string]/[set]/[offset]/[length] where "dleseodlsearch" is the exact string dleseodlsearch, "query string" indicates a list of keywords upon which to search, "set" indicates the set over which to search, "offset" indicates the offset into the results list to begin the results, and "length" indicates the total number of results to return. To search over all sets, clients must supply the string "null" in the set field. Clients must escape all spaces in queries with a plus (+) symbol. The default boolean logic is AND. To request a query using boolean OR, clients must supply the exact string "OR" between each term in the query string.
"BASE_URL?verb=ListRecords&metadataPrefix=oai_dc&set=dleseodlsearch/ocean/null/0/10" - Performs a text search for the term "ocean" across all sets in the repository, returning matching results numbers 0 through 10.
"BASE_URL?verb=ListRecords&metadataPrefix=oai_dc&set=dleseodlsearch/ocean/null/10/10" - Performs a text search for the word "ocean" across all sets in the repository, returning matching results numbers 10 through 20.
"BASE_URL?verb=ListRecords&metadataPrefix=oai_dc&set=dleseodlsearch/ocean+weather/dcc/0/10" - Performs a text search for the terms "ocean" AND "weather" across the set dcc, returning matching results numbers 0 through 10.
"BASE_URL?verb=ListRecords&metadataPrefix=oai_dc&set=dleseodlsearch/ocean+OR+weather/dcc/0/10" - Performs a text search for the terms "ocean" OR "weather" across the set dcc, returning matching results numbers 0 through 10.
Tip: See the ODL Search Service Explorer to issue requests and view the XML response in your web browser.
All state is embedded in the search query string, giving clients control over response flow. Clients can "page through" a set of results by issuing the same request in succession and incrementing the offset parameter by the desired quanta. For example, a client wishing to iterate through three pages of results for a search on the term ocean, retrieving ten records per page, would issue the following three queries:
At the end of each response an empty resumptionToken element is provided for the client that contains the attributes completeListSize and cursor. The completeListSize attribute shows the total number of records in the repository that match the given query. The cursor reflects the offset into the result set where the current response container begins.
If you have questions or comments regarding this service, please send e-mail to firstname.lastname@example.org.
Author: John Weatherley