Services and
APIs
Skip navigation Digital Library for Earth System Education
Digital Library for Earth System Education
Search tips

Search Web Service Documentation

Service version DDSWS v1.0
Document version $Revision: 1.6 $
Last revised $Date: 2009/12/03 18:47:28 $

A new version of this service is available. The documentation here is for a previous version. Please refer to the Current Search Web Service for new application development.


John Weatherley < > - University Corporation for Atmospheric Research, DLESE Program Center.

The DLESE Discovery System Web Service (DDSWS) provides programmatic access to DLESE's search functionality and offers full access to the metadata in DLESE's collections. The service is designed to be used in real-time, high-availability Web sites and applications to provide interactive search and discovery interfaces for library resources. The service is also intended to support research that involves the metadata and content in the library. Metadata is available for educational resources, annotations, news & opportunities and collections. The service supports textual searching over metadata and content, searching by date and field, sorting by date and field, discovery of the controlled vocabularies that are part of the library including grade ranges, subjects, resources types and content standards, checking for the existence of a URL, and other functionality. A full range of Information Retrieval features are exposed through the service as outlined in the description for the Search and UserSearch requests. The service is able to disseminate a number of XML formats as indicated by the ListXmlFormats request.

The Web service requests and responses are described in detail below and examples are provided for reference by developers. Developers may also find the Web service client JSP template and examples helpful.

Thanks to Mike Wright, Tammy Sumner, Sebastian de la Chica, Faisal Ahmad, Srikaran Reddy and other DLESE and NSDL collaborators who contributed directly or indirectly to the design and testing of this service. The design of this service was greatly informed by the work of the Open Archives Initiative and Open Digital Libraries.

Definitions and concepts

DDSWS is a Representational State Transfer (REST) style Web service. In REST style Web service architectures, requests are typically encoded as a URL and responses are returned as XML.

More formally: DDSWS requests are expressed as HTTP argument/value pairs. These requests must be in either GET or POST format. Responses are returned in XML format, which varies in structure and content depending on the request as shown below in the examples section of this document.

  • Base URL - the base URL used to access the Web service. This is the portion of the request that precedes the request arguments. For example http://www.dlese.org/dds/services/ddsws1-0.
  • Request arguments - the argument=value pairs that make up the request and follow the base URL.
  • DDSWS response envelope - the XML container used to return data. This container returns different types of data depending on the request made.

HTTP request format

The format of the request consists of the base URL followed by the ? character followed by one or more argument=value pairs, which are separated by the & character. Each request must contain one verb=request pair, where verb is the literal string 'verb' and request is one of the DDSWS request strings defined below. All arguments must be encoded using the syntax rules for URIs. This is the same encoding scheme that is described by the OAI-PMH.

DDSWS requests and responses

This section defines the available requests or verbs.

The HTTP request format has the following structure:
[base URL]?verb=request[&additional arguments].

For example:

http://www.dlese.org/dds/services/ddsws1-0?
          verb=GetRecord&id=DLESE-000-000-000-001

Summary of available requests:

Search - Allows a client to search the full metadata repository and the content of the resources using a rich textual and fielded Boolean search query language that supports advanced Information Retrieval query features such as term, field and phrase searches, term and term/field boosting, term stemming, wildcard and fuzzy searches, term proximity searches, and other functionality. The Search request has access to a wide range of available search fields, and through the use of query clauses, can be used to apply custom page rank algorighms to searches (see example search queries). The request also supports searching by XML format, searching by date and sorting results by index field, and restricting searches by library controlled vocabularies, such as grade ranges, subjects, etc.

UserSearch - Is nearly identical to the Search request except that it operates over educational resources (ADN metadata format) only, and it applies a default searcher that automatically performs word stemming and provides page rank boosting for resources that match higher relevancy search indicators, such as when a resource contains a matching search term in the title field of it's metadata as opposed to elsewhere in it's text. These search algorithms are the same as those that are applied to user's searches in the DLESE library web site. This request is meant to to be used by clients that wish to provide a search experience similar to that in the DLESE library web site or wish to leverage the automatic word stemming and page rank algorithms that are applied to searches.

GetRecord - Accesses the metadata for a single record.

ListCollections - Accesses the list of available metadata collections in the repository.

ListGradeRanges - Accesses the list of controlled vocabularies and search keys for grade ranges.

ListSubjects - Accesses the list of controlled vocabularies and search keys for subjects.

ListResourceTypes - Accesses the list of controlled vocabularies and search keys for resource types.

ListContentStandards - Accesses the list of controlled vocabularies and search keys for content standards.

ListXmlFormats - Accesses the list of the available XML formats from this service.

UrlCheck - Allows a client to check whether a given URL is cataloged in the repository.

ServiceInfo - Accesses information about this Web service.


Search

Sample request

The following request performs a search for the term "ocean" and returns 10 search results, starting at position 0:

http://www.dlese.org/dds/services/ddsws1-0?verb=Search&q=ocean&s=0&n=10&client=ddsws-documentation

Summary and usage

The Search request allows a client to search the full metadata repository and the content of the resources using a rich textual and fielded Boolean search query language that supports advanced Information Retrieval query features such as term, field and phrase searches, term and term/field boosting, term stemming, wildcard and fuzzy searches, term proximity searches, and other functionality. The Search request has access to a wide range of available search fields, and through the use of query clauses, can be used to apply custom page rank algorighms to searches (see example search queries). The request also supports searching by XML format, searching by date and sorting results by index field, and restricting searches by library controlled vocabularies, such as grade ranges, subjects, etc.

The Search and UserSearch response consists of an ordered set of metadata records, sorted by relevancy. Flow control is managed by the client, which may 'page through' a set of results using the 's' and 'n' arguments as described below. The metadata returned by the Search request may be of any type that is supported by the library, including ADN, collection, annotation, news and opportunities, briefmeta or other supported formats. The metadata returned by the UserSearch request is always in ADN format.

The Search and UserSearch request accepts queries using the Lucene Query Syntax (LQS). LQS supports advanced Information Retrieval query clauses such as term and field boosting, wildcard and fuzzy searches, etc. Queries are supplied in the q argument of the request.

