Search Service
Search Service

About

The Search service provides methods for querying RUcore, obtaining search form profiles, facets and individual resource responses.

The base URL for our search server is

Responses

Responses can be formed in XML, JSON, or serialized PHP depending on the method being used. Further detail can be found under each methods documentation.

Methods

  • Facets
  • Form
  • Record
  • Query

Facets

Top

Provides search facet results for a given portal.

HTTP Method

GET

URI

https://rucore.libraries.rutgers.edu/api/search/facets/

Request URL Pattern

https://rucore.libraries.rutgers.edu/api/search/facets/{parameters}

Parameters

Parameter Value Description
key string (required) Portal key used to provide access to the API, system generated when portal is created.
output string (optional)
  • xml
    Resulting data is formatted in XML and returned with mime-type: application/xml
  • json
    Resulting data is formatted in JSON and returned with mime-type: application/json
  • php
    Resulting data is formatted in serialized PHP and returned with mime-type: application/x-httpd-php
This value is optional and controls the format of the resulting list. Current default is xml.
orderby string (optional)
  • alpha
    Order results in response alphabetically.
  • hits
    Order results in response by number of hits
This value is optional and controls the order of the results. Current default is hits.
facet[] array (optional)
  • facet:author
  • facet:coinsTemporal
  • facet:dateTemporal
  • facet:degreeDate
  • facet:denomination
  • facet:etdDegree
  • facet:etdDiscipline
  • facet:etdSubject
  • facet:genre
  • facet:interviewee
  • facet:interviewer
  • facet:lastName
  • facet:medium
  • facet:moneyer
  • facet:phyPropNote
  • facet:schooldept
  • facet:titlebeginswith
  • facet:topic
If you choose you can request one or many facet field in the response. To do this provide the facet field(s) as a parameter. If you do not provide this parameter all facet fileds will be returned.

Sample Request - for accessing all facets for a portal with key root

https://rucore.libraries.rutgers.edu/api/search/facets/?key=root

Sample Request - for accessing all topic facets for a portal with key root

https://rucore.libraries.rutgers.edu/api/search/facets/?key=root&facet[]=facet:topic

Sample Request - for accessing all topic and author facets ordered alphabetically for a portal with key root

https://rucore.libraries.rutgers.edu/api/search/facets/?key=root&facet[]=facet:topic&facet[]=facet:author&orderby=alpha
Sample output in XML format
In this example above the <root> element has a subelement <facets> that contains 1 or many subelements <facet>. This is determined by the request.

Each <facet> has a series of ATTRIBUTES explained below:

  • @fieldFacet field
  • @quantityNumber of facet values; indicated in the <term> subelements.

The subelement(s) that appears in <facet> supply the facet <term> and the number of occurrences, @hits, of that facet.

Form

Top

Provides search facet results for a given portal.

HTTP Method

GET

URI

https://rucore.libraries.rutgers.edu/api/search/form/

Request URL Pattern

https://rucore.libraries.rutgers.edu/api/search/form/{parameters}

Parameters

Parameter Value Description
key string (required) Portal key used to provide access to the API, system generated when portal is created.
output string (optional)
  • xml
    Resulting data is formatted in XML and returned with mime-type: application/xml
  • json
    Resulting data is formatted in JSON and returned with mime-type: application/json
  • php
    Resulting data is formatted in serialized PHP and returned with mime-type: application/x-httpd-php
This value is optional and controls the format of the resulting list. Current default is xml.
style string (optional)
  • css
    Returns a URI to a CSS file that can be used for access the portal configured styles
  • xml
    Returns style information in response
This value is optional. By default no style inforamtion is returned.

Sample Request - for accessing search form information for a portal with key root

https://rucore.libraries.rutgers.edu/api/search/form/?key=root

Sample Request - for accessing search form information and CSS stylesheet URI for a portal with key root

https://rucore.libraries.rutgers.edu/api/search/form/?key=root&style=css
Sample output in XML format
In this example above the <root> element has five subelements:
  • <indexes>A listing of indexes/collections that are part of the portal
  • <search>Main search form configuration information
  • <browse>Browse list configuration and values.
  • <help>Help information configured for the portal.
  • <style>Optional CSS style information.
The <root> element has a series of ATTRIBUTES explained below:
  • @versionCurrent API method version.
  • @labelFriendly portal name/label.
  • @indexDisplayAn enumerated value; either hidden, expanded, or none. If hidden is supplied the list of indexes should be rendered, but minimized in the search form display. When set to expanded the rendered list should be fully displayed in the search form. When none is supplied no index list should appear in the search form.
  • @typeAn enumerated value; either classic or data. This describes the type of portal.
<indexes>
The <indexes> element has a series of ATTRIBUTES explained below:
  • @typeType of listing; either hierarchical, a series of nested indexes or subscription which is a flat series of indexes.
  • @numindexNumber of indexes the current portal is assigned to.
Each <index> subelement has a series of ATTRIBUTES explained below:
  • @idThe index/collection identifier.
  • @labelUser friendly label for the index/collection.
  • @numobjectNumber of resources/objects that are part of the index/collection. This value can also include any sub-collections, but is not a sum of all sub-collections and their resources.
<search>
The <search> element contains the information needed to render a search form; including input field information and labels. This main element contains one ATTRIBUTES explained below:
  • @tabLabelFriendly label to use for the search tab, if you are building a tab based display. If this value is empty then the search tab is not intended to be rendered.
