Israeli Heritage Explorer

Israeli Heritage Explorer

Problem

Researching Israeli and Jewish cultural history requires navigating millions of records across the National Library of Israel's digital archives. Without structured access, researchers spend hours browsing the NLI website manually, miss relevant primary sources, and struggle to connect related materials across collections. This skill provides AI-powered search and report generation directly through the NLI OpenLibrary API, transforming raw archive data into organized, citation-ready research output.

Instructions

Overview

This skill searches the National Library of Israel (NLI) digital archives via the OpenLibrary API. The NLI holds millions of items spanning Jewish heritage and Israeli culture: ancient manuscripts, government records, historical photographs, maps, music recordings, oral histories, and scholarly publications.

When to Use

• User asks about Israeli history (any period: Ottoman, British Mandate, early statehood, modern)
• User wants primary sources on Jewish heritage topics
• User needs historical photographs or maps of Israeli locations
• User asks about immigration waves (aliyah) to Israel
• User wants to research a specific community, neighborhood, or institution's history
• User needs an annotated bibliography on an Israeli cultural topic

API Access

The NLI OpenLibrary API is free. The base endpoint is:

https://api.nli.org.il/openlibrary/search

Authentication: Every request needs an api_key query parameter. There are two ways to get one:

• Sign up for a free personal key at https://api2.nli.org.il/signup/. This is the right answer for any real research session.
• Use NLI's published guest key for a quick trial with no signup. NLI prints it on its own Search API page: DVQyidFLOAjp12ib92pNJPmflmB5IessOq1CJQDK. It is shared and heavily throttled: in testing it returned 429 OVER_RATE_LIMIT rather than results, so treat it as a way to check your query syntax, not as a working research key.

Recommended MCP Server: Install the nli-search MCP for direct AI-powered access to the NLI API with natural language queries, IIIF image retrieval, and media streaming.

Search Parameters

A request is query={clauses} plus optional standalone filters and commands, joined with &. Most filtering happens INSIDE the query as field,operator,value clauses (this is the documented mechanism). Language and date filtering are query clauses, NOT standalone parameters.

The query attributes (used as the field in a clause):

Operators: contains (partial match, most common) and exact.

Standalone filters and commands (appended with &, outside the query):

availability_type is the single most important parameter for a remote researcher, and it is the one most often left off. A catalogue record is not a scan. A large share of NLI holdings are catalogued but not freely viewable online, and the default result set mixes the two, so an unfiltered search returns items the user cannot actually open. If the user needs material they can read now, filter to online_access (or online_and_api_access). If they are building a bibliography and can visit or request items, leave it open, but say in the output which items are viewable and which are not.

Unknown parameters (such as the old rows, start, publication_year_from/_to) are silently IGNORED by the API: the request still returns results, just unfiltered, with the skipped condition listed in an Errors response header. Always filter via the documented attributes above.

Two routes: pick the one your host can actually run

This skill's data path is the NLI API, and not every host can reach it the same way. Check which tier you are on BEFORE promising the user a search:

Route B: the public catalogue, in the USER's browser. NLI's public discovery layer is Merhav, at merhav.nli.org.il (the main site is nli.org.il). It needs no API key and no signup.

Be honest with the user about who does the searching here. On these hosts you cannot run the search yourself. merhav.nli.org.il and www.nli.org.il sit behind a Cloudflare interstitial that an automated fetcher does not clear: in testing a headless browser was held at "Just a moment..." indefinitely, and even an interactive browser session took around twelve seconds to clear it. Do not present a Merhav URL as an endpoint you can call, and do not promise the user results you have not seen. Instead, hand them something they can execute: the search terms to type, which attributes to put them in, which filters to set, and what to look for. Then work from what they report back.

The interface uses the same field,operator,value grammar as the API (any,contains,..., title,contains,..., creator,contains,...), so the search thinking below transfers directly. Merhav also exposes facets the API does not surface as cleanly, notably Usage Rights and Availability, which is why it is worth sending a user there even when Route A is available to you.

Research Workflow

Follow these steps when a user requests historical research:

Step 1: Clarify the research scope

Ask or infer:

