Primo API results - interpretation of results, refining your query
- Corinna Baksik
DRAFT PAGE
DRAFT
General information on the search API from Ex Libris
https://developers.exlibrisgroup.com/primo/apis/search/
Definitions of PNX elements you may encounter in each record
Visit Data elements (PNX record)Â to see how MARC data is mapped to different elements of the PNX record for the purpose of display, search, facet, etc.Â
Evaluating the content of the Delivery section
In each record, the delivery section will inform you how to treat each record. More info on CDI linking from Ex Libris.Â
Direct Link resources
If delivery: availabilityLinks contains directlink, then Primo has enough information to take the user directly to the provider page. The UI should present the link in "availabilityLinksUrl" element and it will take the user straight to the resource.Â
"delivery": {
"availabilityLinks": [
"directlink"
],
"physicalItemTextCodes": "",
"displayLocation": false,
"availabilityLinksUrl": [
"https://hvd-psb.alma.exlibrisgroup.com/view/uresolver/01HVD_INST/openurl?ctx_enc=info:ofi/enc:UTF-8&ctx_id=10_1&ctx_tim=2021-11-01T15%3A22%3A17IST&ctx_ver=Z39.88-2004&url_ctx_fmt=info:ofi/fmt:kev:mtx:ctx&url_ver=Z39.88-2004&rfr_id=info:sid/primo.exlibrisgroup.com-gale_proqu&rft_val_fmt=info:ofi/fmt:kev:mtx:journal&rft.genre=article&rft.atitle=Persistence%20of%20Zika%20Virus%20in%20Body%20Fluids%20%E2%80%94%20Final%20Report&rft.jtitle=The%20New%20England%20journal%20of%20medicine&rft.au=Paz-Bailey,%20Gabriela&rft.date=2018-09-27&rft.volume=379&rft.issue=13&rft.spage=1234&rft.epage=1243&rft.pages=1234-1243&rft.issn=0028-4793&rft.eissn=1533-4406&rft_id=info:doi/10.1056/NEJMoa1613108&rft.pub=Massachusetts%20Medical%20Society&rft.place=WALTHAM&rft.stitle=NEW%20ENGL%20J%20MED&rft_id=info:bibcode/&rft_id=info:hdl/&rft_id=info:lccn/&rft_id=info:oclcnum/&rft_id=info:pmid/28195756&rft_id=info:eric/&rft_dat=%3Cgale_proqu%3EA558335352%3C/gale_proqu%3E%3Curl%3E%3C/url%3E,language=eng,view=HVD2&svc_dat=single_service&rft_pqid=2112712593&rft_galeid=A558335352"
],
Harvard digitized holdings and similar content managed in MARC
If records from Alma that have MARC holdings with 856 links to full-text, the delivery category will contain "Online Resource," and you can use the link in GetIt1:link.Â
"delivery": {
"deliveryCategory": [
"Online Resource",
"Alma-P"
],
"availability": [
"not_restricted",
"available_in_my_institution"
],
"GetIt1": [
{
"links": [
{
"isLinktoOnline": true,
"displayText": "$$Elinktorsrc",
"hyperlinkText": "tab1_onl_norestrict",
"getItTabText": "tab1_onl_norestrict",
"link": "https://hdl.handle.net/2027/hvd.32044070824016",
"@id": "_:0"
}
Resources that don't have online access
If delivery: availabilityLinks contains detailsGetit1, there is no online availability. It's best to offer a link to the user that opens the full record in HOLLIS, where the user will be able to place a request for print, or ILL or Scan & Delivery.Â
.../primo-explore/fulldisplay?vid=HVD2&docid={pnx/control/recordid}
Physical holdings
Library codes
- When reading the "docs" in the search results, only library codes are used (e.g. BAK), not library names (Baker Business). You will have to translate the codes to names in your interface if you are displaying data to users. There is a separate API call that can be made to find the translations of codes to names: .../primo/v1/translations/HVD2?lang=en_US&apikey=
- You will need to search through the results of this call to find lines that begin with:Â 01HVD.library.
- Examples:Â
- "01HVD.library.BAK": "Baker Business",
- "01HVD.library.FAL": "Fine Arts Library",
- "01HVD.library.GUT": "Gutman Education",
- Note that a number of the entries in the translation response are for obsolete codes. The search API, though, will not return obsolete codes.Â
- Library names change very rarely. It is not necessary or advisable to call the translation response frequently. A weekly call would be sufficient, and translations can be stored locally until the next update. Daily calls are also acceptable.Â
"Best" location
In the Primo search results UI, Primo chooses a "best location" to display in a summary line, for example:Â
For the API equivalent, see the "bestLocation" section (code block below), where:Â
- "mainLocation": library code (needs to be translated to library name)
- "subLocation": location display name (i.e. location within library)
The flag "feDisplayOtherLocations" tells you whether there are additional libraries or not.Â
If there is only one 1 holding, it's always the "best." If there are multiple libraries, Primo chooses one based on availability.
"bestlocation": {
"matchForHoldings": [
{
"holdingRecord": "852##b",
"matchOn": "MainLocation"
},
{
"holdingRecord": "852##c",
"matchOn": "SecondaryLocation"
}
],
"mainLocation": "BAK",
"subLocationCode": "RRMED",
"callNumber": "(HD4901 .L139 1998 v.2 )",
"organization": "01HVD",
"libraryCode": "BAK",
"@id": "_:0",
"availabilityStatus": "available",
"subLocation": "Stacks -- Media Collection",
"holdId": "",
"isValidUser": true
},
"deliveryCategory": [
"Alma-P"
],
"serviceMode": [
"activate"
],
"feDisplayOtherLocations": false,
All holdings (library+locations)
If you want want to prefer one library over others, you can see all holdings and choose the one you want. For example, there are 3 locations, summarized in the search results as:
All 3 holdings are displayed in the Get It section of the UI:
To highlight a library other than the "best" location, read through the holding section to find the library of interest:Â
"holding": [
{
"matchForHoldings": [
{
"holdingRecord": "852##b",
"matchOn": "MainLocation"
},
{
"holdingRecord": "852##c",
"matchOn": "SecondaryLocation"
}
],
"subLocationCode": "HD",
"ilsApiId": "",
"libraryCode": "LAW",
"isValidUser": true,
"mainLocation": "LAW",
"callNumber": "(HB74.P8 L479 2006x )",
"adaptorid": "ALMA_01",
"organization": "01HVD",
"holdingURL": "OVP",
"@id": "_:0",
"availabilityStatus": "available",
"subLocation": "Offsite Storage",
"holdId": ""
},
{
"matchForHoldings": [
{
"holdingRecord": "852##b",
"matchOn": "MainLocation"
},
{
"holdingRecord": "852##c",
"matchOn": "SecondaryLocation"
}
],
"subLocationCode": "CORE",
"ilsApiId": "",
"libraryCode": "BAK",
"isValidUser": true,
"mainLocation": "BAK",
"callNumber": "(HB74.P8 L479 2006 )",
"adaptorid": "ALMA_01",
"organization": "01HVD",
"holdingURL": "OVP",
"@id": "_:1",
"availabilityStatus": "unavailable",
"subLocation": "Stamps Reading Room -- Core Collection",
"holdId": ""
},
{
"matchForHoldings": [
{
"holdingRecord": "852##b",
"matchOn": "MainLocation"
},
{
"holdingRecord": "852##c",
"matchOn": "SecondaryLocation"
}
],
"subLocationCode": "WIDLC",
"ilsApiId": "",
"libraryCode": "WID",
"isValidUser": true,
"mainLocation": "WID",
"callNumber": "(HB74.P8 L479 2006x )",
"adaptorid": "ALMA_01",
"organization": "01HVD",
"holdingURL": "OVP",
"@id": "_:2",
"availabilityStatus": "unavailable",
"subLocation": "WID-LC",
"holdId": ""
}
],
Refining your query
When performing queries in the UI, you can use browser developers tools to very how the query is sent to the API. This is because the Primo UI consumes the API. This will allow you to experiment which how searches in the UI can be sent to the API. In the example below, the Date Limit feature in the UI has been used. By using the developer tools, you can see how this was constructed when sent to the API.Â
Vendor documentation is available at https://developers.exlibrisgroup.com/primo/apis/.Â
To make your search results via API consistent with the UI, we recommend including these two parameters:
- newspapersActive = true
- newspaperSearch = false
The vendor doc does not mention how to facet by date. The screenshot above includes an example (qInclude=facet_searchcreationdate...)