Arguments

  • q - (query) an optional argument that may contain plain text or field/term specifiers. Boolean logic, field/term specifiers and boosting must be specified using the Lucene Query Syntax (LQS). Plain text terms (when no field is indicated) are used to search in the default field, which contains textual metadata extracted from the title, description, keywords, grade ranges, resource types and other areas of the library metadata. See available search fields for examples and detailed information about the fields that are available for searching.

  • xmlFormat - an optional argument that indicates the format the records must be returned in. If specified, searches are limited to only those records that are available in the given format. If not specified, the records will be returned in their native format using a localized version of XML (e.g. stripped of their namespace and schema declarations). The available formats may be discovered using the ListXmlFormats request. Not supported in the UserSearch request.

  • client - an optional argument that may be supplied by the client to indicate where the request originated from. Example values might be ddsExamplesSearchClient or myLibrarySearchClient. When supplied, this information is used by DLESE to help understand how people are using the service and a client-by-client basis.

  • so - (search over) an optional argument that must contain the value allRecords or discoverableRecords. Users who request to search over allRecords must be authorized by IP, otherwise an error is returned. Defaults to discoverableRecords. Not supported in the UserSearch request.

Flow control is managed by the client through the use of the 's' and 'n' arguments, which specify the desired state of paging through a set of search results. For example, when a search is initially performed, the client would typically construct a request that supplies the arguments s=0 and n=10 to return up to the first 10 matching results. The client could then page through the set of results by issuing subsequent requests indicating s=10 and n=10 for the next ten results, s=20 and n=10 for results 20 through 30 and so forth up to totalNumResults. For each requested page of results the client must supply identical search criteria in the q, gr, su, cs, re, xmlFormat, so, sorting and date-restrictive arguments. The search algorithm used in DDSWS is deterministic, which means the set and order of search results are guaranteed to be identical for any two searches when identical search criteria are applied. Thus the 's' and 'n' arguments can be thought of as indicating the 'window' into the set of ordered search results into which the client wants to see.

  • s - (starting offset) - a required argument that specifies the starting offset into the results set upon which metadata records should be returned. May be any integer grater than or equal to 0.

  • n - (number returned) - a required argument that specifies the number of metadata records to return, beginning at the offset specified by 's'. Must be a integer from 1 to 500.


The following arguments serve to limit searches by controlled vocabulary. The searchKey that must be used with these arguments must be discovered using the vocabulary list requests. Example searchKey gr=07

  • gr - (grade range) an optional repeatable argument that limits the search to the given grade range(s). If none specified defaults to searching over all grade ranges. If more than one is specified then boolean OR logic is applied across each.

  • re - (resource type) an optional repeatable argument that limits the search to the given resource type(s). If none specified defaults to searching over all resource types. If more than one is specified then Boolean OR logic is applied across each.

  • su - (subject) an optional repeatable argument that limits the search to the given subject(s). If none specified defaults to searching over all subjects. If more than one is specified then Boolean OR logic is applied across each.

  • cs - (content standard) an optional repeatable argument that limits the search to the given content standard(s). If none specified defaults to searching over all content standards. If more than one is specified then Boolean OR logic is applied across each.

  • ky - (collection key) an optional repeatable argument that limits the search to the given collection(s). If none specified defaults to searching over all collections. If more than one is specified then Boolean OR logic is applied across each.

The following two arguments instruct the service to sort the response by a given index field. The service sorts the entire result set lexically prior to returning the requested portion of the results. Only one of these two arguments may be supplied in the request. Values must a sortable field in the index, as listed below. These arguments are Not supported in the UserSearch request.

  • sortAscendingBy - an optional argument that instructs the service to sort the search results in ascending lexical order by a given index field.
  • sortDescendingBy - an optional argument that instructs the service to sort the search results in descending lexical order by a given index field.

The following arguments instruct the service to search in a given index date field. Date searches may be performed independently or in combination with text-based or vocabulary-based searches. The values provided in the fromDate or toDate arguments must be a union date type string of the form yyyy-MM-dd or an ISO8601 UTC datastamp of the form yyyy-MM-ddTHH:mm:ssZ. Example dates include 2004-07-08 or 2004-07-26T21:58:25Z. The fields that are avialable for searching by date are listed below. These arguments are Not supported in the UserSearch request.

  • dateField - an optional argument that indicates which index date field to search in. If supplied, one or both of either the fromDate or toDate arguments must be supplied.
  • fromDate - an optional argument that indicates a date range to search from. If supplied, the dateField argument must also be supplied.
  • toDate - an optional argument that indicates a date range to search to. If supplied, the dateField argument must also be supplied.

Errors and exceptions

Error is indicted if the request does not the required arguments or if an argument is included that is not supported.

Examples

Request

Search for the word ocean.

http://www.dlese.org/dds/services/ddsws1-0? verb=Search&q=ocean&s=0&n=10

Response


<?xml version="1.0" encoding="UTF-8" ?> 

<DDSWebService>

  <Search>

    <resultInfo>

      <totalNumResults>520</totalNumResults>

      <numReturned>10</numReturned>

      <offset>0</offset>

    </resultInfo>

    <results>

      <record>

        <head>

          <id>DLESE-COLLECTION-000-000-000-018</id>

          <collection recordId="DLESE-COLLECTION-000-000-000-012">

              Science Ed Resource Center (SERC)</collection>

          <xmlFormat>dlese_collect</xmlFormat>

          <fileLastModified>2004-03-29T20:44:41Z</fileLastModified>

          <whatsNewDate type="collection">2004-03-29</whatsNewDate>

          <additionalMetadata realm="dlese_collect">

            <formatOfRecords>adn</formatOfRecords>

            <isEnabled>true</isEnabled>

            <numRecords>325</numRecords>

            <numRecordsIndexed>324</numRecordsIndexed>

            <partOfDrc>false</partOfDrc>

          </additionalMetadata>

        </head>

        <metadata>

          <collectionRecord>

            <general>

              <fullTitle>Carleton College Science Education 

               Resource Center (SERC) - Starting Point Entry 

               Level Geoscience Collection

              </fullTitle>

              ...