• Time period. Useful search ranges: Ottoman to 1917/18, British rule 1917-1948 (military administration until 1920, civil Mandate administration from 1920), early statehood 1948-1967, modern 1967-present. These are search conveniences for building date clauses, not NLI classifications, and the boundaries are conventions rather than facts to quote at the user.
• Geographic focus (specific city, region, or all of Israel)
• Material types wanted (photographs, documents, books, maps, audio)
• Language preference (Hebrew, English, Arabic, Yiddish, Ladino)

Step 2: Search the NLI API

Build targeted queries. Filter by language and date INSIDE the query as clauses; use material_type and availability_type as standalone & filters. Join multiple clauses with a semicolon plus an explicit connector (,AND; or ,OR;); the connector belongs to the clause it follows, and the final clause has no trailing connector. Format:

query=field,operator,value,AND;field,operator,value&material_type=...

A caution on date clauses. The contains operator is a substring match, not a range. start_date,contains,1917 matches dates containing "1917"; it does NOT express "from 1917 onward", and pairing it with an end_date,contains clause does not express a range either. NLI's own documentation contains an example with this confusion in it. For a genuine range, expect to filter the returned date values yourself, and tell the user what you actually filtered on rather than implying a range query succeeded.

# Photographs relating to Jaffa, with a 1917 date string (type as a filter)
query=title,contains,Jaffa,AND;start_date,contains,1917&material_type=images

# Hebrew manuscripts about Jerusalem (language as a clause)
query=title,contains,Jerusalem,AND;language,exact,heb&material_type=manuscripts

# David Ben-Gurion's writings in Hebrew
query=creator,contains,Ben Gurion,AND;language,exact,heb&material_type=books

# American Colony photographs of Jerusalem in English
query=title,exact,jerusalem,AND;creator,contains,American Colony,AND;language,exact,eng&material_type=images

Use ,OR; to broaden instead of narrow. To page through more than 50 results add &result_page=2; to change ordering add &sort_field=date_asc. Do NOT use material_type=images with the old values like photos or videos; only the values in the Search Parameters table are valid (invalid values are silently dropped).

Step 3: Process results

Each result contains:

• title -- item title (often in Hebrew)
• type -- material type (book, archive, image, etc.)
• date -- publication/creation date
• publisher -- publishing body
• language -- content language
• recordid -- unique NLI identifier
• @id -- direct link to the item on nli.org.il
• linkToMarc -- IIIF manifest link for images

Step 4: Generate research output

Format findings into one of these deliverables:

Annotated Bibliography:

## Annotated Bibliography: [Topic]

### Primary Sources

1. **[Title]** / [Creator] ([Date])
   - Type: [manuscript/photograph/map/etc.] | Language: [Hebrew/English/etc.]
   - Held by: National Library of Israel[, Collection if the record names one]
   - Shelfmark: [shelfmark] | System number: [recordid]
   - Permalink: [NNL_ALEPH permalink, not a session URL]
   - Access: [viewable online / in library only / no online access, from availability]
   - Rights: [usage-rights status, or "not established"]
   - Relevance: [1-2 sentence annotation explaining significance]
   - Consulted: [date]

2. ...

### Secondary Sources
...

### Suggested Further Research
- [Related topics or collections to explore]

Research Report:

## Research Report: [Topic]

### Historical Context
[2-3 paragraphs providing context based on found sources]

### Key Primary Sources
[Numbered list with annotations]

### Visual Materials
[Photographs, maps with descriptions and NLI links]

### Timeline
[Chronological list of key events with source citations]

### Source List
[Full citation list, each entry in the form given under "Citing an NLI item": title, creator, date, holding institution, collection, shelfmark, system number, permalink, access status, rights status and consultation date]

### Search Limits
[What was searched, on which attributes, with which availability filter, and what this search cannot rule out. Required: see the null-result rule under Troubleshooting]

Key NLI Collections

When guiding research, be aware of these major collections:

IIIF Image Access

For visual materials, the NLI provides IIIF (International Image Interoperability Framework) endpoints:

• Image API: https://iiif.nli.org.il/IIIFv21/{identifier}/full/max/0/default.jpg
• Manifest (linkToMarc) form: https://iiif.nli.org.il/IIIFv21/marc/bib/{docid} (lowercase marc/bib)

