# Israel Address Validator (official street list) (`lirilabs/israel-address-validator`) Actor

Validate and normalise Israeli addresses in Hebrew against the official locality and street lists on data.gov.il. Returns locality code, street code, house number, apartment and a clean address, with suggestions for typos.

- **URL**: https://apify.com/lirilabs/israel-address-validator.md
- **Developed by:** [Liri Labs](https://apify.com/lirilabs) (community)
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-usage

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Israel Address Validator (official street list)

Check lists of Israeli addresses against the **official locality and street lists published on data.gov.il by the Population and Immigration Authority (רשות האוכלוסין וההגירה)**. For each address you get the official locality and street names, their official codes (סמל ישוב, סמל רחוב), the house number, and a clear status that says whether the address is valid, needs a human look, or could not be matched.

The lists are downloaded fresh from data.gov.il on every run, so results follow the latest published version.

### What it does

- Finds the locality in free text, in Hebrew or English (`Haifa`, `Tel Aviv`), and common abbreviations (`ת"א`, `פ"ת`, `ב"ש`, `ראשל"צ`, `ר"ג`, `ב"ב`, `י-ם`).
- Matches the street against the official street list **of that locality only**, in this order: exact name → name without street type (`רח'`, `שד'`, `דרך`, `סמטת`…) → different word order → spelling variant (ו/י added or dropped) → typo similarity.
- Splits house number, apartment (`20/3`, `דירה 4`), floor (`קומה`), entrance (`כניסה`) and a 7-digit postal code.
- Never guesses silently: if two streets or localities are equally close, the status is `ambiguous_*` and you get the candidates as suggestions. Every correction by spelling variant or similarity sets `needsReview: true`.
- Returns a cleaned address in official spelling: `normalizedAddressHe`.

### Who it is for

E-commerce and delivery teams cleaning checkout addresses, CRM and data teams deduplicating customer lists, and anyone who needs official locality/street codes to join address data with other government datasets.

### Input

| Field | Type | Notes |
|---|---|---|
| `addresses` | array of strings | Free-text addresses. |
| `records` | array of objects | Your own `id` plus `address`, or `street` + `houseNumber` + `city`. The `id` is copied to the output. |
| `defaultCity` | string | Used only when an address has no recognisable locality. |
| `onlyProblems` | boolean | Output only rows with `needsReview: true`. The SUMMARY still counts every address. |
| `minStreetSimilarity` | number (0.5–1, default 0.8) | Lower fixes more typos but risks wrong matches. |
| `minCitySimilarity` | number (0.5–1, default 0.85) | Used only when no locality matches exactly. |
| `maxSuggestions` | integer (default 3) | Candidates returned for ambiguous / not-found rows. |

Example input:

```json
{
  "addresses": [
    "הרצל 12, תל אביב",
    "שד' רוטשילד 1 ת\"א 6688101",
    "ביאליק 20/3 רמת גן",
    "אבן גבירוך 30 תל אביב"
  ],
  "records": [{ "id": "order-1001", "street": "הרצל", "houseNumber": "5", "city": "Haifa" }]
}
```

### Output

One dataset row per address. Example (real output from a local run):

```json
{
  "id": "addresses[1]",
  "input": "שד' רוטשילד 1 ת\"א 6688101",
  "status": "valid",
  "isValid": true,
  "needsReview": false,
  "cityCode": 5000,
  "cityHe": "תל אביב - יפו",
  "cityEn": "TEL AVIV - YAFO",
  "subdistrict": "תל אביב",
  "cityMatchType": "exact",
  "streetCode": 1103,
  "streetHe": "שדרות רוטשילד",
  "streetMatchType": "without_street_type",
  "streetSimilarity": 1,
  "houseNumber": "1",
  "postalCode": "6688101",
  "normalizedAddressHe": "שדרות רוטשילד 1, תל אביב - יפו",
  "suggestions": [],
  "issues": ["Postal code copied as written; it is not validated (not part of the source lists)"],
  "sourceUpdatedAt": "2026-11-01T01:30:34.891058"
}
```

Statuses: `valid`, `valid_street_no_house_number`, `valid_locality_without_streets` (the official list has no named streets for that locality), `street_not_found`, `ambiguous_street`, `street_missing`, `city_not_found`, `ambiguous_city`, `empty_input`.

A `SUMMARY` record in the key-value store holds counts by status, the source resources with their last-modified dates, and the attribution line.

### How to use

1. Paste addresses into **addresses** (one per line) or upload JSON **records** with your own ids.
2. Start the run. Loading the official lists takes a few seconds; the matching itself is fast.
3. Open the **Problems** view of the dataset to see only rows that need a human look, or export everything as CSV/Excel/JSON.

Measured locally: 5,000 addresses took about 9 seconds end to end, including about 6–7 seconds to download the lists. Run time on the Apify platform depends on the memory you choose.

### Accuracy (self-test, with caveats)

`bench/benchmark.mjs` builds addresses from 2,000 random rows of the official list and checks whether the Actor returns the same locality and street codes (seed 42, run on 2 Nov 2026):

- Official spelling, `street number, city`: 100% same codes.
- With `רח'` prefix and no comma: 99.4% same codes; 11 marked ambiguous, 1 wrong (flagged for review).
- City first: 100% same codes.
- One letter deleted from the street name: 96.9% same codes; 41 marked ambiguous; 22 wrong, of which 3 were not flagged, because the typo turned the name into another real street name in the same locality.

These numbers come from addresses generated from the official list itself. They do **not** measure real customer data, which is messier. Always review rows with `needsReview: true`.

### Pricing (suggestion for the publisher, not final)

Pay per event: one `address-validated` event per address checked, suggested at about $1.50 per 1,000 addresses. With `onlyProblems` every checked address is still charged. The run stops cleanly when your maximum cost per run is reached.

### Limits

- **Street names must be in Hebrew.** English is supported for locality names only.
- **House numbers are not checked against a building list** (the source has none). A valid status means the locality and the street exist officially.
- **Postal codes are not validated**, only copied.
- Some small localities have no named streets in the official list; these return `valid_locality_without_streets`.
- Local or informal street names, new streets not yet in the published list, and P.O. boxes are not recognised.
- Arabic-script addresses are not supported.

### Data source, license and legal note

- Data: "רשימת ישובים בישראל" and "רשימת רחובות ישראל" on [data.gov.il](https://data.gov.il), published by the Population and Immigration Authority. Source: data.gov.il, Population and Immigration Authority (רשות האוכלוסין וההגירה).
- License: the [data.gov.il usage license](https://data.gov.il/he/terms-of-use) allows commercial use, copying and derived works, and requires naming the source. The localities dataset is marked "Other (Open)"; the streets dataset has no separate license, so the site license applies.
- The lists hold locality and street names and codes only. No personal data is downloaded. Your input addresses are processed only inside your own run and stored only in your run's dataset.
- This Actor is not affiliated with or endorsed by the Government of Israel or the Population and Immigration Authority.
- Results are an automated check against public lists. They are not a guarantee that mail or couriers can deliver to an address, and they are not legal advice.

### Support

Open an issue on the Actor's Issues tab with an example address (remove personal details) and the output you expected.

# Actor input Schema

## `addresses` (type: `array`):

Free-text Israeli addresses. Street names must be in Hebrew; the locality may be in Hebrew, English or a common abbreviation (ת"א, פ"ת, ב"ש). Example: הרצל 12 דירה 4, תל אביב

## `records` (type: `array`):

Objects with your own id plus either "address" (free text) or "street", "houseNumber" and "city". The id is copied to the output so you can join results back to your CRM or orders.

## `defaultCity` (type: `string`):

Used only when an address contains no recognisable locality (for example, a list that is all from one city). Must be an official locality name, e.g. ירושלים.

## `onlyProblems` (type: `boolean`):

Output only rows where needsReview is true (not valid, or corrected by similarity matching). The SUMMARY record still counts every address.

## `minStreetSimilarity` (type: `number`):

0.5 to 1. Lower values fix more typos but risk wrong matches. Fuzzy matches are always flagged in "issues".

## `minCitySimilarity` (type: `number`):

0.5 to 1. Used only when no locality name matches exactly or by a known spelling variant.

## `maxSuggestions` (type: `integer`):

How many candidate streets or localities to return when the match is ambiguous or not found.

## Actor input object example

```json
{
  "addresses": [
    "הרצל 12, תל אביב",
    "שד' רוטשילד 1 ת\"א",
    "ז'בוטינסקי 7 פתח תקוה",
    "ביאליק 20/3 רמת גן"
  ],
  "records": [
    {
      "id": "order-1001",
      "street": "אבן גבירול",
      "houseNumber": "30",
      "city": "תל אביב - יפו"
    }
  ],
  "onlyProblems": false,
  "minStreetSimilarity": 0.8,
  "minCitySimilarity": 0.85,
  "maxSuggestions": 3
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `summary` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "addresses": [
        "הרצל 12, תל אביב",
        "שד' רוטשילד 1 ת\"א",
        "ז'בוטינסקי 7 פתח תקוה",
        "ביאליק 20/3 רמת גן"
    ],
    "records": [
        {
            "id": "order-1001",
            "street": "אבן גבירול",
            "houseNumber": "30",
            "city": "תל אביב - יפו"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("lirilabs/israel-address-validator").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "addresses": [
        "הרצל 12, תל אביב",
        "שד' רוטשילד 1 ת\"א",
        "ז'בוטינסקי 7 פתח תקוה",
        "ביאליק 20/3 רמת גן",
    ],
    "records": [{
            "id": "order-1001",
            "street": "אבן גבירול",
            "houseNumber": "30",
            "city": "תל אביב - יפו",
        }],
}

# Run the Actor and wait for it to finish
run = client.actor("lirilabs/israel-address-validator").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "addresses": [
    "הרצל 12, תל אביב",
    "שד'\'' רוטשילד 1 ת\\"א",
    "ז'\''בוטינסקי 7 פתח תקוה",
    "ביאליק 20/3 רמת גן"
  ],
  "records": [
    {
      "id": "order-1001",
      "street": "אבן גבירול",
      "houseNumber": "30",
      "city": "תל אביב - יפו"
    }
  ]
}' |
apify call lirilabs/israel-address-validator --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,lirilabs/israel-address-validator"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/8O71m5uLOW1on4fTe/builds/4T49nO7bsqP86RufX/openapi.json