DiscoverItem - Search overview

Find an overview of DiscoverItem - Search in Relais D2D, including search request parameters, example calls, and response.

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: 

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:

  • relevance_descending
  • relevance_ascending
  • title_descending
  • title_ascending
  • date_descending
  • date_ascending

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

Search with "aid" and "query" parameters
  • aid=12knsfd987234ldfd2
  • query=ti%3D%22The%20Stranger%22%20and%20au%3D%22Albert%22%20and%20au%3D%22Camus%22
    { ti="The Stranger" and au="Albert" and au="Camus" }

https://HOSTNAME/di/search?aid=12knsfd987234ldfd2&query=ti%3D%22The%20Stranger%22%20and%20au%3D%22Albert%22%20and%20au%3D%22Camus%22

Search The Stranger by Albert Camus. 

Search with "aid", "query", "start", and "num" parameters
  • aid=12knsfd987234ldfd2
  • query=ti%3D%22The%20Stranger%22%20and%20au%3D%22Albert%22%20and%20au%3D%22Camus%22
    { ti="The Stranger" and au="Albert" and au="Camus" }
  • start=20
  • num=30

https://HOSTNAME/di/search?aid=12knsfd987234ldfd2&query=ti%3D%22The%20Stranger%22%20and%20au%3D%22Albert%22%20and%20au%3D%22Camus%22&start=20&num=30

Search The Stranger by Albert Camus and retrieve records starting at record 20 and fetch 30 records. 

Search with "aid", "query", and "sortby" parameters
  • aid=12knsfd987234ldfd2
  • query=ti%3D%22The%20Stranger%22%20and%20au%3D%22Albert%22%20and%20au%3D%22Camus%22
    { ti="The Stranger" and au="Albert" and au="Camus" }
  • sortby=date_ascending

https://HOSTNAME/di/search?aid=12knsfd987234ldfd2&query=ti%3D%22The%20Stranger%22%20and%20au%3D%22Albert%22%20and%20au%3D%22Camus%22&sortby=date_ascending

Search The Stranger by Albert Camus and sort the results by date in ascending order.

Search with "aid", "query", and "datefilter" parameters
  • aid=12knsfd987234ldfd2
  • query=ti%3D%22The%20Stranger%22%20and%20au%3D%22Albert%22%20and%20au%3D%22Camus%22
    { ti="The Stranger" and au="Albert" and au="Camus" }
  • datefilter=1946
  • datefilter=2002

https://HOSTNAME/di/search?aid=12knsfd987234ldfd2&query=ti%3D%22The%20Stranger%22%20and%20au%3D%22Albert%22%20and%20au%3D%22Camus%22&datefilter=1946&datefilter=2002

Search The Stranger by Albert Camus and retrieve records with publication date matching 1946 or 2002. The date filter will be applied to 20 records starting at 0. The default start parameter value of 0 and num parameter value of 20 will be applied

Search with "aid", "query", and "mediumfilter" parameters
  • aid=12knsfd987234ldfd2
  • query=ti%3D%22The%20Stranger%22%20and%20au%3D%22Albert%22%20and%20au%3D%22Camus%22
    { ti="The Stranger" and au="Albert" and au="Camus" }
  • mediumfilter=book
  • mediumfilter=book%20%28electronic%29 { book (electronic) }

https://HOSTNAME/di/search?aid=12knsfd987234ldfd2&query=ti%3D%22The%20Stranger%22%20and%20au%3D%22Albert%22%20and%20au%3D%22Camus%22&mediumfilter=book&mediumfilter=book%20%28electronic%29

Search The Stranger by Albert Camus and retrieve records with medium matching book or book (electronic). The medium filter will be applied to 20 records starting at 0. The default start parameter value of 0 and num parameter value of 20 will be applied. 

Search with "aid", "query", "datefilter", and "mediumfilter" parameters
  • aid=12knsfd987234ldfd2
  • query=ti%3D%22The%20Stranger%22%20and%20au%3D%22Albert%22%20an d%20au%3D%22Camus%22
    { ti="The Stranger" and au="Albert" and au="Camus" }
  • datefilter=1946
  • mediumfitler=book

https://HOSTNAME/di/search?aid=12knsfd987234ldfd2&query=ti%3D%22The%20Stranger%22%20and%20au%3D%22Albert%22%20and%20au%3D%22Camus%22&datefilter=1946&mediumfilter=book

Search The Stranger by Albert Camus and retrieve records with publication date matching 1946 and medium matching book. The medium filter will be applied to 20 records starting at 0. The default start parameter value of 0 and num parameter value of 20 will be applied.  

Search with "aid", "query", "start", "numb", "datefilter", and "mediumfilter" parameters
  • aid=12knsfd987234ldfd2
  • query=ti%3D%22The%20Stranger%22%20and%20au%3D%22Albert%22%20an d%20au%3D%22Camus%22
    { ti="The Stranger" and au="Albert" and au="Camus" }
  • start=20
  • num=30
  • datefilter=1946
  • mediumfilter=book

https://HOSTNAME/di/search?aid=12knsfd987234ldfd2&query=ti%3D%22The%20Stranger%22%20and%20au%3D%22Albert%22%20and%20au%3D%22Camus%22&start=20&num=30&datefilter=1946&mediumfilter=book

Search The Stranger by Albert Camus and retrieve records with publication date matching 1946 and medium matching book. The medium filter will be applied to 30 records starting at 20.

 Search with "aid", "query", "start", "num", "datefilter", "mediumfilter", and "recordcountonly" parameters
  • aid=12knsfd987234ldfd2
  • query=ti%3D%22The%20Stranger%22%20and%20au%3D%22Albert%22%20an d%20au%3D%22Camus%22
    { ti="The Stranger" and au="Albert" and au="Camus" }
  • start=20
  • num=30
  • datefilter=1946
  • mediumfilter=book
  • recordcountonly=true

https://HOSTNAME/di/search?aid=12knsfd987234ldfd2&query=ti%3D%22The%20Stranger%22%20and%20au%3D%22Albert%22%20and%20au%3D%22Camus%22&start=20&num=30&datefilter=1946&mediumfilter=book&recordcountonly=true

Search The Stranger by Albert Camus and retrieve the count of records with publication date matching 1946 and medium matching book. The medium filter will be applied to 30 records starting at 20

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