Brief Search

General Purpose

The search/brief request performs a search request.

Input Parameters Description

The first four parameters in the list below are only relevant for restricted scopes. A restricted scope is authorized according to the following parameters: institutiongroup, and onCampus. Because the institution parameter defines which PC key is sent to Primo Central, it is most important when searching in Primo Central.

Input Parameters

ParameterDescriptionMandatory
institutionThe institution code. Relevant for restricted scopes or for when searching against Primo Central.Yes
ipThe client IP.
Will help to identify the institution in cases the institution was not identified (according to the IP range associated with the institution)
Not relevant for Deep Links
Yes
groupName of the user group. Relevant for restricted scopes.No
onCampusOn/off campus. Relevant for restricted scopes.
possible value: false or true
Not relevant for Deep Links
No
queryNote: Special usage of specific fields is described after parameters explanation (footnotes) (facet_creationdate, peer_review, fulltext)

The query parameter is a combination of three parameters that are separated by a comma:
&query=<field>,<precision>,<value>

1) field – The field to search against
2) precision – A precision operator (i.e exact/contains/begins_with)
3) value – Any value
Examples:

&query=facet_topic,exact,Nonfiction
&query=any,contains,queens+of+the+stone+age (the value contains more than one term in it)

Note: The query parameter can be used more than once in the URL thus causing for an AND correlation between the two values:

For example:
&query=creator,contains,comm&query=facet_creator,exact,United+States

1) <field> possible values:
The field names to be used are field names used by the search engine. As such their names are a bit different than what you would expect. The below will list the relevant field names:
a) any –
Will search against most of the fields at once.
Example: &query=any,contains,queens
b) regular fields –
(taken from the code table: “Basic Index Fields”):
desc, title, creator, sub (subject), rtype (resource type), isbn, issn,
rectype (record type), dlink (down link), ftext (full text), general, toc, fmt,
lang, cdate (creation date), sid (source ID), rid (record ID),
addsrcrid (additional source ID), addtitle, pnxtype, alttitle,
abstract, and fiction
Example: &query=rid,exact,PRIMO1234
b) facet fields –
(taken from the code table: “Facets Code Fields”):
facet_creator, facet_lang, facet_rtype, facet_pfilter, facet_topic,
facet_creationdate, facet_dcc, facet_lcc, facet_rvk,
facet_tlevel,facet_domain, facet_fsize, facet_fmt, facet_frbrgroupid,
facet_frbrtype, facet_local1 – facet_local50
Example: &query=facet_creator,exact,william+s+burroughs

2) <precision>possible values:

NOTE: for facets, the only possible precision value is exact (i.e. &query=facet_topic,exact,Nonfiction)

a) exact – When searching for a phrase (more than one term,
i.e “queens of the stone age”) and we want an exact match
for this phrase.
                 Note: When querying for one term there is no difference
between exact and contains
Example: &query=title,exact,queens+of+the+stone+age
b) contains -When searching for one term, will return results for any field
containing this term. When searching for a phrase, will return
results for any field containing at least one of the given terms.
For example:
                      &query=title,contains,queens+of+the+stone+age

will return titles like:
“the age of life”, “kings and queens” or
age and health of queens

c) begins_with – Works only against the sort title field (swstitle)!
The swstitle was not mentioned above. The swstitle is the
title under the sort section in the PNX.
Note: 1) When using this precision, there is no meaning to
                                            the field you are using, as it will always search
                                            against the swstitle field!
2) Usually you will want to use sortField=stitle, when searching with begins_with (and not the default relevance)

3) <value> possible values:
Any value is allowed.
Values including commas in them should replace the comma with a space. For example, if you want to use “A,B,C” as the value, specify the following query:

&query=any,contains,A B C

The value can also hold multiple values with an OR, AND, or NOT operator:

&query=title,contains,Queen OR Stone

This will result in a query similar to the following:  title contains Queen OR title contains Stone

Note: The AND, OR, and NOT operators cannot be used between query parameters.