</DDSWebService>


Request

Search for the word ocean and limit the search to grade range High (9-12).

http://www.dlese.org/dds/services/ddsws1-0?

           verb=Search&q=ocean&gr=02&s=0&n=10

Response


<?xml version="1.0" encoding="UTF-8" ?> 

<DDSWebService>

  <Search>

    <resultInfo>

      <totalNumResults>208</totalNumResults>

      <numReturned>10</numReturned>

      <offset>0</offset>

    </resultInfo>

    <results>

      <record>

	<head>

          <id>NASA-Edmall-2315</id>

          <collection recordId="DLESE-COLLECTION-000-000-000-014">


             NASA ED Mall Collection</collection>

          <xmlFormat>adn</xmlFormat>

          <fileLastModified>2004-06-17T18:24:10Z</fileLastModified>

          <whatsNewDate type="itemnew">2003-07-29</whatsNewDate>

          <additionalMetadata realm="adn">

            <accessionStatus>

               accessioneddiscoverable

            </accessionStatus>

            <partOfDrc>false</partOfDrc>

          </additionalMetadata>

        </head>

        <metadata>

          <itemRecord>

            <general>

              <title>Coriolis Force</title>

              ...



</DDSWebService>


Request

Search for all ADN records new to the library since July 7th, 2004 and sort descending by the wndate field.

http://www.dlese.org/dds/services/ddsws1-0?

verb=Search&s=0&n=10&fromDate=2004-07-08&dateField=wndate

&sortDescendingBy=wndate&xmlFormat=adn-localized

Response

Same format as above.


Request

Perform a request that does not contain all required arguments and thus is in error.

http://www.dlese.org/dds/services/ddsws1-0?

         verb=Search&q=ocean&gr=02&s=0

Response


<?xml version="1.0" encoding="UTF-8" ?> 

<DDSWebService>

  <error>

    The argument 'n' is required. n specifies the 

    maximum number of results to return.

  </error>

</DDSWebService>



UserSearch

Sample request

The following request performs a search for the term "ocean" and returns 10 search results, starting at position 0:

http://www.dlese.org/dds/services/ddsws1-0?verb=UserSearch&q=ocean&s=0&n=10&client=ddsws-documentation

Summary and usage

The UserSearch request is nearly identical to the Search request except that it operates over educational resources (ADN metadata format) only, and it applies a default searcher that automatically performs word stemming and provides page rank boosting for resources that match higher relevancy search indicators, such as when a resource contains a matching search term in the title field of it's metadata as opposed to elsewhere in it's text. These search algorithms are the same as those that are applied to user's searches in the DLESE library web site. This request is meant to to be used by clients that wish to provide a search experience similar to that in the DLESE library web site or wish to leverage the automatic word stemming and page rank algorithms that are applied to searches.

The UserSearch response is identical to the Search response and consists of an ordered set of ADN records, sorted by relevancy. The default searcher that is used incorporates several Information Retrieval techniques designed to augment the page rank and total number of results. These augmentations include word stemming, boosting of records that contain search terms in their title or description and a slight boosting of records that are cataloged by two or more collections or are part of the DLESE Reviewed Collection. The default searcher's algorithms are applied automatically to all terms and phrases supplied by the client in the default field portion of the query sent in the request, and all other fields in the query are treated normally (see available search fields for examples and details). Clients may use this request as a starting point and apply additional boosting to what is provided by the default searcher by supplying additional ranking clauses in the query sent in the request. Clients wishing to implement their own page rank algorithms fully from scratch, or to search over records in formats other than ADN, should use the Search request.

Arguments

UserSearch accepts the same arguments as the Search request, with the exception of xmlFormat, sortAscendingBy, sortDescendingBy, dateField, fromDate, toDate, and so.

Errors and exceptions

Same as the Search request.

Examples

Request

Same as the Search request, however the verb argument must be indicated as 'UserSearch' and the arguments listed above are not accepted.

Response

Identical to that of the Search request. UserSearch only returns ADN records.


GetRecord

Sample request

The following request displays the metadata for record ID DLESE-000-000-000-001 displayed in it's native XML format:

http://www.dlese.org/dds/services/ddsws1-0?verb=GetRecord&id=DLESE-000-000-000-001

Summary and usage

The GetRecord request is used to pull up the metadata for a single item in the repository. Clients should use this request to display the metadata from a single record, for example if the user has requested "more information" about a resource. The data is returned in ADN format and other formats including dlese_collect, dlese_anno, oai_dc, nsdl_dc and briefmeta. Sample ADN records are available here.

Arguments

  • id - a required argument that specifies the DLESE identifier for the record.

  • xmlFormat - an optional argument that indicates the format the record must be returned in. If specified, responses are limited to only those records that are available in the given format. If not specified, the record will be returned in it's native format using a localized version of XML (e.g. stripped of it's namespace and schema declaration). The available formats may be discovered using the ListXmlFormats request.

  • so - (search over) an optional argument that must contain the value allRecords or discoverableRecords. Users who request to search over allRecords must be authorized by IP, otherwise an error is returned. Defaults to discoverableRecords.

Errors and exceptions

Error is indicted if the request does not contain the id argument or if the record is not available.

Examples

Request

Request the DLESE record id DLESE-000-000-000-337 and get the response in ADN format. Shown without the required encoding, for clarity.

http://www.dlese.org/dds/services/ddsws1-0?

        verb=GetRecord&id=DLESE-000-000-000-337

Response


<?xml version="1.0" encoding="UTF-8" ?> 

