Facets

Introduction

Some screenshots of Facets in the interfaces of different Elsevier products:

Science Direct:



Scopus:



The parameter 'facets' is a list of fields with an optional depth of categories that should be returned:

facets=nav_1 ([count=number,][sort=sortspec,][prefix=filter]);nav_2(...);nav_3(...);...

a) nav_n must be valid facet name sent to the appropriate API cluster (see tables in following sections). Invalid facets will be ignored. Parameter scomode=on is required for this feature.

b) count=number is optional, where number indicates the number of facet entries to be returned. The number will be truncated if it exceeds the maximum allowed based upon entitlement settings.

c) sort=sortspec is optional, where sortspec is one of the codes listed here:

sortspec Sort by...
na Modifier name, ascending
fd Modifier frequency, descending
fdna Modifier frequency descending, secondary sort through unity by name, ascending

Returned modifiers for nav_n are sorted according to sortspec. If sort parameter is not used, default sortspec is fd for all navigators except the scopubyrnav. The scopubyrnav defaults to sort by name in descending order.

d) prefix=filter is optional, where filter is a sequence of one or more alpha-numeric characters. Returned modifiers for nav_n are limited to those starting with filter. Only prefix filtering is possible, and filtering is case-sensitive and sensitive to the use of accented characters. The prefix will be ignored if filter contains spaces or non-alphanumeric characters.

e) The sort and prefix parameters are applied independently for each facet nav_n specified.

f) If prefix parameter is not used, modifiers are not filtered.

g) If a facet is not listed, it will not be included in the result.

Obviously, this is quite a lot of rules...here is an example that might help clear up some of the above:

The Request:

http://api.elsevier.com/content/search/scopus?query=heart&facets=pubyear(count=3);doctype();subjarea(count=5);language(count=4);af_id(count=10);exactkeyword(count=20);srctype()&count=1

This request takes each specified facet and limits the search results by the specified count. This is a fairly typical application of facets.

The Response:

<feed xmlns="http://www.w3.org/2005/Atom" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:prism="http://prismstandard.org/namespaces/basic/2.0/">
<title>SCOPUS Search Results: heart</title>
<updated>2011-05-23T20:20:06.847Z</updated>
 <author>
 <name>Elsevier, Inc.</name>
 </author>
 <id>http://api.elsevier.com:80/content/search/scopus?query=heart&amp;count=1&amp;start=0&amp;facets=pubyear(count=3);doctype();subjarea(count=5);language(count=4);af_id(count=10);exactkeyword(count=20);srctype()&amp;view=STANDARD&amp;field=</id>
 <opensearch:totalResults>2335755</opensearch:totalResults>
 <opensearch:startIndex>0</opensearch:startIndex>
 <opensearch:itemsPerPage>1</opensearch:itemsPerPage>
 <opensearch:Query role="request" searchTerms="heart" startPage="0"/>
 <link href="http://api.elsevier.com:80/content/search/scopus?query=heart&amp;start=0&amp;count=1&amp;facets=pubyear(count=3);doctype();subjarea(count=5);language(count=4);af_id(count=10);exactkeyword(count=20);srctype()&amp;view=STANDARD&amp;field=" ref="self" type="application/atom+xml"/>
 <link href="http://api.elsevier.com:80/content/search/scopus?query=heart&amp;start=0&amp;count=1&amp;facets=pubyear(count=3);doctype();subjarea(count=5);language(count=4);af_id(count=10);exactkeyword(count=20);srctype()&amp;view=STANDARD&amp;field=" ref="first" type="application/atom+xml"/>
 <link href="http://api.elsevier.com:80/content/search/scopus?query=heart&amp;start=1&amp;count=1&amp;facets=pubyear(count=3);doctype();subjarea(count=5);language(count=4);af_id(count=10);exactkeyword(count=20);srctype()&amp;view=STANDARD&amp;field=" ref="next" type="application/atom+xml"/>
    <link href="http://api.elsevier.com:80/content/search/scopus?query=heart&amp;start=2335754&amp;count=1&amp;facets=pubyear(count=3);doctype();subjarea(count=5);language(count=4);af_id(count=10);exactkeyword(count=20);srctype()&amp;view=STANDARD&amp;field=" ref="last" type="application/atom+xml"/>
    <entry>
        <link href="http://api.elsevier.com/content/abstract/scopus_id/78649662114" ref="self"/>
        <link href="http://www.scopus.com/inward/record.url?partnerID=HzOxMe3b&amp;scp=78649662114" ref="scopus"/>
        <link href="http://www.scopus.com/inward/citedby.url?partnerID=HzOxMe3b&amp;scp=78649662114" ref="scopus-citedby"/>
        <prism:url>http://api.elsevier.com/content/abstract/scopus_id/78649662114</prism:url>
        <dc:identifier>scopus_id/78649662114</dc:identifier>
        <dc:title>Heart failure severity, as determined by loop diuretic dosages, predicts the risk of developing diabetes after myocardial infarction: A nationwide cohort study</dc:title>
        <dc:creator>Andersson, C.</dc:creator>
        <prism:publicationName>European Journal of Heart Failure</prism:publicationName>
        <prism:issn>13889842 18790844</prism:issn>
        <prism:volume>12</prism:volume>
        <prism:issueIdentifier>12</prism:issueIdentifier>
        <prism:pageRange>1333-1338</prism:pageRange>
        <prism:coverDate>2010-12-01</prism:coverDate>
        <prism:doi>10.1093/eurjhf/hfq160</prism:doi>
        <citedby-count>1</citedby-count>
        <affiliation/>
        <affiliation>
            <affilname>Steno Diabetes Center | Steno Diabetes Center ^</affilname>
        </affiliation>
        <affiliation/>
        <prism:aggregationType>Journal</prism:aggregationType>
        <subtype>ar</subtype>
    </entry>
    <facet>
        <name>pubyear</name>
        <attribute>scopubyr</attribute>
        <category>
            <name>2843</name>
            <hitCount>1</hitCount>
        </category>
        <category>
            <name>2826</name>
            <hitCount>1</hitCount>
        </category>
        <category>
            <name>2823</name>
            <hitCount>1</hitCount>
        </category>
    </facet>
    <facet>
        <name>doctype</name>
        <attribute>scosubtype</attribute>
        <category>
            <name>ar</name>
            <hitCount>1574282</hitCount>
        </category>
        <category>
            <name>re</name>
            <hitCount>248392</hitCount>
        </category>
        <category>
            <name>cp</name>
            <hitCount>101272</hitCount>
        </category>
    </facet>
    <facet>
        <name>subjarea</name>
        <attribute>scosubjabbr</attribute>
        <category>
            <name>MEDI</name>
            <hitCount>1603190</hitCount>
        </category>
        <category>
            <name>BIOC</name>
            <hitCount>453693</hitCount>
        </category>
        <category>
            <name>PHAR</name>
            <hitCount>166349</hitCount>
        </category>
        <category>
            <name>NEUR</name>
            <hitCount>77340</hitCount>
        </category>
        <category>
            <name>AGRI</name>
            <hitCount>67425</hitCount>
        </category>
    </facet>
    <facet>
        <name>language</name>
        <attribute>scolang</attribute>
        <category>
            <name>English</name>
            <hitCount>1814987</hitCount>
        </category>
        <category>
            <name>German</name>
            <hitCount>79727</hitCount>
        </category>
        <category>
            <name>French</name>
            <hitCount>55877</hitCount>
        </category>
        <category>
            <name>Russian</name>
            <hitCount>47651</hitCount>
        </category>
    </facet>
    <facet>
        <name>exactkeyword</name>
        <attribute>scoexactkeywords</attribute>
        <category>
            <name>Human</name>
            <hitCount>1425177</hitCount>
        </category>
        <category>
            <name>Article</name>
            <hitCount>1302150</hitCount>
        </category>
        <category>
            <name>Male</name>
            <hitCount>876933</hitCount>
        </category>
        <category>
            <name>Priority journal</name>
            <hitCount>845313</hitCount>
        </category>
        <category>
            <name>Humans</name>
            <hitCount>841536</hitCount>
        </category>
        <category>
            <name>Female</name>
            <hitCount>755270</hitCount>
        </category>
        <category>
            <name>Adult</name>
            <hitCount>647498</hitCount>
        </category>
        <category>
            <name>Controlled study</name>
            <hitCount>541073</hitCount>
        </category>
        <category>
            <name>Nonhuman</name>
            <hitCount>415788</hitCount>
        </category>
        <category>
            <name>Aged</name>
            <hitCount>391236</hitCount>
        </category>
        <category>
            <name>Animals</name>
            <hitCount>317486</hitCount>
        </category>
        <category>
            <name>Major clinical study</name>
            <hitCount>301733</hitCount>
        </category>
        <category>
            <name>Heart</name>
            <hitCount>290208</hitCount>
        </category>
        <category>
            <name>Middle Aged</name>
            <hitCount>288122</hitCount>
        </category>
        <category>
            <name>Review</name>
            <hitCount>250527</hitCount>
        </category>
        <category>
            <name>Animal</name>
            <hitCount>247381</hitCount>
        </category>
        <category>
            <name>Animal experiment</name>
            <hitCount>213232</hitCount>
        </category>
        <category>
            <name>Clinical article</name>
            <hitCount>182021</hitCount>
        </category>
        <category>
            <name>Case report</name>
            <hitCount>180947</hitCount>
        </category>
        <category>
            <name>Rat</name>
            <hitCount>178214</hitCount>
        </category>
    </facet>
    <facet>
        <name>srctype</name>
        <attribute>scosrctype</attribute>
        <category>
            <name>j</name>
            <hitCount>2151361</hitCount>
        </category>
        <category>
            <name>p</name>
            <hitCount>25638</hitCount>
        </category>
        <category>
            <name>k</name>
            <hitCount>14380</hitCount>
        </category>
    </facet>
