Ready to Learn?Ex Libris products all provide open APIs

 

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
institution The 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 
group Name of the user group. Relevant for restricted scopes.No 
onCampus On/off campus. Relevant for restricted scopes. 
possible value: false or true 
Not relevant for Deep Links
No 
query 

Note: 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

 
indx The 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
bulkSize The 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
dym Whether 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") 

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
more Applicable only for remote search. It simulates the "Get More" functionality. 

Possible values: true or false 
Default: false 
No
lang Hints 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
sortField 

Specifies 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.


Mapping Table
 

No
loc NOTE: when not configured, defaults to: local,scope:(<institution code>)
           where <institution code> is the value entered for the parameter, institution

Supports 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 Sciences

A 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 
pyrCategories Allows 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
pyrDegree Allows 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
pcAvailability

Emulates 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
segments Root element of the XML tree. no value 
jagroot Element to contain one or several sub-elements. 
Structure: Sub-element of segments. 
no value 
result Element to contain one or several sub-elements. 
Structure: Sub-element of jagroot. 
no value 
querytransformations Element to contain one or several sub-elements. 
Structure: Sub-element of result. 
no value 
querytransformation Element to contain one or several sub-elements. 
Structure: Sub-element of querytransformations. 
no value 
action did_u_mean. 
Structure: Sub-element of querytransformation. 
any value 
query Alternative spelling of the search term. 
Structure: Sub-element of querytransformation. 
any value 
facetlist Element to contain one or several sub-elements. 
Structure: Sub-element of result. 
no value 
accurate_counters Defines if the facets counters are accurate or approximate. 
Structure: Sub-element of facetlist. 
"true" or "false" 
Default: true 
facet Element to contain one or several sub-elements. 
Structure: Sub-element of facetlist. 
no value 
name Name of the facet. 
Structure: Sub-element of facet. 
any value 
count Number of facet values within one facet. 
Structure: Sub-element of facet. 
any number 
facet_values Element to contain one or several sub-elements. 
Structure: Sub-element of facet. 
no value 
key Name of the facet value. 
Structure: Sub-element of facet_values. 
any value 
value Number of records within one facet value. 
Structure: Sub-element of facet_values. 
any value 
docset Element to contain one or several sub-elements. 
Structure: Sub-element of result. 
no value 
firsthit Index of the first record to be returned by the search. 
Structure: Sub-element of docset. 
any value 
lasthit Index of the last record to be returned by the search. 
Structure: Sub-element of docset. 
any value 
hit_time Time used by the search engine to find results. 
Structure: Sub-element of docset. 
any number 
total_time Time used by the search engine to retrieveresults. 
Structure: Sub-element of docset. 
any number 
totalhits Number of results found by search. 
Structure: Sub-element of docset. 
any number 
doc Element to contain one or several sub-elements. 
Structure: Sub-element ofdocset. 
no value 
no Serial; number of the recordinthebulk. 
Structure: Sub-element of doc. 
any value 
rank The score of the query for the document. 
Structure: Sub-element of doc. 
any decimalnumber 
id IndexID of the recordin thesearchengine. 
Structure: Sub-element of doc. 
any number 
local Indicateswhethersearch was donelocally or remotely. 
Structure: Sub-element of doc. 
"true" or "false" 
Default: true 
GETIT Element to contain one or several sub-elements. 
Structure: Sub-element of doc. 
novalue 
GetIt1 Primary GetItlink. 
Structure: Sub-element of GETIT. 
any value 
GetIt2 Secondary GetIt link. 
Structure: Sub-element of GETIT. 
any value 
pnx:PrimoNMBib Element to contain one or several sub-elements. 
Structure: Sub-element of doc. 
no value 
record Details about how the internal structure of a PNX can be found in the Primo Technical Guide 

 

InputExample

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>