<DDSWebService>

  <GetRecord>

    <record>

      <head>

        <id>DLESE-000-000-000-337</id> 

        <collection recordId="DLESE-COLLECTION-000-000-000-015">

          DLESE Community Collection (DCC)</collection> 

        <xmlFormat>adn</xmlFormat> 

        <fileLastModified>2004-06-24T19:06:08Z</fileLastModified> 

        <whatsNewDate type="itemnew">2003-07-10</whatsNewDate> 

        <additionalMetadata realm="adn">

          <accessionStatus>accessioneddiscoverable</accessionStatus> 

          <partOfDrc>true</partOfDrc> 

          <alsoCatalogedBy collectionLabel="NASA ESE Reviewed 

             Collection" 

             collectionRecordId="DLESE-COLLECTION-000-000-000-023">

                  NASA-ESERevProd333</alsoCatalogedBy> 

        </additionalMetadata>

      </head>

      <metadata>

        <itemRecord>

          <general>

            <title>Earth Science Picture of the Day</title> 

            ...



</DDSWebService>


Request

Request a DLESE record id that does not exist in the repository. An error is returned.

http://www.dlese.org/dds/services/ddsws1-0?

          verb=GetRecord&id=DLESE-000-000-0z00-001

Response


<?xml version="1.0" encoding="UTF-8" ?> 

<DDSWebService>

  <error>ID DLESE-000-000-0z00-001 does not 

     exists in the repository.</error> 

</DDSWebService>


Request

Issue an invalid response (the id argument is missing)

http://www.dlese.org/dds/services/ddsws1-0?verb=GetRecord

Response


<?xml version="1.0" encoding="UTF-8" ?> 

<DDSWebService>

  <error>The id argument is required but is 

      missing or empty</error> 

</DDSWebService>



ListCollections

Sample request

The following request lists the metadata collections that are available in the library:

http://www.dlese.org/dds/services/ddsws1-0?verb=ListCollections

Summary and usage

The ListCollections request is used to discover the available metadata collections in the repository and to retrieve the search field/key values used to perform searches across collections. Clients should use this request to generate user interface widgets for selecting collections to search from, or to display collection information such as the number of records in a collection. This request belongs to the vocabulary list class of requests.

The response from ListCollections conforms to the vocabulary list response format but includes two additional elements: <recordId> and <additionalMetadata>

Examples

Refer to the documentation for the vocabulary list class of requests.


ListGradeRanges

Sample request

The following request lists the library grade range vocabularies and corresponding search keys:

http://www.dlese.org/dds/services/ddsws1-0?verb=ListGradeRanges

Summary and usage

The ListGradeRangesrequest is used to discover the controlled vocabularies and search field/keys for grade ranges. Clients should use this request to generate user interface widgets for selecting grade ranges to search from. This request belongs to the vocabulary list class of requests.

Examples

Refer to the documentation for the vocabulary list class of requests.


ListSubjects

Sample request

The following request lists the library subject vocabularies and corresponding search keys:

http://www.dlese.org/dds/services/ddsws1-0?verb=ListSubjects

Summary and usage

The ListSubjects request is used to discover the controlled vocabularies and search field/keys for subjects. Clients should use this request to generate user interface widgets for selecting the subjects to search from. This request belongs to the vocabulary list class of requests.

Examples

Refer to the documentation for the vocabulary list class of requests.


ListResourceTypes

Sample request

The following request lists the library resource type vocabularies and corresponding search keys:

http://www.dlese.org/dds/services/ddsws1-0?verb=ListResourceTypes

Summary and usage

The ListResourceTypes request is used to discover the controlled vocabularies and search field/keys for resource types. Clients should use this request to generate user interface widgets for selecting the resource types to search from. This request belongs to the vocabulary list class of requests.

Examples

Refer to the documentation for the vocabulary list class of requests.


ListContentStandards

Sample request

The following request lists the library content standard vocabularies and corresponding search keys:

http://www.dlese.org/dds/services/ddsws1-0?verb=ListContentStandards

Summary and usage

The ListContentStandards request is used to discover the controlled vocabularies and search field/keys for content standards. Clients should use this request to generate user interface widgets for selecting the content standards to search from. This request belongs to the vocabulary list class of requests.

Examples

Refer to the documentation for the vocabulary list class of requests.


Vocabulary list requests

Summary and usage

Vocabulary list requests include ListGradeRanges, ListSubjects, ListResourceTypes, ListContentStandards, and ListCollections*. Each of the vocabulary list requests use the same request and response format.

Vocabulary list requests are used to determine the search values supplied in the gr, su, re, cs and ky arguments of the Search and UserSearch requests and should be used to construct user interface menus for selecting the grade ranges, subjects, etc. for users to limit their search by.

More specifically, vocabulary list requests represent the class of requests that expose controlled vocabularies in the library (grade ranges, subjects, resource types, content standards and collections). Vocabulary list requests may be used to discover the vocabulary entries ('Primary elementary'. etc.), the search field/key pair used to perform and limit searches across the given vocabulary in the Search and UserSearch requests ('gr=07', etc.), and a set of rendering guidelines used to determine things such as whether to display the vocabulary listing to the user and the label that should displayed, for example 'Primary (K-2)'.

Implementation tip: Library vocabularies change very infrequently (on the order of years or months). Clients should retrieve the vocabulary values once and cache them, for example at application start up, rather than retrieving them each time a user accesses the client.

*Note: ListCollections conforms to the vocabulary list response but includes two additional elements: <recordId> and <additionalMetadata>

Arguments

None.

Errors and exceptions

None.

Examples

Request

Request the grade ranges that are available. Note the verb argument may contain any of the vocabulary list requests (ListGradeRanges, ListSubjects, ListResourceTypes, ListContentStandards, or ListCollections) corresponding to the vocabulary you are interested in.

http://www.dlese.org/dds/services/ddsws1-0?verb=ListGradeRanges

Response


<?xml version="1.0" encoding="UTF-8" ?> 

<DDSWebService>

  <ListGradeRanges>

    <searchField>gr</searchField>

    <gradeRanges>

      <gradeRange>

        <vocabEntry>DLESE:Primary elementary</vocabEntry>

        <searchKey>07</searchKey>

        <renderingGuidelines>

          <label>Primary (K-2)</label>

          <noDisplay>false</noDisplay>

          <wrap>false</wrap>

          <divider>false</divider>

          <hasSubList>false</hasSubList>

          <isLastInSubList>false</isLastInSubList>

          <groupLevel>0</groupLevel>

        </renderingGuidelines>

      </gradeRange>

      <gradeRange>

        <vocabEntry>DLESE:Intermediate elementary</vocabEntry>

        ...