</feed>

Different facets are available to the RESTful APIs depending on which cluster is searched.


SCIDIR Cluster Facet Values

Field Facet Name Default number of values to return counts for Maximum number of values to return counts for Sorting
Content type, using label contenttype All All Journal, Book, Reference Work
Journal/Book title srctitle 5 20 Result count, descending
Year pubyr 5 20; if there are more than 20 years, the last result count will be for "Year X and before" (similar to what ScienceDirect does). Year, descending
Topics topics X X X

SCOPUS Cluster Facet Values

Field Facet Name Default number of values to return counts for Maximum number of values to return counts for Sorting
Source title exactsrctitle 3 30 Result count, descending
Author name, based on author ID, but showing the name au-id 3 30 Result count, descending
Year pubyear 3 30 Year, descending
Document type, using label doctype 3 All Result count, descending
Subject area, using label subjarea 5 All Result count, descending
Language, using label language 3 All Result count, descending
Affiliation, based on affiliation ID, but showing affiliation name af-id 3 30 Result count, descending
Keyword exactkeyword 3 All Result count, descending
Source type, using label srctype 3 30 Result count, descending

AUTHOR Cluster Facet Values

Field Facet Name Default number of values to return counts for Maximum number of values to return counts for Sorting
Source title srctitle 3 30 Result count, descending
Affiliation af-id 3 30 Result count, descending
City affilcity 3 30 Result count, descending
Country affilcountry 3 30 Result count, descending
Subject area, using label auth-subclus 3 All Result count, descending

AFFILIATION Cluster Facet Values

Field Facet Name Default number of values to return counts for Maximum number of values to return counts for Sorting
City affilcity 3 30 Result count, descending
Country affilcountry 3 30 Result count, descending