The UCARConnect Search API provides the ability to perform faceted search for the following categories: Audience, Education Level, Subject, Type, and Education Standards (hierarchical ASN identifiers).
To see a list of available categories and faceted terms within, issue the following ListTerms request: http://nsdl.org/dds-search?field=$facets&verb=ListTerms
The Search request is used for faceting. Include the following required and optional arguments to enable faceting features. These must be included in addition to the normal arguments for Search like q, n, s, ky, xmlFormat, etc. Facet counts apply across the records that match the given search criteria. Facet results (XML element <facetResults>) are returned at the top of the Search response.
facet=on - (required) - Turns faceting onfacet.category=<facetCategory> - (required) - Indicates the facet category you wish to collect facet totals for. The facetCategory token must be one of the available categories (listed above). Repeat this argument to return multiple categories if desired.facet.maxResults=<Integer> - (optional) - Indicates the maximum number of results. Defaults to 10. This argument can be specified on a per-category basis with the syntax of f.<facetCategory>.maxResultsfacet.maxDepth=<Integer> - (optional) - Indicates the maximum depth to display down the facet hierarchy path. Defaults to 10. This argument can be specified on a per-category basis with the syntax of f.<facetCategory>.maxDepthfacet.maxLabels=<Integer> - (optional) - Indicates the maximum number of labels to show in the results. Labels are expensive to calculate so response time can be improved by using a lower number here. If a label is not returned, the facetId can be used to determine the label, provided you've cached the list of facetIds and their corresponding labels in your client somewhere. The facetIds may change when the search index is updated. Defaults to 1000. This argument can be specified on a per-category basis with the syntax of f.<facetCategory>.maxLabelsf.<facetCategory>.path=<hierarchy/path> - (optional) - Indicates a position in the hierarchy path to start faceting from. This only applies if the given category has a hierarchy greater than one. If not used then results are returned starting at the root. The delimiter character used in the path must match the one that was specified in the config for the given category and that is reflected in the <facetResult> response. As an example, given the following facet taxonomy Book/Fiction/Science Fiction/Fahrenheit 451 where 'Book' represents the category and 'Fiction/Science Fiction/Fahrenheit 451' represents a possible path through the taxonomy and '/' is the delimiter character, f.Book.path=Fiction/Science Fiction would return facet results for Science Fiction and below, only.facet=on, but you can request facet totals again while doing a drill-down if desired.f.drilldown.category=<facetCategory> - (required) - Indicates the facet category you wish to drill down into. Token must be the same as the one specified in the <facetResult> response. Repeat this argument to filter results by multiple facet categories (AND logic).f.drilldown.<facetCategory>.path - (optional) - Indicates the category path you wish to drill down into. Path must be the same as the one specified in the <facetResult> response. If omitted then the search results are filtered by the top-level category only.http://nsdl.org/dds-search?verb=Search&q=oceans&s=0&n=10&facet=on&facet.category=Typen=0 to retrieve facet counts without any records:http://nsdl.org/dds-search?verb=Search&q=oceans&s=0&n=0&facet=on&facet.category=Typehttp://nsdl.org/dds-search?verb=Search&q=oceans&s=0&n=10&facet=on&facet.category=Type&facet.category=AudienceType, filtering results to resource type Instructional Material only, and also request facet counts in the result set:http://nsdl.org/dds-search?verb=Search&q=oceans&s=0&n=10&f.drilldown.category=Type&f.drilldown.Type.path=Instructional%20Material&facet=on&facet.category=Type&facet.category=Audience