</DDSWebService


*Note: ListCollections conforms to the vocabulary list response format shown above but includes two additional elements: <recordId> and <additionalMetadata>


ListXmlFormats

Sample request

The following request lists the XML formats that may be disseminated from this service and their corresponding search keys:

http://www.dlese.org/dds/services/ddsws1-0?verb=ListXmlFormats

Summary and usage

The ListXmlFormats request is used to discover the XML formats available from the repository as a whole or for a single record in the repository. Clients should use this request to discover the available XML formats and the keys that may be supplied in the 'xmlFormat' argument of the Search or GetRecord requests.

DDSWS is able to disseminate a number of XML formats including ADN (adn), News&Opps (news_opps), DLESE annotation (dlese_anno), DLESE collection (dlese_collect), OAI Dublin Core (oai_dc), NSDL Dublin Core (nsdl_dc), and others.

Certain records are available in multiple formats. For example, records that were originally cataloged in the ADN format may be returned in the adn, adn-localized, briefmeta, oai_dc, nsdl_dc, format. When a record is requested in a non-native format, it's XML is transformed to the requested format using XSLT or other transformation prior to being returned by the service.

Many XML formats are available in namespace-specific form or a localized form that contains no namespace or schema declaration. Localized XML is indicated by adding -localized to the end of the XML format specifier, for example adn-localized. When localized XML is returned, the XML is generally easier to read and XPath notation is greatly simplified. By default, all requests in the service return localized versions of the metadata unless a non-localized specifier is indicated.

Arguments

  • id - an optional argument that specifies an ID in the repository. If supplied the request will show only those XML formats that are available for that ID. If ommitted, the response will indicate all XML formats that are available in the repository.

Errors and exceptions

Error is indicted if the id argument is supplied but the given ID is not in the repository.

Examples

Request

Show all XML formats available for ID DLESE-000-000-000-001.

http://www.dlese.org/dds/services/ddsws1-0?

             verb=ListXmlFormats&id=DLESE-000-000-000-001

Response


<?xml version="1.0" encoding="UTF-8" ?> 

<DDSWebService>

  <ListXmlFormats>

    <xmlFormat>adn</xmlFormat>

    <xmlFormat>adn-localized</xmlFormat>

    <xmlFormat>briefmeta</xmlFormat>

    <xmlFormat>nsdl_dc</xmlFormat>

    <xmlFormat>oai_dc</xmlFormat>

  </ListXmlFormats>

</DDSWebService>



UrlCheck

Sample request

The following request searches for all records in the library that have a URL ending in '.pdf':

http://www.dlese.org/dds/services/ddsws1-0?url=http://.pdf&verb=UrlCheck

Summary and usage

The UrlCheck request is used to check whether a given URL is in the DDS repository. This request supports the use of the * wildcard construct. The * character, or wildcard construct, indicates that any character combination is a valid match. For example, a search for http://www.dlese.org/myResource* will match the two URLs http://www.dlese.org/myResource1.html and http://www.dlese.org/myResource2.html. The wildcard construct may appear at any position in the URL argument except the first position.

Arguments

  • url - a required repeatable argument that contains a URL. The url argument may be repeated as many times as desired within a single request.

Errors and exceptions

Error is indicted if the request does not contain the URL argument or if the URL or URLs are not present in the repository.

Examples

Request

Determine whether the URL 'http://epod.usra.edu/' is in the repository. Shown without the required encoding, for clarity.

http://www.dlese.org/dds/services/ddsws1-0?

    verb=UrlCheck&url=http://epod.usra.edu/

Response


<?xml version="1.0" encoding="UTF-8" ?> 

<DDSWebService>

  <UrlCheck>

    <resultInfo>

      <totalNumResults>1</totalNumResults> 

    </resultInfo>

    <results>

      <matchingRecord>

        <url>http://epod.usra.edu/</url> 

        <head>

          <id>DLESE-000-000-000-337</id> 

          <collection recordId="DLESE-COLLECTION-000-000-000-015">

            DLESE Community Collection (DCC)</collection> 

          <xmlFormat>adn</xmlFormat> 

          <fileLastModified>2004-06-24T19:06:08Z</fileLastModified> 

          <whatsNewDate type="itemnew">2003-07-10</whatsNewDate> 

          <additionalMetadata realm="adn">

            <accessionStatus>accessioneddiscoverable</accessionStatus> 

            <partOfDrc>true</partOfDrc> 

            <alsoCatalogedBy collectionLabel="NASA ESE 

                 Reviewed Collection" 

              collectionRecordId="DLESE-COLLECTION-000-000-000-023">

                 NASA-ESERevProd333</alsoCatalogedBy> 

          </additionalMetadata>

        </head>

      </matchingRecord>

    </results>

  </UrlCheck>

</DDSWebService>

Note: responses to this request contain the common head element.

Request

Determine whether the URL 'http://epod.usra.edu/' or 'http://www.marsquestonline.org/index.html' is in the repository.

http://www.dlese.org/dds/services/ddsws1-0?

   verb=UrlCheck&url=http://epod.usra.edu/&

   url=http://www.marsquestonline.org/index.html

Response


<?xml version="1.0" encoding="UTF-8" ?> 

<DDSWebService>

  <UrlCheck>

    <resultInfo>

      <totalNumResults>2</totalNumResults> 

    </resultInfo>

    <results>

      <matchingRecord>

        <url>http://www.marsquestonline.org/index.html</url> 

        ....

      </matchingRecord>

      <matchingRecord>

        <url>http://epod.usra.edu/</url> 

        ...

      </matchingRecord>

    </results>

  </UrlCheck>

</DDSWebService>


Request

Determine whether a URL that begins with 'http://www.dlese.org' is in the repository. The * character acts as a wildcard, which may appear at any position in the URL argument except the first position.

http://www.dlese.org/dds/services/ddsws1-0?

         verb=UrlCheck&url=http://www.dlese.org* 