Prefer the linkToMarc / @id value returned in each result rather than hand-building these URLs. Use the manifest to get all available images for a multi-page item (manuscript, book, newspaper).

Period-Specific Research Tips

Ottoman period (search range to 1917/18):

• Search in Ottoman Turkish, Arabic, and Hebrew
• Key subjects: land ownership (tabu), religious courts (sharia), Jewish communities (yishuv)
• Ottoman-era administrative records (land registers, sharia court records) are largely NOT NLI holdings: they sit with state and religious-court custodians. Search NLI for published, photographic, cartographic and personal-papers material about the period, and route administrative-record requests to the institutions in the table below

British rule (search range 1917-1948):

• 1917 is the Ottoman military defeat and the Balfour Declaration, not the start of the Mandate. British military administration ran from 1917, and civil Mandate administration began in 1920. For 1917-1920 material, search the military administration, and do not tell a user researching Mandate government records that the Mandate began in 1917
• Rich in English-language administrative documents
• Search title,contains,Palestine for Mandate-era materials, and try publisher,contains, for government and institutional imprints
• Major topics: immigration certificates, land purchases, urban planning, newspapers

Early statehood (search range 1948-1967):

• Government publications, Knesset records, military documents
• Immigration wave (mass aliyah) documentation
• Development town planning, cultural institution founding

Modern period (search range 1967-present):

• Oral history recordings, contemporary photography
• Academic research, cultural documentation

NLI is not the only archive, and often not the right one

This skill searches NLI holdings. NLI is a library: its archival strength is personal papers, manuscripts, maps, photographs, sound and the historical press. A great deal of what users ask for is held elsewhere, and sending them to NLI for it produces a confident empty result:

Say this to the user when their question points outside NLI, rather than reporting "no results found".

Citing an NLI item

A URL is not a citation, and the search response already contains everything a proper one needs. For each item give: title, creator, date, the holding institution (National Library of Israel), the collection where the result names one, the shelfmark / call number, and the system number (recordid, which also forms the stable permalink). Prefer the permalink over a session URL.

Rights and reuse

Users of this skill routinely want to reproduce an image in a report, a slide deck or a publication. Do not imply that anything found here is free to reuse. Rights differ item by item: NLI's catalogue distinguishes free use, non-commercial use, use for research/study/teaching, and items where copying is prohibited outright. The Usage Rights facet in Merhav (Route B) is the fastest way to see an item's status, and NLI runs a copyright-queries service for anything unclear. State the rights status alongside any image you surface, and where it is unknown, say it is unknown.

Bundled Resources

See the references/ directory for:

• nli-api-reference.md -- full API parameter reference with examples
• historical-periods.md -- detailed Israeli historical periods with key search terms

Gotchas

1. Query minimum length: NLI documents that a basic query must contain at least a three-character string over one of the search attributes. Single Hebrew letters and very short English words fail this. Use descriptive terms instead.

2. Hebrew search vs. English search: Many NLI records have metadata in Hebrew only. If an English search returns few results, retry with Hebrew terms. The API does NOT auto-translate between languages.

3. Date format quirks: The date field in results uses inconsistent formats: some items have YYYYMMDD, others have YYYY, and some have free-text dates like [circa 1930] or תרצ"ב. Parse dates defensively.

4. Material type values are a fixed set: The valid material_type values are books, journals, images, audio_video, scores, maps, archives, sheets, dissertations, manuscripts, media, databases, NEWSPAPER, Identity. There is no audio, videos, articles, or rareBooks (use audio_video, NEWSPAPER, etc.). An invalid value is silently dropped (the request returns UNFILTERED results, not zero results), with the dropped condition noted in the response Errors header. Newspapers use the all-caps NEWSPAPER.

5. Unknown parameters are ignored, not rejected: Passing a parameter the API does not recognize (for example the old rows, start, publication_year_from) does not error: the condition is silently skipped and you get unfiltered results. Filter language and dates as query clauses (language,exact,eng, start_date,contains,1951), not as standalone parameters.