Yes
query_inc (Multiple facets – Query include)Note: Sepcial usage of specific fields is described after parameters explanation (footnotes) (facet_creationdate, peer_review, fulltext)

Supported from version V4.0 only.
Query a facet including multiple values:

&query_inc=<field>,<precision>,<value1, value2,…>

Example: &query_inc=facet_topic,exact,women,science

field  any facet fields –
(taken from the code table: “Facets Code Fields”):
facet_creator, facet_lang, facet_rtype, facet_pfilter, facet_topic,
facet_creationdate, facet_dcc, facet_lcc, facet_rvk,
facet_tlevel,facet_domain, facet_fsize, facet_fmt, facet_frbrgroupid,
facet_frbrtype, facet_local1 – facet_local50

precision – The precision operator MUST only hold the “exact” value (other values are not supported).

value1, value2.. – any value or multiple values separated by a comma. (Values including commas in them should replace the comma with a space)

The query created will generate an OR query between the values:
i.e. (facet_topic=value1 OR facet_topic=value2 OR …)

You can use the query_inc multiple times in the query:
i.e. &query_inc=facet_topic,exact,women,science&query_inc=facet_lang,exact,eng,heb

No
query_exc
(Multiple facets – Query exclude)
Note: sepcial usage of specific fields is described after parameters explanation (footnotes) (facet_creationdate, peer_review, fulltext)

Supported from version V4.0 only.
Query a facet excluding multiple values:

&query_exc=<field>,<precision>,<value1, value2,…>

Example: &query_exc=facet_topic,exact,women,science

field  any facet fields –
(taken from the code table: “Facets Code Fields”):
facet_creator, facet_lang, facet_rtype, facet_pfilter, facet_topic,
facet_creationdate, facet_dcc, facet_lcc, facet_rvk,
facet_tlevel,facet_domain, facet_fsize, facet_fmt, facet_frbrgroupid,
facet_frbrtype, facet_local1 – facet_local50

precision – The precision operator MUST only hold the “exact” value (other values are not supported).

value1, value2.. – any value or multiple values separated by a comma. (Values including commas in them should replace the comma with a space)

The query created will generate an AND query between the values:
i.e. (facet_topic=value1 AND facet_topic=value2 AND …)

You can use the query_exc multiple times in the query:
i.e. &query_exc=facet_topic,exact,women,science&query_exc=facet_lang,exact,eng,heb

indxThe position number of the record to begin from when retrieving the results
(For example, in order to display page #2, we want to set indx=11, meaning start retrieving records from position 11 in the result set)
Yes
bulkSizeThe amount of records to retrieve from the position set for indx
(In order to display page #2 when we display 10 records in a page:
indx=11
bulkSize=10)
Yes
dymWhether to include in the response a “Did you mean” suggestion.
The response will include (if at all) only 1 suggestion!Possible values: true or false
Default: false
No
highlight + displayFieldYou can define to “highlight” the search term you have requested in the retrieved results.
(Below, highlighting the title when searching for the term: “book”)

highlight
Indication whether highlights by server is required.
Possible values: true or false
Default: false

If highlight=true, you must supply one or more  displayField parameters to indicate which fields to highlight.

displayField
defines in which field from the Display section of the PNX to highlight, if it contains the search term.
Possible values: PNX field names from the Display section.
You can define more than 1 displayField:
&highlight=true&displayField=title&displayField=creator

Note: the highlighting is done by wrapping the relevant section in the PNX with a <span> tag,
i.e. <span class=”searchword”>BOOK</span>

No
moreApplicable only for remote search. It simulates the “Get More” functionality.

Possible values: true or false
Default: false

No
langHints input languages to search engine for language recognition.

“eng” or “fre” or “ger” (Code for the representation of name of language conform to ISO-639)

No
sortFieldSpecifies the type of sort to perform. If this parameter is not specified or left empty, the system uses the relevance sort. Other than the relevance sort, Primo supports the following types of sorts:

  • stitle – performs Title sort.
  • scdate – performs a date sort in descending order.
  • scdate2 – performs a date sort in ascending order.
  • screator – performs an author sort.
  • popularity – performs a popularity sort.

The valid values for this parameter are defined with the Index Field column in the Sort Fields Config mapping table, as shown below. The direction of the sort is defined with the Direction column.

 

No
locNOTE: when not configured, defaults to: local,scope:(<institution code>)
where <institution code> is the value entered for the parameter, institutionSupports 3 different search targets:1) Local
2) Deep Search
3) Remote (Metalib) – If the results from a remote site are not in the MetaLib data format, Primo displays a link to the results in the Additional Results section, which appears first in the results.In order to add a target to search on, add the following template to the URL:
loc=<target>,<location reference><target> possible values:1) local – For a local search
2) adaptor – For a deep search
3) remote – For a remote search against Metalib<location reference> possible values:1) for local – define the scope to search on
Example: loc=local,scope:(VOLCANO)
2) for adaptor – need to define the name of the requested adaptor
Example: loc=adaptor,primo_central_multiple_fe
3) for remote – need to define a quick set name
Example: loc=remote,Business and SciencesA single request will let you define as many search targets as you want, meaning, all 3 can be done in a single request.Example for single search target:

