Primo API Docs

__METHOD= GET . __PATH= /primo/v1/search .

Brief Search


This service implements Primo's main search service and returns a list of results based on the specified search query and also information about the total results number, the list of the facets for all exists results etc.).

Note: Hosted customers can use this API by specifying the API-key, but on-premises customers must specify an institution code and add a valid guest JWT to the header of the request.
To get a valid guest JWT, please use the Guest JWT Creator Rest API (see JWT Rest API).


Basic URL example for hosted customers:
<api-gateway-url>/primo/v1/search?vid=Auto1&tab=default_tab&scope=default_scope&q=any,contains,water&apikey=<apikey>


Basic URL example for on-premises customers:
<base-local-url>/primo_library/libweb/webservices/rest/primo-explore/v1/pnxs?vid=<view id>&tab=<tab>&scope=<scope>&q=any,contains,water&inst=<the instisution code>

The API key (which is required for hosted customers only) is used to access this API. For information on getting the API key, see Getting Started with Primo REST APIs

Resource URL

GET /primo/v1/search

API Description

URL Parameters

None

Querystring Parameters

ParameterTypeRequiredDescription
vidxs:stringRequiredThe view ID.
Example: vid=Auto1.
tabxs:stringRequiredThe name of the tab.
Example: tab=default_tab.
scopexs:stringRequiredThe scope name.
Example: scope=default_scope.
qxs:stringRequiredThe query string that you want to use to perform a search.
The query string uses the following format:
q=<field_1>,<precision_1>,<value_1>[[,<operator_1>];<field_n>,<precision_n>,<value_n>...]
* field - The data field that you want to search within. The following fields are valid: any (for any field), title, creator (for author), sub (for subject), and usertag (for tag).
* precision - The precision operation that you want to apply to the field. The following precision operators are valid: exact (value must match the data in the field exactly), begins with (the value must be found at the beginning of the field), and contains (the value must be found anywhere in the field).
* value - The search terms, which can be a word, phrase, or exact phrase (group of words enclosed by quotes), and can include the following logical operators: AND, OR, and NOT. For more information regarding search terms, see Performing Basic Searches.
* operator - When specifying multiple search fields for advanced searches, this parameter applies the following logical operations between fields: AND (specified values must be found in both fields), OR (specified values must be found in at least one of the fields), NOT (the specified value of the next field must not be found). If no operator is specified, the system defaults to AND.

Note: Multiple fields are delimited by a semicolon.
Limitation: The value must not include a semicolon character.

In the following example, the system searches for all records in which the word home is found anywhere within the record's title:
q=title,contains,home

In the following example, the system searches for all records in which the author field contains the word david and the title field contains the word wine:
q=creator,contains,david,AND;title,contains, wine
qIncludexs:stringOptional.Filters the results by the facets that you want to include. The logical AND operation is applied between the facets.
This filter uses the following format:
qInclude=<facet_category_1>,exact,<facet_name_1>[|,|<facet_category_n>,exact,<facet_name_n>...]

Note: Multiple categories are delimited by the following string of characters: |,|

* facet_category - The facet category that you want to include. The following categories are valid: facet_rtype (Resources Type), facet_topic (Subject), facet_creator (Author), facet_tlevel (Availability), facet_domain (Collection), facet_library (library name), facet_lang (language), facet_lcc (LCC classification).
* facet_name - The name of the facet to include (such as Journals if facet_rtype was selected).

In the following example, the system will search for all records in which the author field contains the word david and the title field contains the word wine:
q=creator,contains,david,AND;title,contains, wine
qExcludexs:stringOptional.Filters the results by the facets that you want to exclude. The logical AND operation is applied between the facets.
This parameter uses the following format:
qExclude=<facet_category_1>,exact,<facet_name_1>[|,|<facet_category_n>,exact,<facet_name_n>...]

Note: Multiple categories are delimited by the following string of characters: |,|