Response


<?xml version="1.0" encoding="UTF-8" ?> 

<DDSWebService>

  <UrlCheck>

    <resultInfo>

      <totalNumResults>2</totalNumResults> 

    </resultInfo>

    <results>

      <matchingRecord>

        <url>http://www.dlese.org/vgee/index.htm</url> 

        ...

      </matchingRecord>

      <matchingRecord>

        <url>

   http://www.dlese.org/documents/policy/CollectionsScope_final.html

        </url> 

        ...

      </matchingRecord>

    </results>

  </UrlCheck>

 </DDSWebService>


Request

Determine whether the URL 'http://epod.usra.edu/zzzz' is in the repository. In this case no matching records are found.

http://www.dlese.org/dds/services/ddsws1-0?

        verb=UrlCheck&url=http://epod.usra.edu/zzzz 

Response


<?xml version="1.0" encoding="UTF-8" ?> 

<DDSWebService>

  <UrlCheck>

    <resultInfo>

      <totalNumResults>0</totalNumResults> 

    </resultInfo>

  </UrlCheck>

</DDSWebService>



ServiceInfo

Sample request

The following request displays information about this Web service:

http://www.dlese.org/dds/services/ddsws1-0?verb=ServiceInfo

Summary and usage

The ServiceInfo requests is used to retrieve general information about this Web service including name, description, the URL used to access the service (base URL), service version and an administrator e-mail.

Arguments

None

Errors and exceptions

None

Examples

Request

Display information about the Web service

http://www.dlese.org/dds/services/ddsws1-0?verb=ServiceInfo

Response


<?xml version="1.0" encoding="UTF-8" ?> 

<DDSWebService>

  <ServiceInfo>

    <serviceName>

      Digital Library for Earth System Education (DLESE) 

      discovery Web service

    </serviceName>

    <baseURL>http://www.dlese.org/dds/services/ddsws1-0</baseURL>

    <serviceVersion>1.0</serviceVersion>

    <adminEmail>support@dlese.org</adminEmail>

    <compression>gzip</compression>

    <description> ... description here ... </description>

  </ServiceInfo>

</DDSWebService>



Common response elements

Several requests in the protocol share common XML elements in their responses. These include the <head> and <additionalMetadata> elements, which are described below.

The head element

The head element appears in the UserSearch, Search, GetRecord, UrlCheck responses. The head element is used to return information about a single record. This includes the ID of the record, the collection in which the record is a member of, the XML format of the record, the date the record was last modified, the whatsNewDate and an additionalMetadata element.

Head element example:

<?xml version="1.0" encoding="UTF-8" ?> 

...

<head>

   <id>CEIS-000-000-001</id>

   <collection recordId="DLESE-COLLECTION-000-000-000-003">

          Discover Our Earth</collection>

   <xmlFormat>adn</xmlFormat>

   <fileLastModified>2004-07-02T17:32:29Z</fileLastModified>

   <whatsNewDate type="itemnew">2003-07-19</whatsNewDate>

	<additionalMetadata realm="adn">

         ...

        </additionalMetadata>

</head>

...



The additionalMetadata element

The additionalMetadata element appears in UserSearch, Search, GetRecord, UrlCheck and the vocabulary list class of responses. The additionalMetadata element is used to return additional information related to the record's format type, referred to as realms. The information realms include adn and dlese_collect, and each contains slightly different information related to underlying format type.

additionalMetadata element example:

<?xml version="1.0" encoding="UTF-8" ?> 

...

<additionalMetadata realm="adn">

   <accessionStatus>accessioneddiscoverable</accessionStatus>

   <partOfDrc>false</partOfDrc>

   <alsoCatalogedBy collectionLabel="DLESE Community Collection (DCC)"

        collectionRecordId="DLESE-COLLECTION-000-000-000-015">

           DLESE-000-000-000-840</alsoCatalogedBy>

   <alsoCatalogedBy collectionLabel="Cutting Edge" 

        collectionRecordId="DLESE-COLLECTION-000-000-000-010">

           SERC-NAGT-000-000-000-322</alsoCatalogedBy>

</additionalMetadata>

...


Available search fields

This section describes the fields that are available for searching using the Search and UserSearch requests, as well as many of the commands. Fields may contain plain text, controlled vocabularies or encoded field values. The index contains fields derived from multiple XML metadata formats. A given field may contain metadata from a single format or from multiple formats as indicated below. Arbitrary Boolean searches may be performed across and within each of these fields using the Lucene Query Syntax (LQS) supplied in the 'q' argument of the Search request. Example search queries are provided below.

Fields that may be sorted, as indicated, may be supplied in the 'sortAscendingBy' or 'sortDescendingBy' arguments of the Search request.

Text fields - These fields contain plain text or, where indicated, text that has been stemmed using the Porter stemmer algorithm.

When searching in a text field, exact terms are matched. For example a search for ocean will return all documents that contain the exact term ocean in the given field. When searching in a field that has been stemmed, however, all documents containing morphologically similar terms in the given field will be returned. For example a search for ocean will return all documents that contain the terms ocean, oceans or oceanic.