http ://il-primo03:1702/PrimoWebServices/xservice/search/brief?institution=PRIMO&query=any,contains,book&indx=20&bulkSize=10&loc=local,scope:(VOLCANO)
Example for multi search (two)  targets:

http ://il-primo03:1702/PrimoWebServices/xservice/search/brief?institution=PRIMO&query=any,contains,book&indx=20&bulkSize=10&loc=local,scope:(VOLCANO)&loc=adaptor,primo_central_multiple_fe

Example for multi search (three)  targets:

http ://il-primo03:1702/PrimoWebServices/xservice/search/brief?institution=PRIMO&query=any,contains,book&indx=20&bulkSize=10&loc=local,scope:(VOLCANO)&loc=adaptor,primo_central_multiple_fe&loc=remote,Business and Sciences

Multiple scopes
You can search multiple scopes in 2 ways:
1) loc=local,scope:(VOLCANO,NORTH)
2) Use multiple loc parameters:
&loc=local,scope:(VOLCANO)&loc=local,scope:(NORTH)
There is a limitation to the order and which scopes can be used in such queries.
The limitation is according to the “Search Scopes” you have defined for each view.
To be sure what your “Search scopes” are, you can view the following file on your FE machine:
$primo_dev/ng/jaguar/home/system/conf/search_schema.xml

under the <filters> tag you will find all your configured search scopes:
<filters>
<filter>facet_frbrtype:(7 OR 6)</filter>
<filter>NOT scope:(“PRIMO”)</filter>
<filter>scope:(NORTH)  OR scope:(demo_digitool) OR scope:(“CENTRAL”)</filter>
<filter>scope:(BBR)</filter>
You are allowed to use only those scopes listed in the file and only use the order as in the file.
Mixing the order will not work, so &loc=local,scope:(NORTH, demo_digitool, “CENTRAL”) will work but &loc=local,scope:( demo_digitool, NORTH,”CENTRAL”) will not!
Searching against Primo Central
Searching against Primo Central is done via an adaptor.
Therefor as mentioned above, you will need to add the following:
loc=adaptor,primo_central_multiple_fe

No
pyrCategoriesAllows you to personalize your results by disciplines.

Possible values: agriculture_forestry, anthropology, arts_humanities, biology, business,
chemistry, computer_science, earth_sciences, economics, education, engineering,
geography, languages_literature, law, library_information_science, mathematics, medicine,
nursing, pharmacy_therapeutics_ pharmacology, philosophy_religion, physics,
political_sciences, psychology, public_health, sciences, social_sciences, sociology,
veterinary_medicine
Example: &pyrCategories=chemistry;business

No
pyrDegreeAllows you to personalize your results by degree.

Possible values: graduate, librarystaff, researcher, undergraduate
Example: &pyrDegree=undergraduate

