Ready to Learn?Ex Libris products all provide open APIs

General Purpose

A web service that performs a "brief search".
The returned XML is identical to that which is returned from the XService "brief search" request.

 

WSDL

The WSDL file is located under the following URL:
<your address>:<fe_port>/PrimoWebServices/services/searcher?wsdl

Request Example

The request expects 1 parmeter only, which is searchRequestStr.
This parameter is of type string.
The web service is expecting this parameter to hold an XML "Primo Search Request".

View the "Primo Search Request" XSD here.
SOAP envelope request and the place holder for your "Primo search request":

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.ws.primo.exlibris.com">
    <soapenv:Header/>
    <soapenv:Body>
        <api:searchBrief soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
            <searchRequestStr xsi:type="soapenc:string" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
                Your Primo Search Request HERE
            </searchRequestStr>
        </api:searchBrief>
    </soapenv:Body>
</soapenv:Envelope>


Primo Search Request example:


<searchRequest xmlns="http://www.exlibris.com/primo/xsd/wsRequest"  xmlns:uic="http://www.exlibris.com/primo/xsd/primoview/uicomponents">

    <PrimoSearchRequest xmlns="http://www.exlibris.com/primo/xsd/search/request">
        <QueryTerms>
            <BoolOpeator>AND</BoolOpeator>
            <QueryTerm>
                <IndexField>any</IndexField>       
                <PrecisionOperator>contains</PrecisionOperator>
                <Value>book</Value>
            </QueryTerm>
        </QueryTerms>
        <StartIndex>1</StartIndex>
        <BulkSize>10</BulkSize>
        <DidUMeanEnabled>true</DidUMeanEnabled>
        <HighlightingEnabled>true</HighlightingEnabled>
        <Languages><Language>eng</Language></Languages>
        <SortByList>
            <SortField>stitle</SortField>
        </SortByList>
        <DisplayFields>title</DisplayFields>
        <Locations>
            <uic:Location type="local" value=""/>
        </Locations>
        <InstBoost>true</InstBoost>
    </PrimoSearchRequest>
    <ip>127.0.0.1</ip>
    <group>GUEST</group>
    <onCampus>false</onCampus>
    <isLoggedIn>true</isLoggedIn>
    <institution>%s</institution>
</searchRequest>

 


Combined final request example:


<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.ws.primo.exlibris.com">
    <soapenv:Header/>
    <soapenv:Body>
        <api:searchBrief soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
            <searchRequestStr xsi:type="soapenc:string" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">

                    <searchRequest xmlns="http://www.exlibris.com/primo/xsd/wsRequest"  xmlns:uic="http://www.exlibris.com/primo/xsd/primoview/uicomponents">

                         <PrimoSearchRequest xmlns="http://www.exlibris.com/primo/xsd/search/request">
                               <QueryTerms>
                               ...
                        </PrimoSearchRequest>
                 </searchRequest>
            </searchRequestStr>
        </api:searchBrief>
    </soapenv:Body>
</soapenv:Envelope>

 


Combined final request (encoded) example

The searchRequestStr is of type string.

This means you need to make sure the searchRequest you are placing in it,  is encoded as a string.

You can do this by using the CDATA tag.

When using a SOAP client (such as soapUI which is a desktop client) you will need to encode the searchRequest so the combined request might look like:


<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.ws.primo.exlibris.com">
    <soapenv:Header/>
    <soapenv:Body>
        <api:searchBrief soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
            <searchRequestStr xsi:type="soapenc:string" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">

                    <![CDATA[

                 <searchRequest xmlns="http://www.exlibris.com/primo/xsd/wsRequest"  xmlns:uic="http://www.exlibris.com/primo/xsd/primoview/uicomponents">

                         <PrimoSearchRequest xmlns="http://www.exlibris.com/primo/xsd/search/request">
                               <QueryTerms>
                               ...
                        </PrimoSearchRequest>
                 </searchRequest>

                  ]]>
            </searchRequestStr>
        </api:searchBrief>
    </soapenv:Body>
</soapenv:Envelope>

Input Parameters

The following are the parameters in the "Primo Search Request":

The request is mainly combined from two "parts":

  1. searchRequest
  2. PrimoSearchRequest (resides under the searchRequest)
The structure of the searchRequest (XSD):

<xs:complexType name="SearchRequest">
           <xs:sequence>
               <xs:element ref="psr:PrimoSearchRequest"/>
               <xs:element name="ip"  type="xs:string"  maxOccurs="1"/>
               <xs:element name="institution"  type="xs:string"  maxOccurs="1"/>
               <xs:element name="group"  type="xs:string"  maxOccurs="1"/>
               <xs:element name="onCampus"  type="xs:boolean" maxOccurs="1"/>
               <xs:element name="isLoggedIn" type="xs:boolean" maxOccurs="1" minOccurs="0"/>
               <xs:element name="pdsHandle"  type="xs:string" maxOccurs="1" minOccurs="0"/>
           </xs:sequence>