Note that when searching in a field that has been stemmed, the client must not apply the stemming algorithm to the terms. Stemming will be applied automatically by the search engine for the fields that support it - no pre-processing is necessary by the client.

  • default - The default field represents the text that is most appropriate for searching by humans using natural language queries. The default field contains text extracted from different locations in the metadata depending on the XML format. The default field is the only field that does not require the use of a field specifier in the LQS query clause (e.g. the clause "default:ocean" and "ocean" are equivalent). May not be sorted. Available for formats:
    • adn: Includes title, description, keyword, resource type, subjects, event names, place names, temporal coverage names, terms found in the primary URL, and creators last name. May be sorted.
    • dlese_collect: Includes full title, short title, description, subjects, keywords, and terms extracted from the primary URL, scope URL and review process URL.
    • dlese_anno: Includes title, description and terms extracted from the URL.
    • news_opps: Includes title, description, keywords, announcements, topics, audience, diversities, location, and sponsors institution.

  • stems - Identical to the default field, however all terms are in stemmed form. May not be sorted.

  • title - Contains the titles of resources or items, as text. May be sorted. Available for formats: adn, news_opps.

  • titlestems - Contains the titles of resources or items, as stemmed text. May not be sorted. Available for formats: adn.

  • url - Contains the URL for the resource tokenized as text. Useful search clause examples include http*nasa.gov* or http*.edu*. May be sorted. Available for formats: adn.

  • description - Contains the descriptions of resources or items, as text. May be sorted. Available for formats: adn, dlese_collect, news_opps.

  • keyword - Contains keywords associated with the resource or item, as text. May be sorted. Available for formats: adn, dlese_collect, news_opps.

  • creator - Contains the first, middle and last name of each contributor for the resource. May not be sorted. Available for formats: adn.

  • organizationInstName - Contains the name of the contributing institution. May be sorted. Available for formats: adn.

  • organizationInstDepartment - Contains the name of the contributing institution's department. May be sorted. Available for formats: adn.

  • personInstName - Contains the name of the contributing person's institution. May be sorted. Available for formats: adn.

  • personInstDepartment - Contains the name of the contributing person's institutional department. May be sorted. Available for formats: adn.

  • emailPrimary - The primary contributor's e-mail. May be sorted. Available for formats: adn.

  • emailOrganization - The contributing organization's e-mail. May be sorted. Available for formats: adn.

  • emailAlt- The alternate contributor's e-mail. May be sorted. Available for formats: adn.

  • placeNames - Place names, for example "colorado," "AZ," "Brazil," as text. May be sorted. Available for formats: adn.

  • eventNames - Event names, for example "windstorm," "Destruction of Pompeii," as text. May be sorted. Available for formats: adn.

  • temporalCoverageNames - Temporal coverage names, for example "cambrian," "Triassic Period," as text. May be sorted. Available for formats: adn.

  • itemAudienceTypicalAgeRange - The typical age range for this resource. Available for formats: adn.

  • itemAudienceInstructionalGoal - The instructional goals for this resource. Available for formats: adn.

  • newsOppstitle - News & Opportunities title. May be sorted. Available for formats: news_opps.

  • newsOppsdescription - News & Opportunities description. May be sorted. Available for formats: news_opps.

  • newsOppskeyword - News & Opportunities keywords. May be sorted. Available for formats: news_opps.

Textual content - These fields contain the text of the content of the resources themselves. These are available for all resources in the library whose primary content is in HTML or PDF.

  • itemContent - The full textual content of the resource. May be sorted. Available for formats: adn.

  • itemContentTitle - The HTML title element text. May be sorted. Available for formats: adn.

  • itemContentHeaders - The HTML header element (H1, H2, etc.) text. May be sorted. Available for formats: adn.

  • itemContentType - The HTTP content type header terms that were returned by the Web server that holds the resource, for example "text html", "application pdf". May be sorted. Available for formats: adn.

Textual vocabulary fields - These fields contain DLESE controlled vocabularies that have been indexed as plain text.

  • gradeRange - The DLESE grade range vocabularies verbatim as text, for example "DLESE:Primary elementary." These values may be discovered using the ListGradeRange request within the vocabEntry element. May be sorted. Available for formats: adn, dlese_collect.

  • resourceType - The DLESE resource type vocabularies verbatim as text, for example "DLESE:Learning materials:Classroom activity." These values may be discovered using the ListResourceTypes request within the vocabEntry element. May be sorted. Available for formats: adn, dlese_collect.

  • subject - The DLESE subject vocabularies verbatim as text, for example "DLESE:Atmospheric science." These values may be discovered using the ListSubjects request within the vocabEntry element. May be sorted. Available for formats: adn, dlese_collect.

  • contentStandard - The DLESE content standard vocabularies verbatim as text, for example "NSES:K-4:Unifying Concepts and Processes Standards:Change, constancy, and measurement." These values may be discovered using the ListContentStandards request within the vocabEntry element. May be sorted. Available for formats: adn.




  • itemannotypes - Indicates the type of annotation that this item has, for example "Teaching tip," "Information on challenging teaching and learning situations," as text. These values are shown in the types schema. May be sorted. Available for formats: adn.

  • itemannostatus - Indicates the status of an annotation that this item has, for example "Text annotation completed," as text. These values are shown in the status schema. May be sorted. Available for formats: adn.

  • itemannoformats - Indicates the format of an annotation that this item has. Values include 'text', 'audio', 'video' and 'graphical'. May be sorted. Available for formats: adn.

  • itemannopathways - Indicates the pathway of an annotation that this item has, for example "CRS (Community Review System)," as text. These values are shown in the pathway schema. May be sorted. Available for formats: adn.

  • newsOppsannouncement - News & Opportunities announcements. May be sorted. Available for formats: news_opps.

  • newsOppsaudience - News & Opportunities audience. May be sorted. Available for formats: news_opps.

  • newsOppsdiversity - News & Opportunities diversity. May be sorted. Available for formats: news_opps.

  • newsOppslocation - News & Opportunities locations. May be sorted. Available for formats: news_opps.

  • newsOppstopic - News & Opportunities topics. May be sorted. Available for formats: news_opps.

Encoded vocabulary fields - These fields contain DLESE controlled vocabularies that have encoded into keys. Corresponding textual vocabulary fields are listed above, e.g. the same information is indexed both as text and as keys for these fields: gr - gradeRanges; re - resourceTypes; su - subjects; cs - contentStandards.

  • gr - The DLESE grade range vocabularies encoded as a two or three character key, for example "05." These values may be discovered using the ListGradeRanges request within the searchKey element. May be sorted. Available for formats: adn.

  • re - The DLESE resource type vocabularies encoded as a two or three character key, for example "05." These values may be discovered using the ListResourceTypes request within the searchKey element. May be sorted. Available for formats: adn.

  • su - The DLESE subject vocabularies encoded as a two or three character key, for example "05." These values may be discovered using the ListSubjects request within the searchKey element. May be sorted. Available for formats: adn.

  • cs - The DLESE content standard vocabularies encoded as a two or three character key, for example "05." These values may be discovered using the ListContentStandards request within the searchKey element. May be sorted. Available for formats: adn.

  • ky - The DLESE collections vocabularies encoded as a two or three character key, for example "05." These values may be discovered using the ListCollections request within the searchKey element. May be sorted. Available for formats: adn.