No
Date Ranges
dr_s
dr_e
In order to search by date ranges, emulating the date widget in the advanced search

 

&query=dr_s,exact,YYYYMMDD&query=dr_e,exact,YYYYMMDD

 

i.e. &query=dr_s,exact,19840201&query=dr_e,exact,99991231

No
pcAvailabilityEmulates the “Expand My Results” checkbox in the Primo UI.
possible values are: true/false.false – not expanded, only results with full text are returned.
true – expanded, all results even without full text are returned.By default pcAvailability=false.Available from Primo V4.8 and later.
No
jsonPossible values: true/false (default is false). If set as true, the result will return as a JSON result instead of an XML.No

Notes

Retrieving only full text results:

query=facet_tlevel,exact,online_resources_PC_TN.

From Primo V4.4 this also works in a blended search (up to then it worked only against a Primo Central search).

Retrieving only peer reviewed results from Primo Central:

query=facet_tlevel,exact,peer_reviewed

Working with facet_creationdate

Example: query=facet_creationdate,exact,[2005+TO+2013]

To query for an exact year, use the same value twice,

query=facet_creationdate,exact,[2013+TO+2013]

this will select records with creation date of 2013

Limitation on number of results

When querying Primo Central via API, you are limited to requesting records within the first 2,000 results. That is, if you are retrieving records in order to display 10 records per page, you can only display the first 200 pages.
Any request that you send to retrieve records beyond the first 2,000 records will result in an empty result set.

Record IDs retrieved from Primo Central

Record IDs returning from Primo Central will hold a leading “TN_” infront of them.

For example: TN_jstor1234.

In order to query against such record IDs, you must remove the leading TN_, so in our case: rid,exact,jstor1234

 

Output Parameters

ElementDescriptionValue
segmentsRoot element of the XML tree.no value
jagrootElement to contain one or several sub-elements.
Structure: Sub-element of segments.
no value
resultElement to contain one or several sub-elements.
Structure: Sub-element of jagroot.
no value
querytransformationsElement to contain one or several sub-elements.
Structure: Sub-element of result.
no value
querytransformationElement to contain one or several sub-elements.
Structure: Sub-element of querytransformations.
no value
actiondid_u_mean.
Structure: Sub-element of querytransformation.
any value
queryAlternative spelling of the search term.
Structure: Sub-element of querytransformation.
any value
facetlistElement to contain one or several sub-elements.
Structure: Sub-element of result.
no value
accurate_countersDefines if the facets counters are accurate or approximate.
Structure: Sub-element of facetlist.
“true” or “false”
Default: true
facetElement to contain one or several sub-elements.
Structure: Sub-element of facetlist.
no value
nameName of the facet.
Structure: Sub-element of facet.
any value
countNumber of facet values within one facet.
Structure: Sub-element of facet.
any number
facet_valuesElement to contain one or several sub-elements.
Structure: Sub-element of facet.
no value
keyName of the facet value.
Structure: Sub-element of facet_values.
any value
valueNumber of records within one facet value.
Structure: Sub-element of facet_values.
any value
docsetElement to contain one or several sub-elements.
Structure: Sub-element of result.
no value
firsthitIndex of the first record to be returned by the search.
Structure: Sub-element of docset.
any value
lasthitIndex of the last record to be returned by the search.
Structure: Sub-element of docset.
any value
hit_timeTime used by the search engine to find results.
Structure: Sub-element of docset.
any number
total_timeTime used by the search engine to retrieveresults.
Structure: Sub-element of docset.
any number
totalhitsNumber of results found by search.
Structure: Sub-element of docset.
any number
docElement to contain one or several sub-elements.
Structure: Sub-element ofdocset.
no value
noSerial; number of the recordinthebulk.
Structure: Sub-element of doc.
any value
rankThe score of the query for the document.
Structure: Sub-element of doc.
any decimalnumber
idIndexID of the recordin thesearchengine.
Structure: Sub-element of doc.
any number
localIndicateswhethersearch was donelocally or remotely.
Structure: Sub-element of doc.
“true” or “false”
Default: true
GETITElement to contain one or several sub-elements.
Structure: Sub-element of doc.
novalue
GetIt1Primary GetItlink.
Structure: Sub-element of GETIT.
any value
GetIt2Secondary GetIt link.
Structure: Sub-element of GETIT.
any value
pnx:PrimoNMBibElement to contain one or several sub-elements.
Structure: Sub-element of doc.
no value
recordDetails about how the internal structure of a PNX can be found in the Primo Technical Guide.