* facet_category - The facet category that you want to exclude. The following categories are valid: facet_rtype (Resources Type), facet_topic (Subject), facet_creator (Author), facet_tlevel (Availability), facet_domain (Collection), facet_library (library name), facet_lang (language), facet_lcc (LCC classification)
* facet_name - The name of the facet to exclude (such as Journals if facet_rtype was selected).
multiFacetsxs:stringOptional.Filter the results by including and excluding facets. The main difference between this parameter and the qInclude and qExclude parameters is that this parameter uses OR logic between facet values and AND logic between facet categories. This parameter uses the following format:multiFacets=<facet_category_1>,<facet_operator_1>,<facet_name_1>[|,|<facet_category_n>,<facet_operator_n>,<facet_name_n>...]

* facet_category - The facet category that you want to include or exclude. The following categories are valid: facet_rtype (Resources Type), facet_topic (Subject), facet_creator (Author), facet_tlevel (Availability), facet_domain (Collection), facet_library (library name), facet_lang (language), facet_lcc (LCC classification)
* facet_operator - The operator to apply to the facet. The valid values are include or exclude.
* facet_name - The name of the facet to exclude (such as Journals if facet_rtype was selected).

Note: Multiple categories are delimited by the following string of characters: |,|

Example: multiFacets=facet_rtype,include,books|,|facet_lang,exclude,spa
journalsxs:stringOptional.The query string used to search specifically for journals. (Relevant for Alma customers only). This parameter uses the following format:
journals=<operator>,<value>

* type - The type of search to perform. The valid values are any (search using free text or ISSN) or letter (search using the first letter of the journal).
* value - Depending on the search type, the search string can be free text, ISSN, or a letter.

The following example returns all journals that have the word nature in any of its data fields: journals=any,natureThe following example returns all journals that begin with the letter N: journals=letter,N
databasesxs:stringOptional.The query string used to search specifically for databases. (Relevant for Alma customers only). This parameter uses the following format:
databases=<operator>,<value>

* type - The type of search to perform. The valid values are any (search using free text or ISSN) or letter (search using the first letter of the journal).
* value - Depending on the search type, the search string can be free text, ISSN, or a letter.
The following example returns all databases that have the word law in any of its data fields: journals=any,law
The following example returns all databases that begin with the letter L: journals=letter,L
langxs:stringOptional. Default: engThe Language.
Example: lang=eng.
fromDatexs:stringOptional.This parameter gives results which updated in the library data base from certain date. .
The following date example represent 12.1.2018 15:21:28 Example: fromDate=20180128152128.
offsetxs:intOptional. Default: 0The offset of the results from which to start displaying the results.

The following example skips the first bulk and displays the remaining results up to the specified limit: offset=10.
limitxs:intOptional. Default: 10The maximum number of results in the response
Example: limit=5.
sortxs:stringOptional. Default: rankThe type of sort to perform on the results, which can be based on relevance or a specific field: rank, title, author, or date.
Example: sort=rank
personalizationxs:stringOptional.The disciplines to apply to your search query. (Relevant for Primo Central searches only).When applied, records marked with the specified disciplines are boosted in the results.
The valid disciplines are defined in the Personalize Your Results Disciplines mapping table in the Back Office. This parameter uses the following format:
personalization=<discipline_1>[;<discipline_2>...;<discipline_5]

Note: Multiple disciplines are delimited by a semicolon. A maximum of five disciplines are supported. You cannot specify a discipline and its sub-discipline, but you can specify either the discipline or up to five of its sub-disciplines.

Example: personalization=biology;chemistry;medicine
pcAvailabilityxs:booleanOptional. Default: trueIndicates whether PC records that do not have full text are displayed in the results. The valid values are true (display full text records only) or false (display all records even if they do not have full text)
Example: pcAvailability=false.
getMorexs:stringOptional. Default: 0Relevant for searches in Metalib.
Indicates whether to expand the number of results in Metalib searches. The valid values are 0 (false) or 1 (true).
Example: getMore=0.
conVocxs:booleanOptional. Default: trueIndicates whether the controlled vocabulary service is enabled to add synonyms to queries. The valid values are true or false.
Example: conVoc=true.
instxs:stringRequiredThe Institution code, which is required for on-premises (non-hosted) Primo customers only.

Note: On-premises customers must also add a valid guest JWT to the header of the request. To get a valid guest JWT, To get a valid guest JWT, please use the Guest JWT Creator Rest API..

Example: inst=VOLCANO.

Body Parameters

None

Output

Possible Error Codes

CodeMessage