Defined key fields - These fields contain finite sets of key values such as "true" or "false" that may be used to limit searches to a sub-set of records.

  • itemhasanno - Indicates whether an item has an annotation. Values are either "true" or "false." May be sorted. Available for formats: adn.

  • partofdrc - Indicates whether the item or collection is part of the DLESE Reviewed Collection (DRC). Values are either "true" or "false." May be sorted. Available for formats: adn, dlese_collect.

  • multirecord - Indicates whether the resource that the record catalogs is also cataloged by other records in other collections. Values are either "true" or "false." May be sorted. Available for formats: adn.

  • collection - Contains the record's collection vocabulary entry pre-pended with a 0, for example "0dcc," "0comet.". These values may be discovered using the ListCollections request within the vocabEntry element. May be sorted. Available for all formats.

  • wntype - Indicates the reason the item is new to the library, corresponding to the 'wndate' field. Possible values are: itemnew, itemannocomplete, itemannoinprogress, annocomplete, drcannocomplete, drcannoinprogress, collection. May be sorted. Available for all formats.

Fields available for searching by value or range of value - These fields may be searched by exact value or by range of value:

  • itemannoaveragerating - Contains the average of all star ratings assigned to a given resource. Values range from 1.000 to 5.000. Example search syntax itemannoaveragerating:[3.500 TO 5.000] - returns all resources with an average star rating of 3.5 to 5.0. May be sorted. Available for formats:adn.

  • itemannoratingvalues - Contains all star ratings assigned to a given resource. Values range from 1 to 5. Example search syntax itemannoratingvalues:[3 TO 5] - returns all resources that have one or more ratings of 3, 4, or 5 stars assigned to them. May be sorted. Available for formats:adn.

  • itemannonumratings - Contains the number of star ratings that have been assigned to a given resource. Values are encoded to 5 digits, for example 00000 or 00014. Example search syntax itemannonumratings:[00004 TO 99999] - returns all resources that have from 4 to 99999 star ratings assigned to them. May be sorted. Available for formats:adn.

  • annorating - Contains the star rating of a given annotation record. Values are integers from 1 to 5. Example search syntax annorating:[3 TO 5] - returns all annotations that have a start rating of 3 to 5. May be sorted. Available for formats: dlese_anno.

Fields available for searching by date - These fields may be supplied in the 'dateField' argument of the Search request:

  • wndate - A date field that indicates the date the item was new to the library, corresponding to the 'wntype' field. May be sorted. Available for all formats.

  • accessiondate - The ADN accession date for the record. May be sorted. Available for formats: adn.

  • collaccessiondate - The dlese_collect accession date for the collection. May be sorted. Available for formats: dlese_collect.

  • modtime - A date field that corresponds to the time the items file was last modified or touched. This does not necessarily indicate that the content in the record changed. May be sorted. Available for all formats.

  • newsOppsapplyBydate - News & Opportunities applyBy date. May be sorted. Available for formats: news_opps.

  • newsOppsarchivedate - News & Opportunities archive date. May be sorted. Available for formats: news_opps.

  • newsOppsduedate - News & Opportunities due date. May be sorted. Available for formats: news_opps.

  • newsOppseventStartdate - News & Opportunities eventStart date. May be sorted. Available for formats: news_opps.

  • newsOppseventStopdate - News & Opportunities eventStop date. May be sorted. Available for formats: news_opps.

  • newsOppspostdate - News & Opportunities post date. May be sorted. Available for formats: news_opps.

  • newsOppsrecordCreationdate - News & Opportunities recordCreation date. May be sorted. Available for formats: news_opps.

  • newsOppsrecordModifieddate - News & Opportunities recordModified date. May be sorted. Available for formats: news_opps.


Example search queries

This section shows some examples of performing searches using the Search or UserSearch request. To perform these searches, the values shown below should be supplied in the 'q' argument, using the Lucene Query Syntax (LQS). Additional arguments may be supplied to the Search or UserSearch request to further limit the search, such as xmlFormat, dateField and the vocabulary fields gr, su, re and cs.

Search for the term 'ocean' in the default field:

ocean

Search for the term 'ocean' in the stems field. This will return documents containing morphologically similar terms including ocean, oceans and oceanic

stems:ocean

Search for resources that that have an average star rating of 3.5 to 5.0:

itemannoaveragerating:[3.500 TO 5.000]

Search for resources that contain 'noaa.gov' in their URL:

url:http*noaa.gov*

Search for the term ocean within resources from 'noaa.gov':

url:http*noaa.gov* AND ocean

Search for term 'estuary' in the stems field, and limit the search to subject biological oceanography (subject key 02):

stems:estuary AND su:02

Search for the term 'ocean' in the default field, and boost the ranking of results that contain 'ocean' in their title (stemmed) (uses the special clause allrecords:true to select the set of all records). Note that this clause returns the same number of results as if the search were performed only over the word 'ocean' in the default field, but it applies additional boosting for records that contain the term 'ocean' in their title (stemmed), which augments the page rank of the results that are returned. This example illustrates the kind of page rank augmentation that is applied automatically in the UserSearch request.

ocean AND (allrecords:true OR titlestems:ocean^2)

Show all records with subject biological oceanography, and boost results that contain florida in the title (stemmed), description or placeNames fields (uses the clause allrecords:true to select the set of all records):

su:02 AND (allrecords:true OR titlestems:florida*^20
                  OR description:florida*^20 OR placeNames:florida^20)

Glossary

whatsNewDate - A date that describes when an item was new to the library. Generally this corresponds to the item's accession date or the date in which the item first became accessible in the library.

University Corporation for Atmospheric Research (UCAR) National Science Foundation (NSF) National Science Digital Library (NSDL)