Each <field> subelement has a series of ATTRIBUTES explained below:
  • @typeType of search field; either text, free text field, or select a select menu.
  • @valueForm field name to use when passing the submitted value to the query method.
  • @actionThe type of resulting action this field is designed to provide. Action values can be display, affects the displaying of the results. Result ordering is an example of a display action. Another action is query which provides query context to a search. Finally, the limitby action provide search filtering options.
  • @labelFor limitby actions an optional friendly label can be supplied for use next to the select menu.
  • @orderFor limitby actions this attribute defines the order multiple limitby fields should be displayed in.
  • @emptyValLabelFor select types this attribute defines the label that should be used for an empty value <option value=''>{emptyValLabel}</option> in the select menu.
Any <field> subelements that are type select will have additional subelements. These include:
  • <label>This is the friendly label to use in the <option>{label}</option> tag. An optional @default ATTRIBUTE that is passed with the value Y to indicate this should be the default selection in the menu.
  • <value>The value to use the in <option value='{value}'>{label}</option> tag.
<browse>
The <browse> element contains the information needed to render a browse list. This main element has a series of ATTRIBUTES explained below:
  • @tabLabelFriendly label to use for the browse tab, if you are building a tab based display. If this value is empty then the browse tab is not intended to be rendered.
  • @indexesAn enumerated value; either Y for yes or N for no. This indicates if a browse list should be created using the information supplied in the <indexes> element.
  • @subTabsAn enumerated value; either Y for yes or N for no. This indicates if the browse list has a series of groupings and a sub tab heading is needed in the display.
Each <group> subelement has a series of ATTRIBUTES explained below:
  • @labelFriendly label to use for grouping.
  • @quantityThe number of browse terms returned for the grouping.
  • @columnsThe number of columns for the grouping display of the terms.
Every <group> subelement has a series of <term> subelements. These subelements are ordered based on the configuration of the portal and should be displayed in the order they are delivered in the methods response. Each <term> subelement has a series of ATTRIBUTES explained below:
  • @labelThis is the friendly label to use when displaying the term.
  • @uriThe percent-encoded value to use with the query method. Note this value needs to be decoded using a uri decoder before creating a HTML <a> link.
<help>
The <help> element contains the information needed to render a helpful information to the user. This main element has one ATTRIBUTE explained below:
  • @tabLabelFriendly label to use for the help tab, if you are building a tab based display. If this value is empty then the help tab is not intended to be rendered.
The <topic> elements are ordered based a configuration selection and should be rendered in the order they are delivered in the response. Each <topic> subelement has a two subelements; <label> and <note>.
  • <label>Friendly label/heading to use for the help topic.
  • <note>The help topics information.
<style>
The <style> element could contain a URI reference to an external stylesheet or a series of subelements; this is dependent on the <style> parameter supplied in the request to the form method.

Record

Top

Provides resource information based on a portal configuration.

HTTP Method

GET

URI

https://rucore.libraries.rutgers.edu/api/search/record/

Request URL Pattern

https://rucore.libraries.rutgers.edu/api/search/record/{parameters}

Parameters

Parameter Value Description
key string (required) Portal key used to provide access to the API, system generated when portal is created.
id[] array (required) Resource identifier. Because this is an array you can provide multiple identifiers in a single request, instead of having to perform multiple requests.
output string (optional)
  • xml
    Resulting data is formatted in XML and returned with mime-type: application/xml
  • json
    Resulting data is formatted in JSON and returned with mime-type: application/json
  • php
    Resulting data is formatted in serialized PHP and returned with mime-type: application/x-httpd-php
This value is optional and controls the format of the resulting list. Current default is xml.

Sample Request - for accessing the resource rutgers-lib:26685 portal with key root

https://rucore.libraries.rutgers.edu/api/search/form/?key=root&id[]=rutgers-lib:26685
Sample output in XML format
The <root> element has a series of ATTRIBUTES explained below:
  • @versionCurrent API method version.
  • @labelFriendly portal name/label.
  • @statisticsAn enumerated value; either TRUE, display statisitcs, or FALSE, do not display. At this time the statistics feature uses a closed/non-public webservice.
  • @statisticsLabelLabel to use in the statistics display if the @statistics is set to TRUE. At this time the statistics feature uses a closed/non-public webservice.
In this example above the <root> element has a single <results> element with one or many <result> subelements. The number of <result> subelements is based on the number of resource identifiers that were supplied and successfully validated. Each <result> element has the following five subelements.
  • <metadata>The metadata to display based on the portal keys configuration.
  • <files>The files associated with the resource based on the portal keys configuration.
  • <system>General resource information always returned regardless of portal configuration.
  • <metatags>Metatag information for the resource.
  • <citations>Citation information in various formats for the resource.

Background

RUcore has been developing web services that allow software applications to easily interact with our repository framework of services. These web services are REST based and typically respond to requests in XML or JSON.

Web Services

Listserv and Google Group

A listserv has been established that will be used to communicate service outages and RUcore web service related news. The listserv address is rucore_web_services[at]email.rutgers.edu. Visit this page to subscribe.

A Google Group has been created to provide a place for discussion about the web services RUcore provides.

If you have any further questions please contact us.
Version 8.2.5
Rutgers University Libraries - Copyright ©2017