Primo API Docs

Ex Libris Developer Network Primo Documentation Primo REST APIs Primo API Docs

Primo Search

Resource URL
API Description
URL Parameters
Query string Parameters
Body Parameters
Output
Possible Error Codes

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

Note: The Primo search API has a hardcoded offset limitation parameter of 5000.

TRY IT NOW

Resource URL

GET /primo/v1/search

API Description

WADL documentation: Download
Swagger (OpenAPI) documentation: Download

URL Parameters

None

Querystring Parameters

Parameter	Type	Required	Description
`vid`	xs:string	Required	The view ID. Example: vid=Auto1.
`tab`	xs:string	Required	The name of the tab. Example: tab=default_tab.
`scope`	xs:string	Required	The scope name. Example: scope=default_scope.
`q`	xs:string	Required	The 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 title field contains the words pop and music and the subject field contains the word korean: q=title,contains,pop music,AND;sub,contains,korean
`qInclude`	xs:string	Optional.	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). * For retrieving cited/citing references, you may use: "qInclude=[facet_citing/facet_citedby],exact,cdi_[citation key]". where the [citation key] is in the format: "FETCH-...." and is taken from the 'citedby'/'cites'/'citing' fields, in a response for search API query that includes results with citations.
`qExclude`	xs:string	Optional.	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).
`multiFacets`	xs:string	Optional.	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
`journals`	xs:string	Optional.	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
`databases`	xs:string	Optional.	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 - this is only supported in classic Primo and not in Primo VE). * 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
`lang`	xs:string	Optional. Default: eng	The Language. For Primo - use the locale format language. For example: lang=en_US. For Primo VE - use the two letters format language. For example: lang=en.
`fromDate`	xs:string	Optional.	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.
`offset`	xs:int	Optional. Default: 0	The 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. The recomended maximim offset is 2000.
`limit`	xs:int	Optional. Default: 10	The maximum number of results in the response Example: limit=5. The recomended maximim limit is 50.
`sort`	xs:string	Optional. Default: rank	The 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
`personalization`	xs:string	Optional.	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
`pcAvailability`	xs:boolean	Optional. Default: true	Indicates whether PC records that do not have full text are displayed in the results. The valid values are true (display all records even if they do not have full text) or false (display full text records only). The default value for Primo VE is false. Example: pcAvailability=false.
`getMore`	xs:string	Optional. Default: 0	Relevant 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.
`conVoc`	xs:boolean	Optional. Default: true	Indicates whether the controlled vocabulary service is enabled to add synonyms to queries. The valid values are true or false. Example: conVoc=true.
`inst`	xs:string	Required	The 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.
`skipDelivery`	xs:boolean	Optional. Default: true	Indicates whether to skip the delivery call (relevant only for Primo VE). When set to 'true', no delivery will be sent in the response, and the results should be displayed quicker. Example: skipDelivery=true.
`disableSplitFacets`	xs:boolean	Optional. Default: true	Indicates whether to retrieve facets or not (relevant only for Primo VE). When set to 'false' the facets won't be retrieved and the results should be displayed quicker. Example: disableSplitFacets=true.

Body Parameters