Israeli Address Autocomplete

Israeli Address Autocomplete

Instructions

Step 1: Parse Address Components

Israeli address format: [Street Name] [Number], [City], [Postal Code] Hebrew: [rechov] [mispar], [ir], [mikud]

Example: rechov Rothschild 42, Tel Aviv-Yafo, 6688310

Ask which address the form wants before formatting anything. Israel has two different addresses for the same person and they are frequently not the same:

A well-formed, correctly-geocoded, correct-mikud address is still the wrong answer to a Bituach Leumi form that asks for the מען. This skill formats and validates addresses; it cannot read the population registry. When a government form is involved, say so and tell the user to take the address from the ספח, and that if the two have diverged the fix is filing a change-of-address notice with the Interior Ministry, not reformatting the address.

Step 2: Validate Components

1. City: Check against the official settlement list (1,310 entries). Query it from the data.gov.il CKAN datastore, see Step 3.
2. Street: Verify the street exists in that city (data.gov.il street dataset)
3. Number: Validate format (number, optional apartment/entrance)
4. Postal code: look it up per address on the Israel Post form; verify it matches the address area

Check whether the locality is divided into streets BEFORE you ask for a street. Israel Post marks each locality as divided or not. A locality that is NOT divided, which covers most kibbutzim and moshavim and many Arab localities, has one locality-wide mikud and no street-level postal codes at all. Asking for a street name there is wrong by construction, and a street-level lookup will return an empty result that looks like a missing address rather than a category error. Israel Post publishes the list of localities with no delivery address or mixed delivery at https://doar.israelpost.co.il/content/no-address.

Step 3: Lookup Missing Data

Settlements and streets: the data.gov.il CKAN datastore is a real keyless public API. Use it rather than the HTML catalogue, which no longer exists. Both datasets are published by רשות האוכלוסין וההגירה (the Population and Immigration Authority), and the code column סמל_ישוב is the same semel yishuv used on government forms.

A bad resource_id returns an HTML error page rather than JSON, so parse the response as JSON and treat a parse failure as a bad request, not as an empty result set.

Postal code (mikud): the documented route is the web form; there is an undocumented API.

The supported, documented route is the web form at https://doar.israelpost.co.il/locatezip, which resolves in three steps: locality, then street within that locality, then house number. Use it for one-off lookups and treat it as the compliant option.

Behind that form is an undocumented JSON API on apimftprd.israelpost.co.il, gated by a subscription key that the site's own client bundle carries. It is usable, and it is the only way to resolve a mikud programmatically, but treat it as best-effort, not a contract:

Derive the key; do not hardcode it. A hardcoded key breaks silently the day it rotates, and every installed copy is wrong at once. The derivation is the durable instruction:

1. Load https://doar.israelpost.co.il/locatezip and read the script tag matching /assets/index-<HASH>.js. This page is bot-protected and returns a redirect to a block page for a plain fetch, so this step generally needs a real browser session.
2. Fetch that bundle and search it for Ocp-Apim-Subscription-Key. It sits next to baseURL:"https://apimftprd.israelpost.co.il".
3. The bundle contains stray NUL bytes, so a plain grep can return nothing on a file that does contain the key. Strip \x00 before matching.

Observed implementation detail, verified 2026-08-26 and recorded so a reader can tell a rotation from a bug: the key in the bundle was 5ccb5b137e7444d885be752eda7f767a, and the API accepts the key alone, with no Origin, Referer or User-Agent header. Do not send forged headers.

The three calls, then the reverse lookup that round-trips the answer:

GET /mypost-zip/getcities-lang?CityStartsWith=<name>&Lang=he
    -> {"id":"1212","sym":"5000","n":"תל אביב - יפו","divided":true,"zip":"0000000"}
GET /mypost-zip/GetStreets-lang?CityID=1212&CityName=&SearchMode=ID-StartsWith&StartsWith=<street>&Lang=he
    -> {"id":"101482","sym":"1103","n":"שדרות רוטשילד"}
GET /mypost-zip/SearchZip-Lang?CityID=1212&StreetID=101482&House=42&Entry=&Lang=he&ByMaanimID=true
    -> {"zip":"6688310","msgtype":"address"}
GET /mypost-zip/searchaddressbyzip-lang?Zip=6688310&Lang=he     (reverse, use it to self-check)
    -> {"cityname":"תל אביב - יפו","streetname":"שדרות רוטשילד","houseNum":"42"}

Three ways this fails silently, and how to tell them apart:

• HTTP 401 means the key is stale, NOT that the address is unknown. Re-derive the key and retry once. Never report a 401 as "address not found"; that is a confidently wrong answer.
• divided: false means the locality has no streets. The city record then carries the whole answer in its own zip field (דגניה א' 1512000, כפר קאסם 4881000, נהלל 1060000). Stop there; do not run the street call.
• Branch on msgtype. address is a real hit, unitedtown means the house number does not exist in a locality that does have streets, notfound means no such mikud. Collapsing these into "not found" loses the distinction the user needs.

Passing the semel yishuv (5000) where CityID (1212) is expected returns "Result":[] with HTTP 200 and no error. See the id-space table below.

Do not use bennymeg/IsraelPostalServiceAPI for mikud, that library is a shipping-price calculator, not an address-to-mikud lookup.

• No street: Suggest closest matching streets from the street dataset above.

Three id spaces that are NOT interchangeable. Feeding one where another is expected returns an empty result with no error, which reads as "address not found":

Step 4: Format Output

Provide address in:

• Hebrew (official format)
• English transliteration
• Structured data (JSON with components separated)

Major City Codes Reference

Granular Components Israeli forms typically expect

Israeli address forms (Bit, Pelephone, Bituach Leumi, banks) often split a single address into separate fields beyond street + number + city:

Kibbutz / moshav addresses typically have no street name, just משק [number], מושב X or קיבוץ X. Form designers should handle this case explicitly.

Examples

Example 1: Format Address

User says: "Format this address for a form: rothschild 42 tel aviv" Result: Hebrew: rechov Rothschild 42, Tel Aviv-Yafo | Mikud: 6688310 (from the Israel Post form) | Settlement code: 5000

Example 2: Find Postal Code

User says: "What's the mikud for Herzl 10, Haifa?" Result: 7-digit postal code with area identification

Example 3: Batch Address Validation

User says: "I have a CSV with 500 Israeli addresses, validate and add postal codes"

Say the hard part first: the mikud half cannot be automated. Settlement codes and street validation can, against the CKAN datastore. Mikud cannot: the only source is a key-gated API whose key must not be scraped, and the web form is one interactive address at a time. Do not promise a mikud column, and never generate one by pattern or by copying a neighbouring row.

Actions:

1. Parse each address into components
2. Resolve settlement codes against the settlements dataset (automatable)
3. Verify each street exists in its locality against the streets dataset (automatable)
4. Detect localities with no named streets and mark them as locality-wide addresses rather than as errors
5. Flag ambiguous localities, and leave the mikud column EMPTY with a per-row reason
6. Tell the user how many rows would need manual mikud lookup, so they can decide whether it is worth doing

Result: A CSV with settlement codes, street-validation status, and per-row flags. The mikud column is deliberately empty, with the count of rows needing manual lookup stated up front.

Bundled Resources

Scripts

• scripts/lookup_address.py - Look up CBS city codes, parse and format Israeli addresses into structured components, and list all known cities with their codes and area codes. Supports subcommands: city, format, cities. Run: python scripts/lookup_address.py --help

References

• references/city-codes.md - CBS settlement codes for the top 30 Israeli cities by population, including district, Hebrew transliteration, and telephone area codes. Also covers the 7-digit postal code (mikud) format and standard address structure. Consult when resolving city names to CBS codes or validating address components.

Gotchas

• Every שם_ישוב value in the CKAN datasets carries trailing whitespace ("אבו גוש "). All 1,310 of 1,310 rows. An exact-match join on the raw field silently returns nothing. Strip before comparing.
• Two localities can share one Latin name on different settlement codes. The Bedouin (שבט) and (יישוב) pairs do exactly this: ABU QUREINAT is both אבו קורינאת (שבט) 968 and אבו קרינאת (יישוב) 1342, and the Hebrew spellings differ too (קורינאת against קרינאת). KHAWALED is 986 and 1321; TARABIN AS-SANI is 970 and 1346. Matching on the Latin name, or on a fuzzy Hebrew match, returns whichever row came first and produces the domain's signature failure: a real code belonging to a different settlement. Disambiguate on סמל_ישוב, and surface both options to the user rather than picking.
• The dataset's Latin name field שם_ישוב_לועזי is hard-truncated at 20 characters (MODI'IN-MAKKABBIM-RE, ASHDOT YA'AQOV(ME'UH) and is empty on some rows including חברון 3400 and סנסנה 3777. Never use it as a join key.
• Every locality has a self-row in the streets dataset with סמל_רחוב = 9000 whose שם_רחוב is the locality name: exactly 1,310 such rows out of 63,571. Listing streets for a locality will otherwise offer the locality's own name as a street. A locality whose ONLY street row is this sentinel has no named streets at all, which is a machine-readable test for the non-divided case that works at CSV scale, unlike the Israel Post HTML list.
• When the registry datasets and Israel Post disagree, they are different authorities and neither is simply right. רשות האוכלוסין וההגירה owns the settlement and street lists that government forms are validated against; Israel Post owns the mikud and the divided or non-divided status. Use the registry for a form's locality and street fields, use Israel Post for the mikud, and surface the conflict to the user rather than silently choosing.
• Israeli street names exist in both Hebrew and Arabic, with different official spellings. Agents may use only the Hebrew name, missing valid Arabic variants that appear on government documents.
• Israeli city names have multiple valid transliterations (e.g., "Tel Aviv" vs "Tel-Aviv" vs "Tel Aviw"). Agents should normalize inputs before matching.
• Settlement and neighborhood boundaries in Israel are politically sensitive. Agents should avoid making assumptions about municipal boundaries, especially for areas in the West Bank or Golan Heights.

Reference Links

Troubleshooting

Error: "Street not found"

Cause: Spelling variation or renamed street Solution: Try common transliteration variants. Many streets have Hebrew-only official names.

Error: "Postal code not matching address area"

Cause: Israel Post periodically updates mikud codes, especially in new developments. Verified: this is a real cause. Not verified as a cause, so do not assert it: a stale cached mikud in a third-party dataset. Solution: Re-resolve the mikud on the Israel Post form rather than from any cached list. New neighbourhoods may have different mikud codes than their parent city.

Error: "Street not found, but the locality exists"

Cause: The locality is not divided into streets. Most kibbutzim and moshavim and many Arab localities have a single locality-wide mikud and no street-level codes, so a street lookup there returns empty rather than erroring. Solution: Check the locality against https://doar.israelpost.co.il/content/no-address before treating an empty street result as a bad address. Format the address as משק [number], [locality] or just the locality, and use the locality-wide mikud.

Error: "City name ambiguity"

Cause: Multiple Israeli settlements share similar names (e.g., Kfar Saba vs Kfar Sava, Ramat Gan vs Ramat HaSharon) Solution: Use CBS settlement code for unambiguous identification. Present the user with a list of matching settlements with their codes and district for disambiguation.