Input Example

http://primo.com:170X/PrimoWebServices/xservice/search/brief?institution=WESTERN&onCampus=false&query=any,exact,lok&indx=1&bulkSize=2&dym=true&highlight=true&lang=eng

Output Example

<sear:SEGMENTS xmlns="

http://www.exlibrisgroup.com/xsd/jaguar/search"
>
  <sear:JAGROOT>

    <sear:RESULT>

      <sear:DOCSET TOTALHITS="1">

        <sear:DOC LOCAL="true" xmlns="http://www.exlibrisgroup.com/xsd/primo/primo_nm_bib" xmlns:sear="http://www.exlibrisgroup.com/xsd/jaguar/search" >
          <PrimoNMBib>
            <record>
              <control>
                <sourcerecordid>81686</sourcerecordid>
                <sourceid>White_Shore_Voyager</sourceid>
                ...
              </control>
              <display>
                <type>book</type>
                <title>Harry Potter and the deathly hallows</title>
                <creator>J. K. Rowling</creator>
                ...
              </display>
              <links>
                <openurl>$$Topenurl_journal</openurl>
                <backlink>$$Tvoyager_backlink$$Ebacklink</backlink>
                ...
              </links>
              <search>
                <title>Harry Potter and the deathly hallows /</title>
                <subject>Potter, Harry (Fictitious character) Fiction.</subject>
                ...
              </search>
              <sort>
                <title>Harry Potter and the deathly hallows /</title>
                <creationdate>2007</creationdate>
                ...
              </sort>
              <facets>
                <language>eng</language>
                <creationdate>2007</creationdate>
                ...
              </facets>
              <dedup>
                <f7>harry potter and the deathly hallows</f7>
                <f8>nyu</f8>
               ...
              </dedup>
              <frbr>
                <t>1</t>
                <k1>$$Krowling j k$$AA</k1>
              </frbr>
              <delivery>
                <institution>WHITESHORE</institution>
                <delcategory>Online Resource</delcategory>
              </delivery>
              <ranking>
                <booster1>1</booster1>
                <booster2>1</booster2>
              </ranking>
              <addata>
                <aulast>Rowling</aulast>
                <aufirst>J. K.</aufirst>
                ...
              </addata>
            </record>
          </PrimoNMBib>
          <sear:GETIT GetIt2="http://1.1.1.1?ctx_ver=Z39.88-2004&ctx_enc=info:ofi/enc:UTF-8&ctx_tim=2011-06-10T17%3A28%3A55IST&url_ver=Z39.88-2004&url_ctx_fmt=infofi/fmt:kev:mtx:ctx&rfr_id=info:sid/primo.exlibrisgroup.com:primo3-Journal-White_Shore_Voyager&rft_val_fmt=info:ofi/fmt:kev:mtx:book&rft.genre=book&...../>
          <sear:GETIT GetIt2="" GetIt1="OVP" deliveryCategory="Physical Item"/>
          <sear:LIBRARIES>
            <sear:LIBRARY>
              <sear:library>MAIN</sear:library>
              ...
            </sear:LIBRARY>
          </sear:LIBRARIES>
          <sear:LINKS>
            <sear:openurl><![CDATA[></sear:openurl>
            ...
          </sear:LINKS>
        </sear:DOC>
      </sear:DOCSET>

    </sear:RESULT>

  </sear:JAGROOT>

</SEGMENTS>