Announcement: The operation of NSDL has been transferred to ISKME's OER Commons (effective December, 2014) - Read the news release.
This documentation describes the policies, procedures, and services that existed while NSDL was operated by UCAR.
The baseURL is http://nsdl.org/dds-search
Yes. Education Level, Resource Type, Access Rights, Language, Medium, and MimeType are fixed controlled vocabularies that are normalized in the NSDL DC metadata and search index. Subject also has a controlled vocabulary but the metadata is not filtered so there are other subject vocabularies and keyword that appear in that field.
To filter a search by a given field/term, add a Boolean clause to the query supplied in the 'q' argument, for example (user's typed keywords) AND /key//nsdl_dc/educationLevel:"Middle School" AND xmlFormat:nsdl_dc
For example, the following request performs a search for 'video' filtered to Middle School education level only:
http://nsdl.org/dds-search?verb=Search&q=(video) AND /key//nsdl_dc/educationLevel:"Middle School" AND xmlFormat:nsdl_dc&s=0&n=10
This request will search for Movie/Animation in the type field (instead of searching the record for the word 'video') and Middle School education level:
Fields that start with /key//nsdl_dc/ correspond to metadata elements in the NSDL DC metadata framework, which represents the educational resources in the library. See this NSDL DC metadata guide for details.
Use the ListTerms API request to fetch the list of available terms for each field (to get a list of fields, use ListFields).
For example, these requests list the terms/vocabs for Education Level and Type, respectively: http://nsdl.org/dds-search?verb=ListTerms&field=/key//nsdl_dc/educationLevel http://nsdl.org/dds-search?verb=ListTerms&field=/key//nsdl_dc/type
The repository contains multiple types of records that are expressed in different XML formats. The canonical XML format for educational resources is NSDL DC (
nsdl_dc), which should be used for most search applications. Other formats that appear in the repository are
comm_anno, which contain annotation data (comments, tips, reviews, etc.),
comm_para, which contains usage summary data (favorited 12 times, etc.), Learning Application Ready
lar metadata, which is richer format that describes educational resources, and
dlese_collect, which contains metadata about the collections in the repository. Note that for each
lar metadata record in the repository, there is a corresponding
To filter your search to only the canonical NSDL DC format, add a Boolean query clause to your search query to require
xmlFormat:nsdl_dc. For example:
(user keywords) AND (xmlFormat:nsdl_dc). This will filter the search to only those resources that have one or more
nsdl_dc record for them.
The search and browse pages at NSDL.org are implemented using the Search API. The UI provides keyword search as well as options to search and filter by Grade Level, Resource Type, Subject, and Pathway. For example, see this search for 'ocean' with 'Grade Level: Elementary School' selected.
To see the full API request that is used for a given search in the NSDL.org UI, first perform a search like you normally would and then add the http param &showquery=1 to the url in your browser, for example: http://nsdl.org/search/index.php?q=ocean&submitButton=Go&n=10&educationLevel%5B%5D=Elementary+School&showquery=1
The q argument in the API request contains the search query, for example from the above: (((ocean) OR stems:(ocean) OR title:(ocean) OR titlestems:(ocean) OR description:(ocean) OR descriptionstems:(ocean))) AND (/key//nsdl_dc/educationLevel "Elementary School")) AND xmlFormat:nsdl_dc
Here the term 'ocean' is expanded to search across the default, stems, title, titlestems, description and descriptionstems fields, which is done to boost the rank ordering for matches in the title, titlestems, description and descriptionstems fields of the record while also including matches in the default and stems fields.
The next clause in the query, AND (/key//nsdl_dc/educationLevel "Elementary School"), filters the search to education/grade level "Elementary School". The final clause, AND xmlFormat:nsdl_dc, filters the search to NSDL DC records only, which are the educational resources in the library.
Refer to the API documentation for information about what the other request parameters are used for. NSDL.org uses some advanced features from DDS, which may not be needed for many applications. Play around with this UI and compare the request that is being sent to see what is going on.
The Search request allows you to construct Lucene queries that operate over any field in the search index, supplied in the q argument of the request. A text query without any explicit field specifier is applied to the default field, which contains the full text of the resource metadata and the crawled content of the front page of the resource itself. Applying a user's search terms to the default field produces fairly good results but it is often better to apply query expansion techniques such as stemming to increase the scope of the search and to perform boosting to augment the ordering of the results to bring more relevant resources to the top of the hit list.
The index contains a number of search fields that are useful for query expansion and boosting. These include but are not limited to:
To apply query expansion, construct a Boolean query using the Lucene syntax to expand the user's query across the desired fields, and then supply this in the q argument in the Search request. For example, if the user has typed a search for the word ocean, the following progression illustrates how the expanded query might be constructed:
Note that for the stemmed fields it is not necessary to stem the words supplied in the query - just supply the user's text exactly as it was typed and the Search API will automatically apply word stemming in the appropriate fields for you. Because the colon is a reserved character in the Lucene syntax, these and other reserved characters should be filtered out prior to issuing the query, unless you want to allow the user to perform Lucene queries themselves.
One more Boolean clause that is often desirable is to restrict the search to educational resources only by adding a clause xmlFormat:nsdl_dc to the query:
This final example is the query expansion technique used for user's searches at nsdl.org.
The following query will show you your collection's resources that are referenced by paradata collections from a certain collection (i.e. your own paradata collection). This particular example uses the SMILE resource and paradata collection keys (ncs-NSDL-COLLECTION-000-003-112-056 and ncs-NSDL-COLLECTION-000-003-112-075 respectively). Replace these with your own collection keys. If you are not sure what the collection key is, use the search request http://nsdl.org/dds-search?verb=ListCollections to find the <searchKey> for your collection.
This query, on the other hand, will show the resources from your collection that are not associated with paradata from your paradata collection (again, replace collection keys with your own).
http://nsdl.org/dds-search?verb=Search&q=(*:* NOT isRelatedToByCollectionKey:"ncs-NSDL-COLLECTION-000-003-112-075")&ky=ncs-NSDL-COLLECTION-000-003-112-056&s=0&n=100 (http://nsdl.org/dds-search?verb=Search&q=(*:*%20NOT%20isRelatedToByCollectionKey:%22ncs-NSDL-COLLECTION-000-003-112-075%22)&ky=ncs-NSDL-COLLECTION-000-003-112-056&s=0&n=100)
Replace in the above query with the url you are searching for.
This query will give you all nsdl_dc records with ASN standards aligned (adjust n=100 for # of results shown):
This query will give you all comm_anno records with ASN standards aligned (adjust n=100 for # of results shown):
This query will give you all nsdl_dc records with Strand Map Service ID's associated with them:
Yes. See Faceted Search for details.
Yes. Deduping is applied to matching
nsdl_dc results in the Search API and is designed to remove duplicate returns from being displayed in the search results at NSDL.org and other portals/applications built on the Search API. By default the API returns the single
nsdl_dc metadata record that best matches the search criteria. For example, suppose a given resource URL has multiple
nsdl_dc metadata entries that describe it, one from collection A, another from collection B, and a third from collection C. When a search is performed that matches the resource, the results will return the single nsdl_dc metadata record that best matches the search criteria, and it may return different metadata for different searches depending on the terms and field classifiers indicated in the search. If the search indicates collection A as it's sole search criteria for example, the API will return the metadata from partner A, likewise if partner B is indicated, collection B's metadata will be returned. Best match is calculated using standard IR algorithms applied to all search criteria indicated including search terms, fielded classifiers (Grade Range, Subject, etc.), and collection, compared against the metadata features (terms and classifiers) that appear in the records.
By default only the best matching
nsdl_dc metadata record is returned. To have all available
nsdl_dc metadata returned, however, include the argument
&relation=alsoCatalogedBy in the
Search request. If more than one
nsdl_dc metadata record is available for given
Search result, they will appear in the
<relations> portion of the XML response.