</xs:complexType>

 


The structure of the PrimoSearchRequest (XSD):


<xs:element name="PrimoSearchRequest">
    <xs:complexType>
        <xs:sequence>
            <xs:element ref="RequestParams" minOccurs="0" maxOccurs="1"/>
            <xs:element ref="QueryTerms" />
            <xs:element name="StartIndex" type="xs:int"    default="0">
            <xs:element name="BulkSize" type="xs:int" default="10">
            <xs:element name="DidUMeanEnabled" type="xs:boolean" default="false">
            <xs:element name="HighlightingEnabled" type="xs:boolean" default="false" minOccurs="0" maxOccurs="1">    
            <xs:element name="GetMore" type="xs:int" default="0" minOccurs="0" maxOccurs="1">
            <xs:element ref="Languages" minOccurs="0" maxOccurs="1">
            <xs:element ref="SortByList" minOccurs="0" maxOccurs="1">
            <xs:element name="DisplayFields" type="xs:string" maxOccurs="unbounded" minOccurs="0">
            <xs:element ref="Locations" minOccurs="0" maxOccurs="1">
            <xs:element name="InstBoost" type="xs:boolean" maxOccurs="1" minOccurs="0">
            <xs:element ref="PersonalizedRankingParams" minOccurs="0" maxOccurs="1"/>
        </xs:sequence>
    </xs:complexType>
</xs:element>

 


Below is the description of each parameter, starting from the searchRequest simple parameters and then the PrimoSearchRequest parameters.

Some parameters are identical to those in the XService brief search. Those which are the same will just point there.

 

ElementDescriptionValue/ExampleDefaultSub elemnt of
ipClient IP
See XService brief search
string searchRequest
institutionInstitution code
See XService brief search
string searchRequest
groupName of user group
See XService brief search
string searchRequest
onCampusOn\Off campus
See XService brief search
"false" or "true"falsesearchRequest
PrimoSearchRequest   searchRequest
RequestParamsIncludes additional parameters with the request.<RequestParams>
   <RequestParam key="<parameter_name>">
        <value>
    </RequestParam>
     .
     .
     .
</RequestParams>
 PrimoSearchRequest
Availability indicationPasses this parameter to the Primo Central adaptor to request only full-text materials.

There are two ways of doing this:

1) Using the RequestParam tag - The same as the "Expand My Results" checkbox in the UI

2) Using a facet - The same as clicking the "Full Text Online" facet in the UI. 
Option #1:
<RequestParam key="pc_availability_ind">
     true
</RequestParam>

Option #2:
<BoolOpeator>AND</BoolOpeator>
<QueryTerm>
          <IndexField>facet_tlevel</IndexField>
          <PrecisionOperator>exact</PrecisionOperator>
          <Value>online_resources</Value>
</QueryTerm>
 RequestParams
peer_reviewPasses this parameter to the Primo Central adaptor to request only peer-reviewed materials.
This is just a facet to be added to the query.

 
<BoolOpeator>AND</BoolOpeator>
<QueryTerm>
          <IndexField>facet_tlevel</IndexField>
          <PrecisionOperator>exact</PrecisionOperator>
          <Value>peer_reviewed</Value>
</QueryTerm>
 PrimoSearchRequest
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
<RequestParam key="pyrCategories">
     chemistry;business
</RequestParam>
 RequestParams
pyrDegreeAllows you to personalize your results by degree.

Possible values: graduate, librarystaff, researcher, undergraduate
<RequestParam key="pyrDegree">
     undergraduate
</RequestParam>
 RequestParams
QueryTermsElement to contain one or several queries<QueryTerms>
      <BoolOpeator>AND</BoolOpeator>
      <QueryTerm>
           <IndexField>any</IndexField>                  <PrecisionOperator>
              contains
           </PrecisionOperator>
           <Value>book</Value>
       </QueryTerm>
       <QueryTerm>
            <IndexField>
                facet_creator
            </IndexField>
            <PrecisionOperator>
              contains
           </PrecisionOperator>
           <Value>william s burroughs</Value>
       </QueryTerm>
</QueryTerms>

You can add multiple <QueryTerm> elements.

<BoolOpeator>
possible values:
1) AND
2) OR

<QueryTerm> -
  See XService brief search (query parameter)
 
 PrimoSearchRequest
QueryTerms - Multiple facetsElement to contain one or several queries.
Use the:
 req:includeValue and req:excludeValue in order to create include/exclude multiple facet queries.

