DiscoverItem - Search overview
DiscoverItem - Search is a service that initiates a federated search on Z39.50 catalogs and retrieves deduped records. This service is designed to retrieve results in an asynchronous manner. The first time the service is called with a query parameter, a search is initiated on all the configured catalogs, and the service returns a response as soon as any record is available from the catalogs.
Note:
At this point, all records may not have been retrieved. Subsequent calls to the service with the same query may yield more records as they are retrieved by the underlying subsystem.
The response JSON document contains an element, ActiveCatalog, which is an integer value indicating the number of catalogs actively being searched. A value of 0 means that the search is complete. While ActiveCatalog is greater than 0, records are being retrieved, deduped, and sorted. When designing a client to consume this service, considerations should be given to a mechanism to keep calling the service with identical query parameters till such point ActiveCatalog is 0.
HTTP Method: GET
HTTP Method: POST
HTTP Header Content-Type: "application/json"
HTTP Header User-Agent: ${user-agent}
Standard HTTP clients (browser, HTTP client libraries, etc.) will automatically include its User-Agent value.
Search URL:
- https://HOSTNAME/di/search
Search request parameters
| Parameter Name | Definition | Required/Optional/etc. | Notes |
|---|---|---|---|
| aid | A valid authorization ID | Required | Refer to authentication service for details |
| query | A valid Common Command Language - CCL (ISO 8777) query | Required | Refer to constructing CCL query for details |
| start | The first record of the result set | Optional | If not provided, the default value of 0 will be used. |
|
num |
The number of records to retrieve |
Optional |
If not provided, the default value of 20 will be used. The maximum support value is 50, meaning, a single cell can, at most, retrieve 50 records. |
|
Note: The start and num parameters are there to limit the response payload to a manageable size. A federated search on a popular title may yield thousands of records, so if the entire result set were returned then it may adversely affect the response time and overflow memory buffers of client applications as well as this web service. This is of particular concern when results are being presented in a web interface, where response time and memory usage is of vital importance, especially on handheld devices. |
|||
|
sortby |
The sort criteria |
Optional |
If not provided, the default value of 'relevance_descending' will be used. Relevance ranking is performed using a variant of the term frequency-inverse document frequency (ref: tf-idf) algorithm. Valid values are:
|
|
datefilter |
A date value (yyyy) which can be used to filter records |
Optional and repeatable |
If provided, only records matching the date filter value returned. The value should be one of the values seen in the date facet collection. The filter is applied to the subset of the result set encapsulated by the start and num parameter value. |
|
mediumfilter |
A medium value which can be used to filter records |
Optional and repeatable |
If provided, only records matching the medium filter value is returned. The value should be one of the values seen in the medium facet collection. The filter is applied to the subset of the result set encapsulated by the start and num parameter values.
|
|
Note: The datefilter and the mediumfilter are applied to the subset of the result set encapsulated by the start and num parameter values. While the search is running (ie: the ActiveCatalog element in the response JSON document is greater than 0), records are being retrieved, deduped, and sorted. As records are sorted, they will change position in the recordset. If the datefilter or mediumfilter is applied to a subset of the result set while the search is active, the records may appear in different subsets if the start or num parameters are changed. To mitigate this issue, consider applying filters only when ActiveCatalog is 0. |
|||
|
recordcountonly |
A parameter used to fetch the number (count) of the filtered records only and not the actual records |
Valid values are true and false (default) |
This parameter is applicable only if datefilter or mediumfilter is provided and it is an optional parameter. |
|
The parameter, recordcountonly, can be useful where this service is integrated with a user interface where N records are displayed in a page view along with pagination. Since the datefilter and mediumfilter are applied to the subset of the result set encapsulated by the start and num parameter values, it may be useful to increment the start parameter and make asynchronously calls to this service to retrieve the total number of records matching the datefilter and mediumfilter across the entire result set of the search. This will enable the UI to display correct pagination when datefilter or mediumfilter are applied effectively to the entire result set in small subsets (N records). |
|||
Request body (HTTP Method: POST):
{
"Catalog":[
{
"Name":"CatalogA"
},
{
"Name":"CatalogB"
},
{
"Name":"..."
}
]
}
Example Calls
Response
The response from this service is a JSON document.
Successful response request
The following is a sample response for a successful request (HTTP status 200 OK):
{
"ActiveCatalog":0,
"TotalMergedRecordCount":0,
"TotalItemCount":0,
"StartIndex":0,
"NumOfRecordRetrieved":0,
"FilteredRecordCount":0,
"Record":[
{
"RecordID":"Unique Record ID",
"Relevance":0,
"RecordTitle":"Author",
"RecordDate":"yyyy",
"RecordMedium":"Medium",
"Item":[
{
"CatalogName":"Catalog Name",
"LCCN":"LCCN",
"BibID": [
"Bib ID"
],
"III-Id":[
"III Id"
],
"OCLCRecordNumber":[
"OCLC Record Number"
],
"ISBN":[
"ISBN"
],
"ISSN": [
"ISSN"
],
"Title":"The stranger",
"Author":[
"Author"
],
"Date":"yyyy",
"Medium":"Medium",
"TitleRemainder":"Title Remainder",
"TitleResponsibility":"Title Responsibility",
"Description":"Description",
"Subject":[
"Subject"
],
"Edition":"Edition",
"Publisher":"Publisher",
"PublicationPlace":"Publication Place",
"PublicationDate":"Publication Date",
"PhysicalExtent":"Physical Extent",
"PhysicalFormat":"Physical Format",
"PhysicalDimension":"Physical Dimension",
"SeriesTitle":"Series Title",
"JournalTitle":"Journal Title",
"JournalSubpart":"Journal Subpart",
"VolumeNumber":"Volume Number",
"IssueDate":"Issue Date",
"IssueNumber":"Issue Number",
"PagesNumber":"Pages Number",
"Holding":[
{
"Format":"Format",
"ShelvingLocation":"Shelving Location",
"CallNumber":"Call Number",
"Availability":"Availability",
"LoanPolicy":"Loan Policy",
"ItemId":"Item Id",
"EnumAndChron":"Enum and Chron"
}
]
}
]
}
]
}
Response value glossary
| Value Name | Definition |
|---|---|
| FilteredRecordCount | An integer value indicating the number of merged records matching the date or format filters in the records retrieved from the underlying subsystem. |
| Record | An object representing a unique deduped record. This value is repeatable and is returned as an array. |
| Record[n].RecordId | A unique record id for a merged record. |
| Record[n].Relevance | An integer value representing the relevance ranking number. The higher the number the better the relevance ranking of the merged record. |
| Record[n].RecordTitle | The title value used to merge records, and this value is part of the record ID. |
| Record[n].RecordAuthor | The author value used to merge records, and this value is part of the record ID. |
| Record[n].RecordDate | The date value used to merge records, and this value is part of the record ID. |
| Record[n].RecordMedium | The medium value used to merge records, and this value is part of the record ID. |
| Record[n].Item | An object representing an item returned by a catalog. This value is repeatable and is returned as an array. |
| Record[n].Item[n].Holding | An object representing holding information for an item as it is returned by a catalog. This value is repeatable and is returned as an array. |
Unsuccessful response request
The following is a sample response for a successful request:
{
"Problem": {
"Code":"PUBHG005",
"Message":"No result"
}
}
Problem codes and messages glossary
| HTTP Status | Code | Type | Message |
|---|---|---|---|
| 400 Bad Request | PUBHG001, PUBSC002 | Public | Missing parameter |
| 400 Bad Request | PUBSC003 | Public | Invalid parameter |
| 400 Bad Request | PUBHG003 | Public | Invalid query |
| 401 Unauthorized | PUBSC004 | Public | Invalid aid |
| 401 Unauthorized | PUBSC006 | Public | User group not authorized to access the service |
| 404 Not Found | PUBHG005 | Public | No result |
| 500 Internal Server Error | PRIHG001, PRISC001 | Private | Internal error |