Search API Common Usage

Request Format

https://api.nli.org.il/openlibrary/search?api_key={USER_KEY}&{search_string}

Search Content Options

A {search_string} is composed by {query} string and by [additional filters]. The delimiter between the query and between [additional filters] parameters is "&" (logical AND). The delimiter inside the {query} string, between internal query conditions is ",AND;" (or ",OR";)

A query compares a text to one / few / all descriptive attributes, and can filter by start_date / end_date and/or language and/or system_number and/or shelfmark.

Query string example:

query=title,exact,jerusalem,AND;publisher,contains,jaffa,AND;language,exact,eng,AND;system_number,exact,990023677080205171,AND;start_date, contains,1925,AND;shelfmark,exact,Jer344

Additional Search String filters / commands

Filters: availability_type, material_type

Commands: output_format, count_mode, result_page, items_per_page, sort_field

Search example (including query and additional filters):

https://api.nli.org.il/openlibrary/search?api_key={USER_KEY}&query=title,exact,jerusalem,AND;publisher,contains,jaffa,AND;language,exact,eng,AND;system_number,exact,990023677080205171,AND;start_date,contains,1925,AND;shelfmark,exact,Jer344&availability_type=online_and_api_access&material_type=manuscripts

Search example (including query, additional filters and commands):

https://api.nli.org.il/openlibrary/search?api_key={USER_KEY}&query=title,exact,jerusalem,AND;publisher,contains,jaffa,AND;language,exact,eng,AND;system_number,exact,990023677080205171,AND;start_date,contains,1925,AND;shelfmark,exact,Jer344&availability_type=online_and_api_access&material_type=manuscripts&output_format=xml&result_page=2&sort_field=title

FAQ

• How do I search for map items that contains the word 'Jerusalem' in title and have full access by API
  https://api.nli.org.il/openlibrary/search?api_key={USER_KEY}&query=title,contains,jerusalem&availability_type=online_and_api_access&material_type=maps
• How do I search for Newspaper items on Jpress collection, with publisher code of ' unzsft'
  https://api.nli.org.il/openlibrary/search?api_key={USER_KEY}&material_type=NEWSPAPER&query=title,exact,unzsft
  
  
• How do I search for a specific item by system_number
  https://api.nli.org.il/openlibrary/search?api_key={USER_KEY}&query=system_number,exact,990023677080205171
  
  
• How can I Count the number of items that my criteria returns
  https://api.nli.org.il/openlibrary/search?api_key={USER_KEY}&query=title,exact,jerusalem&count_mode=true
  
  
• How can I Paginate on results, when more than 50 items matches my criteria
  https://api.nli.org.il/openlibrary/search?api_key={USER_KEY}&query=title,exact,jerusalem&result_page=3
  
  
• How can I define multiple criteria on query string:
  • Search for any item that contains the word 'Jerusalem' on title AND are written in English language AND has start_date/end_date between 19500101 and 19501231. Output format is XML
    https://api.nli.org.il/openlibrary/search?api_key={USER_KEY}&query=title,exact,jerusalem,AND;creator,contains,Jerusalem,AND;language,exact,eng,AND;start_date,contains,1951&sort_field=title&output_format=xml
• Q: What if my query has syntax error – is it ignored, or will I get HTTP Error response?
• A: If the Search string has a syntax error in a non-mandatory attribute, the condition is ignored and an "Errors" Header will describe the error. For Mandatory condition, HTTP Error code with a message will be returned
  • Example for "Errors" message:
    

    curl -v -k "https://api.nli.org.il/openlibrary/search?api_key={USER_KEY}&query=title,exact,jerusalem&availability_type=online_and_api_access&material_type=manuscripts111 "
    Response Header
    > User-Agent: curl/7.29.0
    > Host: api.nli.org.il
    > Accept: */*
    >
    < HTTP/1.1 200 OK
    < Server: openresty
    < Date: Mon, 31 May 2021 14:24:48 GMT
    < Content-Type: application/json;charset=UTF-8
    < Content-Length: 1223
    < Connection: keep-alive
    < Vary: Accept-Encoding
    < X-RateLimit-Limit: 1000
    < X-RateLimit-Remaining: 966
    < Errors: {"Errors":[{"code":1010,"description":"\"material_type\" with value : \"manuscripts111\" hasn't been used because it is invalid.\"","value":"ERROR_NOT_USE_PARAMETER"},{"code":1014,"description":"Invalid page number. The first page was returned instead.","value":"ERROR_GET_OVER_ARTICLE"}]}
    < Age: 1
    < Via: http/1.1 api-umbrella (ApacheTrafficServer [cMsSf ])
    < X-Cache: MISS