See XService brief search (query_inc/query_exc parameters)
<req:QueryTerm>
    <req:IndexField>
         facet_topic
    </req:IndexField>
    <req:PrecisionOperator>
        exact
    </req:PrecisionOperator>
    <req:Value/>
    <req:includeValue>
       Woodwork
    </req:includeValue>
    <req:includeValue>
       United States
    </req:includeValue>
    <req:excludeValue>
        Feature films
     </req:excludeValue>
    <req:excludeValue>
        Coffee
     </req:excludeValue>
  </req:QueryTerm>
 PrimoSearchRequest
StartIndexStart index of retrieved result list
  See XService brief search (indx parameter)
"1" to "n" PrimoSearchRequest
BulkSizeBulk size
See XService brief search
"10" or "20" or "30" or any value10PrimoSearchRequest
DidUMeanEnabledSee XService brief search (dym parameter)"true" or "false"FALSEPrimoSearchRequest
HighlightingEnabledSee XService brief search (highlight parameter)"true" or "false"
Must include the <DisplayFields> as well when setting HighlightingEnabled = true
FALSEPrimoSearchRequest
GetMoreApplicable only for remote search. It simulates the "Get More" functionality."true" or "false"FALSEPrimoSearchRequest
LanguagesElement to contain one or more <Language> elements.
 
<Languages>
    <Language>eng</Language>
    <Language>fre</Language>
</Languages>

Hints input languages to search engine for language recognition
(Code for the representation of name of language conform to ISO 639-2 Code ("T" (terminology))
 PrimoSearchRequest
SortByListElement to contain one <SortField>
See XService brief search (sortField parameter)
<SortByList>
      <SortField>stitle</SortField>
</SortByList>

Although XSD permits more than one field, only one field is supported.
 PrimoSearchRequest
DisplayFieldsSee XService brief search (highlight parameter)Supports multiple values:

<DisplayFields>title</DisplayFields>
<DisplayFields>creator</DisplayFields>
 PrimoSearchRequest
LocationsSee XService brief search (loc parameter)Blended search: local + Primo Central: 
 <Locations>
    <uic:Location type="local" value="scope:(VOLCANO)"/>
      <uic:Location type="adaptor" value="primo_central_multiple_fe"/>
  </Locations>

All 3 location options:

<uic:Location type="local" value="scope:(scope_name)"/>
<uic:Location type="remote" value="quickset_name"/>
<uic:Location type="adaptor" value="primo_central_multiple_fe"/>


NOTE: when not configured, defaults to: <uic:Location type="local" value="scope:(<institution code>)"/>
           where <institution code> is the value entered for the parameter, institution
 PrimoSearchRequest

 

Notes

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.

Output

This Web service returns a search response in XML format.

The following table describes the parameters in the XML output response:

ElementDescriptionValueDefaultStructure
segmentsRoot element of the XML treeno value root element
jagrootElement to contain one or several subelements (see structure)no value subelement of segments
resultElement to contain one or several subelements (see structure)no value subelement of jagroot
querytransformationsElement to contain one or several subelements (see structure)no value subelement of result
querytransformationElement to contain one or several subelements (see structure)no value subelement of querytransformations
actiondid_u_meananyvalue subelement of querytransformation
queryAlternative spelling of the search termany value subelement of querytransformation
facetlistElement that contains one or several subelements (see structure)
The facets enable to filter the records in the results by the different categories:
Creator, Subjects (lcc), language, topic, type(book/journal…) ,libraries(domain) and creation date
no value subelement of result
accurate_countersDefines if the facets counters are accurate or approximate"true" or "false"TRUEsubelement of facetlist
facetElement to contain one or several subelements (see structure)no value subelement of facetlist
namename of the facetany value subelement of facet
countnumber of facet values within one facetany number subelement of facet
facet_valuesElement to contain one or several subelements (see structure)no value subelement of facet
keyname of the facet valueany value subelement of facet_values
valuenumber of records within one facet valueany value subelement of facet_values
docsetElement to contain one or several subelements (see structure)no value subelement of result
firsthitIndex of the first record to be returned by the searchany value subelement of docset
lasthitIndex of the last record to be returned by the searchany value subelement of docset
hit_timeTime used by the search engine to find resultsany number subelement of docset
total_timeTime used by the search engine to retrieve resultsany number subelement of docset
totalhitsNumber of results found by searchany number subelement of docset
docElement to contain one or several subelements (see structure)no value subelement of docset
noSerial; number of the record in the bulkany value subelement of doc
rankThe score of the query for the documentany decimal number subelement of doc
idIndex id of the record in the search engineany number subelement of doc
localDefines if search was done locally or remotly"true" or "false"truesubelement of doc
GETITElement to contain one or several subelements (see structure)no value subelement of doc
GetIt1Primary GetIt linkany value subelement of GETIT
GetIt2Secondary GetIt linkany value subelement of GETIT
pnx:PrimoNMBibElement to contain one or several subelements (see structure)no value subelement of doc
recordDetails about how the internal structure of a PNX can be found in the technical guide