6. Cloudflare protection is triggered by the curl/* User-Agent string, not by your IP and not by a missing User-Agent. This was previously documented as a datacenter-IP block, which sent people down the wrong path. Tested behaviour from a single machine: sending curl/8.x as the User-Agent returns an HTML Cloudflare challenge page. Sending python-urllib/3.11, a browser string, the bundled script's own NLI-Heritage-Explorer/1.0, or NO User-Agent header at all, all reach the real API and return structured JSON. In other words the rule targets the curl signature specifically. So: send any User-Agent other than curl's default, and if you are debugging, check whether the body is HTML (Cloudflare) or JSON (the API answering), because that distinction tells you which problem you have. One trap when diagnosing this: a bare curl command with no -A flag is NOT a request without a User-Agent, it still sends curl/x.y.z, which is exactly the blocked string.

7. subject is UNCONFIRMED as a recognised attribute, and a wrong attribute fails SILENTLY. NLI's documentation names the filterable attributes explicitly (start_date / end_date, language, system_number, shelfmark) but describes the text side only as "one / few / all descriptive attributes", without publishing a closed list. subject appears in none of the worked examples, and we have not been able to test it against a live keyed call. Treat it as unverified rather than as known-good or known-bad. Combined with gotcha 5, the failure mode is nasty: if the API does not recognise the attribute, it drops the condition and returns UNFILTERED results, which look like a successful broad search. Whenever you use subject, inspect the Errors response header. If it reports the condition was skipped, fall back to title,contains and creator,contains, and say so in the output rather than presenting unfiltered results as a topical search.

8. exact is unforgiving on names and Hebrew orthography. Several examples here use title,exact. Under exact a maqaf (תל-אביב vs תל אביב), defective vs plene spelling (ירושלם vs ירושלים), and Latin transliteration variants (Herzl / Hertzl / Herzel / הרצל) will not match. Use contains for personal and place names, and try more than one spelling before concluding NLI holds nothing.

Troubleshooting

Query rejected as too short

NLI documents that a basic query must include at least a three-character string over one of the search attributes. Single Hebrew letters and very short tokens fail this. Use a longer, more descriptive term. (Earlier versions of this skill quoted a specific error string here; the documented rule is the reliable thing to match on, not a remembered message.)

Empty results for a known topic

First, the rule that matters most: an empty result set does not prove the material does not exist. The API searches catalogued records. Uncatalogued and unprocessed material is invisible to it, holdings elsewhere are invisible to it, and a condition the API silently dropped can distort the result in either direction. Never report "NLI has nothing on this". Report what you searched, on which attributes, with which availability filter, and what came back.

Then try:

1. Switch between English and Hebrew search terms, and try Arabic where the topic warrants it
2. Use contains rather than exact, and try spelling variants (see gotcha 8)
3. Widen or drop the date clauses. Remember they are substring matches, not ranges, so an ANDed start_date + end_date pair asks for a date string containing BOTH years and will usually match nothing
4. Remove the material_type filter to search across all types
5. Check the Errors response header before concluding anything: if a condition was dropped, your "empty" or "full" result is not what you think it is
6. Consider that the right institution may not be NLI at all (see the table above)

Note on subject: earlier versions of this skill recommended switching to subject,contains here. That recommendation has been REMOVED, and no example in this skill uses subject any more. subject is absent from every published NLI attribute list, and an unrecognised attribute is dropped silently and returns UNFILTERED results, so the recommendation could turn a zero-result search into a falsely full one with nothing in the output to signal it. Broaden with title,contains and creator,contains, or use the browser route and reuse the exact subject heading the catalogue itself shows.

403 or 429 response

Do not guess the cause: the API distinguishes them clearly in the response BODY, and three different problems all surface as a non-200. Read the body before telling the user anything.

Only the second row is "the key expired". Earlier versions of this skill asserted that cause for every 403, which sent users to re-issue a key that was working.

IIIF image not loading

Some items are restricted rather than broken. Use availability_type to reason about this: online_in_library_only marks material viewable only on NLI premises, and no_online_access marks material with no digital surrogate at all, so a catalogue hit for either will never yield an image. Do not report a specific access-status field name unless you can see it in the response you actually received.