{ "openapi": "3.1.0", "info": { "title": "Bituchon public car data API", "version": "1.1.0", "description": "Read-only Israeli car data from ביטוחון (https://bituchon.co.il), operated by ז.א שיווק ומכירות דיגיטליים בע\"מ. Source: Israel Ministry of Transport open datasets on data.gov.il. Catalog endpoints reflect the catalog build date (meta.data_date); the vehicle endpoint is a live lookup.\n\nThe API describes data only. It contains no insurance prices, advice or recommendations. Compulsory (chova) insurance prices are set by insurers and published in the regulator's calculator at https://car.cma.gov.il/. The Ministry's safety-equipment level and safety score are intentionally not exposed. `licence_fee_retrofit_discount` refers to a LICENCE-FEE discount, not insurance.\n\nGeneral information only - not personal insurance advice or a recommendation. The final price is set by the insurer. Consult a suitably qualified professional (\"איש מקצוע מתאים\") before deciding.\n\nהמידע כללי ואינו מהווה ייעוץ או המלצה אישית בביטוח. המחיר הסופי נקבע על ידי חברת הביטוח. לפני קבלת החלטה כדאי להתייעץ עם איש מקצוע מתאים.\n\nEvery response is `{ data, meta }`; cite `meta.citation_url` or the item `url`. CORS is open. An MCP server is available at https://bituchon.co.il/api/mcp.", "contact": { "name": "ז.א שיווק ומכירות דיגיטליים בע\"מ", "url": "https://bituchon.co.il/developers" }, "termsOfService": "https://bituchon.co.il/terms", "x-guidance": "Start with GET /api/v1/search?query=... (Hebrew or English), then /api/v1/fetch?id=... for the full text of a page, or the car endpoints (vehicles/{plate}, models, model-info, thefts, standard-policy, licence-fee, chova-factors). Cite data.citation_url. Every answer has a handoff: when the person wants a quote, offer its WhatsApp link or form, or POST /api/v1/quote-request only after their explicit consent." }, "externalDocs": { "description": "For AI assistants and developers (Hebrew + English)", "url": "https://bituchon.co.il/developers" }, "tags": [ { "name": "catalog", "description": "Makes, models, model years (catalog build)." }, { "name": "vehicle", "description": "Live lookup by licence plate." }, { "name": "facts", "description": "Search, pages, thefts, standard policy, licence fee, chova variables." }, { "name": "contact", "description": "The person asks the operator to call back with a quote (consent required)." } ], "servers": [ { "url": "https://bituchon.co.il" } ], "paths": { "/api/v1/search": { "get": { "operationId": "search", "summary": "Search the site", "description": "Use first for any Israeli car or car-insurance question in Hebrew or English: finds the right page among car models (e.g. \"קורולה\", \"kia picanto\"), makes, guides (chova vs comprehensive, young driver, total loss, renewal, after an accident...), and the data pages (licence fee 2026, car...", "tags": [ "facts" ], "responses": { "200": { "description": "The facts, with citation_url, data_date, source and handoff (how the person can ask for a quote).", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "snippet": { "type": "string" }, "url": { "type": "string" }, "markdown_url": { "type": "string" } }, "required": [ "id", "title", "url" ] } }, "citation_url": { "type": [ "string", "null" ], "description": "Page to cite (link it when you use the facts)." }, "data_date": { "type": [ "string", "null" ], "description": "YYYY-MM-DD the data is correct to." }, "source": { "type": "string" }, "disclaimer": { "type": "string", "description": "Hebrew disclaimer; relay it." }, "disclaimer_en": { "type": "string" }, "handoff": { "type": "object", "description": "How the person can ask the operator for a quote (offer only when relevant; never automatic).", "properties": { "offer_he": { "type": "string" }, "options": { "type": "object" } } }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid input; the message says how to fix it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "query", "in": "query", "required": true, "description": "What the person asked, e.g. \"ביטוח רכב לנהג צעיר\", \"טויוטה קורולה 2019\", \"licence fee\".", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "description": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 10 } } ] } }, "/api/v1/fetch": { "get": { "operationId": "fetch", "summary": "Fetch a page as text", "description": "The full text (clean markdown) of one page, by an id from search, a page URL on the site, or its \".md\" URL. Every page ends with its official sources and data date. Use it to quote a guide or a data page accurately.", "tags": [ "facts" ], "responses": { "200": { "description": "The facts, with citation_url, data_date, source and handoff (how the person can ask for a quote).", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "text": { "type": "string" }, "url": { "type": "string" }, "metadata": { "type": "object" }, "citation_url": { "type": [ "string", "null" ], "description": "Page to cite (link it when you use the facts)." }, "data_date": { "type": [ "string", "null" ], "description": "YYYY-MM-DD the data is correct to." }, "source": { "type": "string" }, "disclaimer": { "type": "string", "description": "Hebrew disclaimer; relay it." }, "disclaimer_en": { "type": "string" }, "handoff": { "type": "object", "description": "How the person can ask the operator for a quote (offer only when relevant; never automatic).", "properties": { "offer_he": { "type": "string" }, "options": { "type": "object" } } }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid input; the message says how to fix it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "query", "required": true, "description": "An id from search (e.g. \"/kia/picanto\", \"/madrich/ovdan-gamur\") or a URL on the site.", "schema": { "type": "string", "minLength": 1, "maxLength": 300 } } ] } }, "/api/v1/vehicle": { "get": { "operationId": "lookup_vehicle", "summary": "Vehicle lookup by plate", "description": "Use when the person gives an Israeli licence plate: live lookup in the Ministry of Transport open data. Returns make, model, year, trim, engine and fuel, safety systems, first registration (on the road since), licence validity and last annual test, open recalls, list price when new, the...", "tags": [ "facts" ], "responses": { "200": { "description": "The facts, with citation_url, data_date, source and handoff (how the person can ask for a quote).", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "vehicle": { "type": [ "object", "null" ], "description": "Registry + model facts for the plate." }, "citation_url": { "type": [ "string", "null" ], "description": "Page to cite (link it when you use the facts)." }, "data_date": { "type": [ "string", "null" ], "description": "YYYY-MM-DD the data is correct to." }, "source": { "type": "string" }, "disclaimer": { "type": "string", "description": "Hebrew disclaimer; relay it." }, "disclaimer_en": { "type": "string" }, "handoff": { "type": "object", "description": "How the person can ask the operator for a quote (offer only when relevant; never automatic).", "properties": { "offer_he": { "type": "string" }, "options": { "type": "object" } } }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid input; the message says how to fix it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "plate", "in": "query", "required": true, "description": "Israeli licence plate, 7 or 8 digits; dashes/spaces allowed (e.g. \"12-345-67\"). / מספר רישוי.", "schema": { "type": "string", "minLength": 7, "maxLength": 12 } } ] } }, "/api/v1/recall": { "get": { "operationId": "check_open_recall", "summary": "Open recall check", "description": "Use when the person asks whether their car has an open recall: checks the plate against the Ministry of Transport list of vehicles that have not completed a manufacturer recall, with what the recall is about and how it is fixed.", "tags": [ "facts" ], "responses": { "200": { "description": "The facts, with citation_url, data_date, source and handoff (how the person can ask for a quote).", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "has_open_recall": { "type": [ "boolean", "null" ] }, "open_recalls": { "type": [ "object", "null" ] }, "model": { "type": [ "object", "null" ] }, "year": { "type": [ "integer", "null" ] }, "citation_url": { "type": [ "string", "null" ], "description": "Page to cite (link it when you use the facts)." }, "data_date": { "type": [ "string", "null" ], "description": "YYYY-MM-DD the data is correct to." }, "source": { "type": "string" }, "disclaimer": { "type": "string", "description": "Hebrew disclaimer; relay it." }, "disclaimer_en": { "type": "string" }, "handoff": { "type": "object", "description": "How the person can ask the operator for a quote (offer only when relevant; never automatic).", "properties": { "offer_he": { "type": "string" }, "options": { "type": "object" } } }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid input; the message says how to fix it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "plate", "in": "query", "required": true, "description": "Israeli licence plate, 7 or 8 digits; dashes/spaces allowed (e.g. \"12-345-67\"). / מספר רישוי.", "schema": { "type": "string", "minLength": 7, "maxLength": 12 } } ] } }, "/api/v1/model-info": { "get": { "operationId": "model_info", "summary": "Model facts", "description": "Use for questions about a car model (optionally one model year) without a plate: cars on the road in Israel, trims, engines, share of cars with each safety system, importer list price when new, recall notices, the annual licence fee per model year (per trim with a fuel-use estimate when a...", "tags": [ "facts" ], "responses": { "200": { "description": "The facts, with citation_url, data_date, source and handoff (how the person can ask for a quote).", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "model": { "type": [ "object", "null" ] }, "summary": { "type": [ "object", "null" ] }, "model_year": { "type": [ "object", "null" ] }, "citation_url": { "type": [ "string", "null" ], "description": "Page to cite (link it when you use the facts)." }, "data_date": { "type": [ "string", "null" ], "description": "YYYY-MM-DD the data is correct to." }, "source": { "type": "string" }, "disclaimer": { "type": "string", "description": "Hebrew disclaimer; relay it." }, "disclaimer_en": { "type": "string" }, "handoff": { "type": "object", "description": "How the person can ask the operator for a quote (offer only when relevant; never automatic).", "properties": { "offer_he": { "type": "string" }, "options": { "type": "object" } } }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid input; the message says how to fix it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "make", "in": "query", "required": true, "description": "Make in Hebrew, English or slug, e.g. \"קיה\", \"Kia\", \"kia\". / יצרן.", "schema": { "type": "string", "minLength": 1, "maxLength": 60 } }, { "name": "model", "in": "query", "required": true, "description": "Model in Hebrew, English or slug, e.g. \"פיקנטו\", \"Picanto\", \"picanto\". / דגם.", "schema": { "type": "string", "minLength": 1, "maxLength": 80 } }, { "name": "year", "in": "query", "required": false, "description": "Model year (שנת ייצור). Optional.", "schema": { "type": "integer", "minimum": 1950, "maximum": 2100 } } ] } }, "/api/v1/thefts": { "get": { "operationId": "theft_by_model", "summary": "Car thefts by model", "description": "Use when the person asks how often a model is stolen, whether it is a \"stolen a lot\" car, or why the insurer asks for anti-theft protection: Israel Police theft and recovery counts 2023-2025 for the model (FOI release), thefts per 1,000 cars on the road against all private cars, the...", "tags": [ "facts" ], "responses": { "200": { "description": "The facts, with citation_url, data_date, source and handoff (how the person can ask for a quote).", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "model": { "type": [ "object", "null" ] }, "thefts": { "type": [ "object", "null" ], "description": "by_year [{year, thefts, recovered}], rate_per_1000, rate_year, national_rate_per_1000, shared_with, top_production_years" }, "national": { "type": [ "object", "null" ] }, "page_url": { "type": "string" }, "citation_url": { "type": [ "string", "null" ], "description": "Page to cite (link it when you use the facts)." }, "data_date": { "type": [ "string", "null" ], "description": "YYYY-MM-DD the data is correct to." }, "source": { "type": "string" }, "disclaimer": { "type": "string", "description": "Hebrew disclaimer; relay it." }, "disclaimer_en": { "type": "string" }, "handoff": { "type": "object", "description": "How the person can ask the operator for a quote (offer only when relevant; never automatic).", "properties": { "offer_he": { "type": "string" }, "options": { "type": "object" } } }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid input; the message says how to fix it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "make", "in": "query", "required": false, "description": "Make in Hebrew, English or slug, e.g. \"קיה\", \"Kia\", \"kia\". / יצרן.", "schema": { "type": "string", "minLength": 1, "maxLength": 60 } }, { "name": "model", "in": "query", "required": false, "description": "Model in Hebrew, English or slug, e.g. \"פיקנטו\", \"Picanto\", \"picanto\". / דגם.", "schema": { "type": "string", "minLength": 1, "maxLength": 80 } }, { "name": "plate", "in": "query", "required": false, "description": "Instead of make + model. Israeli licence plate, 7 or 8 digits; dashes/spaces allowed (e.g. \"12-345-67\"). / מספר רישוי.", "schema": { "type": "string", "minLength": 7, "maxLength": 12 } } ] } }, "/api/v1/standard-policy": { "get": { "operationId": "standard_policy_at_age", "summary": "What the standard comprehensive policy guarantees at this car age", "description": "Use when the person asks what a comprehensive (מקיף) policy must give them for a car of a given age: under the regulator's standard policy (הפוליסה התקנית) an insurer replacing a part must use an original or new part up to age 2, pays without depreciation up to age 9, and total loss is paid...", "tags": [ "facts" ], "responses": { "200": { "description": "The facts, with citation_url, data_date, source and handoff (how the person can ask for a quote).", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "age": { "type": [ "object", "null" ], "description": "months (exact) or min_years/max_years (from a model year)" }, "tier": { "type": "string", "enum": [ "new", "mid", "old", "edge2", "edge9" ] }, "lead_he": { "type": "string" }, "points_he": { "type": "array", "items": { "type": "string" } }, "example_he": { "type": "string" }, "total_loss_he": { "type": "string" }, "extension_he": { "type": [ "string", "null" ] }, "sources": { "type": "array" }, "page_url": { "type": "string" }, "citation_url": { "type": [ "string", "null" ], "description": "Page to cite (link it when you use the facts)." }, "data_date": { "type": [ "string", "null" ], "description": "YYYY-MM-DD the data is correct to." }, "source": { "type": "string" }, "disclaimer": { "type": "string", "description": "Hebrew disclaimer; relay it." }, "disclaimer_en": { "type": "string" }, "handoff": { "type": "object", "description": "How the person can ask the operator for a quote (offer only when relevant; never automatic).", "properties": { "offer_he": { "type": "string" }, "options": { "type": "object" } } }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid input; the message says how to fix it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "plate", "in": "query", "required": false, "description": "Most exact. Israeli licence plate, 7 or 8 digits; dashes/spaces allowed (e.g. \"12-345-67\"). / מספר רישוי.", "schema": { "type": "string", "minLength": 7, "maxLength": 12 } }, { "name": "on_road_since", "in": "query", "required": false, "description": "First registration month \"YYYY-MM\" (as on the vehicle licence).", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{1,2}" } }, { "name": "year", "in": "query", "required": false, "description": "Model year, when nothing better is known (the age is then a range).", "schema": { "type": "integer", "minimum": 1950, "maximum": 2100 } } ] } }, "/api/v1/chova-factors": { "get": { "operationId": "explain_chova_price", "summary": "What drives compulsory (chova) insurance pricing", "description": "Use when the person asks what their compulsory insurance (ביטוח חובה) price depends on: which of the regulator's pricing variables come from the car and what the ministry data says for this car (by plate) or for each trim of a model-year (make + model + optional year), plus the driver...", "tags": [ "facts" ], "responses": { "200": { "description": "The facts, with citation_url, data_date, source and handoff (how the person can ask for a quote).", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "mode": { "type": "string" }, "car_factors": { "type": "array" }, "trims": { "type": "array" }, "driver_factors_he": { "type": "array" }, "chova_calculator_url": { "type": "string" }, "citation_url": { "type": [ "string", "null" ], "description": "Page to cite (link it when you use the facts)." }, "data_date": { "type": [ "string", "null" ], "description": "YYYY-MM-DD the data is correct to." }, "source": { "type": "string" }, "disclaimer": { "type": "string", "description": "Hebrew disclaimer; relay it." }, "disclaimer_en": { "type": "string" }, "handoff": { "type": "object", "description": "How the person can ask the operator for a quote (offer only when relevant; never automatic).", "properties": { "offer_he": { "type": "string" }, "options": { "type": "object" } } }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid input; the message says how to fix it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "plate", "in": "query", "required": false, "description": "Israeli licence plate, 7 or 8 digits; dashes/spaces allowed (e.g. \"12-345-67\"). / מספר רישוי.", "schema": { "type": "string", "minLength": 7, "maxLength": 12 } }, { "name": "make", "in": "query", "required": false, "description": "Make in Hebrew, English or slug, e.g. \"קיה\", \"Kia\", \"kia\". / יצרן.", "schema": { "type": "string", "minLength": 1, "maxLength": 60 } }, { "name": "model", "in": "query", "required": false, "description": "Model in Hebrew, English or slug, e.g. \"פיקנטו\", \"Picanto\", \"picanto\". / דגם.", "schema": { "type": "string", "minLength": 1, "maxLength": 80 } }, { "name": "year", "in": "query", "required": false, "description": "Model year (שנת ייצור). Optional.", "schema": { "type": "integer", "minimum": 1950, "maximum": 2100 } } ] } }, "/api/v1/licence-fee": { "get": { "operationId": "explain_licence_fee", "summary": "Annual licence fee (agrat rishui)", "description": "Use for the Israeli annual car licence fee (אגרת רישוי) for private cars up to 3.5 t: the official table (7 price groups x 4 age tiers, valid 1.4.2026-31.3.2027), how the price group is fixed at first registration, the 135 ILS broadcasting add-on, and the safety-retrofit reduction (a...", "tags": [ "facts" ], "responses": { "200": { "description": "The facts, with citation_url, data_date, source and handoff (how the person can ask for a quote).", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "mode": { "type": "string" }, "licence_fee": { "type": [ "object", "null" ] }, "table": { "type": [ "object", "null" ] }, "page_url": { "type": "string" }, "citation_url": { "type": [ "string", "null" ], "description": "Page to cite (link it when you use the facts)." }, "data_date": { "type": [ "string", "null" ], "description": "YYYY-MM-DD the data is correct to." }, "source": { "type": "string" }, "disclaimer": { "type": "string", "description": "Hebrew disclaimer; relay it." }, "disclaimer_en": { "type": "string" }, "handoff": { "type": "object", "description": "How the person can ask the operator for a quote (offer only when relevant; never automatic).", "properties": { "offer_he": { "type": "string" }, "options": { "type": "object" } } }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid input; the message says how to fix it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "plate", "in": "query", "required": false, "description": "Israeli licence plate, 7 or 8 digits; dashes/spaces allowed (e.g. \"12-345-67\"). / מספר רישוי.", "schema": { "type": "string", "minLength": 7, "maxLength": 12 } }, { "name": "make", "in": "query", "required": false, "description": "Make in Hebrew, English or slug, e.g. \"קיה\", \"Kia\", \"kia\". / יצרן.", "schema": { "type": "string", "minLength": 1, "maxLength": 60 } }, { "name": "model", "in": "query", "required": false, "description": "Model in Hebrew, English or slug, e.g. \"פיקנטו\", \"Picanto\", \"picanto\". / דגם.", "schema": { "type": "string", "minLength": 1, "maxLength": 80 } }, { "name": "year", "in": "query", "required": false, "description": "Model year (שנת ייצור). Optional.", "schema": { "type": "integer", "minimum": 1950, "maximum": 2100 } } ] } }, "/api/v1/quote-request": { "post": { "operationId": "request_quote_callback", "summary": "Ask ז.א to call the person back with a car-insurance quote", "description": "ONLY after the person asked for a quote and explicitly agreed to: \"אני מאשר/ת את מסירת הפרטים שמילאתי ל-ז.א שיווק ומכירות דיגיטליים בע\"מ ואת השימוש בהם ליצירת קשר איתי בנושא ביטוח רכב, בהתאם לתקנון ולמדיניות הפרטיות.\" Then consent=true. Never on your own; only details they gave.", "tags": [ "contact" ], "responses": { "200": { "description": "The facts, with citation_url, data_date, source and handoff (how the person can ask for a quote).", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "properties": { "created": { "type": "boolean" }, "status": { "type": "string", "enum": [ "received", "already_received", "dry_run_not_sent", "consent_required" ] }, "request_id": { "type": [ "string", "null" ] }, "operator": { "type": "string" }, "consent_text": { "type": "string" }, "consent_version": { "type": "string" }, "citation_url": { "type": [ "string", "null" ], "description": "Page to cite (link it when you use the facts)." }, "data_date": { "type": [ "string", "null" ], "description": "YYYY-MM-DD the data is correct to." }, "source": { "type": "string" }, "disclaimer": { "type": "string", "description": "Hebrew disclaimer; relay it." }, "disclaimer_en": { "type": "string" }, "handoff": { "type": "object", "description": "How the person can ask the operator for a quote (offer only when relevant; never automatic).", "properties": { "offer_he": { "type": "string" }, "options": { "type": "object" } } }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } }, "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid input; the message says how to fix it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 80, "description": "The person's full name, as they gave it. / שם מלא." }, "phone": { "type": "string", "minLength": 9, "maxLength": 20, "description": "The person's Israeli phone number, e.g. 050-1234567 or +972-50-1234567. / טלפון." }, "plate": { "type": "string", "minLength": 7, "maxLength": 12, "description": "Optional. Israeli licence plate, 7 or 8 digits; dashes/spaces allowed (e.g. \"12-345-67\"). / מספר רישוי." }, "make": { "type": "string", "minLength": 1, "maxLength": 60, "description": "Optional, when there is no plate. Make in Hebrew, English or slug, e.g. \"קיה\", \"Kia\", \"kia\". / יצרן." }, "model": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Optional, with make. Model in Hebrew, English or slug, e.g. \"פיקנטו\", \"Picanto\", \"picanto\". / דגם." }, "year": { "type": "integer", "minimum": 1950, "maximum": 2100, "description": "Model year (שנת ייצור). Optional." }, "interest": { "type": "string", "enum": [ "general", "chova", "makif", "tzad_g", "renewal" ], "default": "general", "description": "general | chova (compulsory) | makif (comprehensive) | tzad_g (third party) | renewal." }, "consent": { "type": "boolean", "const": true, "description": "true only after the person explicitly agreed to: \"אני מאשר/ת את מסירת הפרטים שמילאתי ל-ז.א שיווק ומכירות דיגיטליים בע\"מ ואת השימוש בהם ליצירת קשר איתי בנושא ביטוח רכב, בהתאם לתקנון ולמדיניות הפרטיות.\"" } }, "required": [ "name", "phone", "consent" ], "additionalProperties": false }, "example": { "name": "ישראל ישראלי", "phone": "050-1234567", "plate": "12-345-67", "interest": "makif", "consent": true } } } }, "x-openai-isConsequential": true } }, "/api/v1/vehicles/{plate}": { "get": { "operationId": "getVehicle", "tags": [ "vehicle" ], "summary": "Vehicle by licence plate (live)", "description": "Registry + model spec + open recall lookup for an Israeli private car. Rate limited per client IP (30 per 10 minutes). Responses are private-cacheable only and not indexed.", "parameters": [ { "name": "plate", "in": "path", "required": true, "description": "7 or 8 digits; dashes allowed.", "schema": { "type": "string", "pattern": "^[0-9\\- ]{7,12}$" } } ], "responses": { "200": { "description": "Vehicle", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Vehicle" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid plate", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in the private-vehicle registries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Ministry data service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/makes": { "get": { "operationId": "listMakes", "tags": [ "catalog" ], "summary": "Car makes", "parameters": [ { "name": "all", "in": "query", "description": "1 = include makes without a page.", "schema": { "type": "string", "enum": [ "1" ] } } ], "responses": { "200": { "description": "Makes, most cars on the road first", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Make" } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } } } } }, "/api/v1/models": { "get": { "operationId": "listModels", "tags": [ "catalog" ], "summary": "Search / list models", "parameters": [ { "name": "make", "in": "query", "description": "Make slug or name (Hebrew / English).", "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Model name in Hebrew or Latin, e.g. \"קורולה\", \"corolla\", \"cx5\".", "schema": { "type": "string" } }, { "name": "vehicleClass", "in": "query", "description": "private | commercial. Keeps models with registrations in that class (commercial = vans, pickups, light trucks up to 3.5 t, ministry sug_degem M); without q, ordered by cars in that class.", "schema": { "type": "string", "enum": [ "private", "commercial" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } } ], "responses": { "200": { "description": "Models (neutral order: match quality, then cars on the road)", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ModelSummary" } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "404": { "description": "Unknown make", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/models/{make}/{model}": { "get": { "operationId": "getModel", "tags": [ "catalog" ], "summary": "Model facts", "parameters": [ { "name": "make", "in": "path", "required": true, "description": "Make slug, e.g. \"kia\".", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "model", "in": "path", "required": true, "description": "Model slug, e.g. \"picanto\".", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } } ], "responses": { "200": { "description": "Model", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Model" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "404": { "description": "No model page data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/models/{make}/{model}/{year}": { "get": { "operationId": "getModelYear", "tags": [ "catalog" ], "summary": "Model-year facts with trims", "parameters": [ { "name": "make", "in": "path", "required": true, "description": "Make slug, e.g. \"kia\".", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "model", "in": "path", "required": true, "description": "Model slug, e.g. \"picanto\".", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "year", "in": "path", "required": true, "description": "Model year", "schema": { "type": "string", "pattern": "^\\d{4}$" } } ], "responses": { "200": { "description": "Model year", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ModelYear" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "Invalid year", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No data for this year", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Meta": { "type": "object", "required": [ "source", "data_date", "disclaimer", "docs" ], "properties": { "source": { "type": "string", "description": "Data source (Hebrew)." }, "data_date": { "type": [ "string", "null" ], "description": "Date the data was pulled from the Ministry, YYYY-MM-DD." }, "disclaimer": { "type": "string", "description": "Hebrew disclaimer - show it with the data." }, "docs": { "type": "string", "example": "/openapi.json" }, "citation_url": { "type": "string", "description": "Public page to cite." } }, "additionalProperties": true }, "Error": { "type": "object", "required": [ "data", "error", "meta" ], "properties": { "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "Make": { "type": "object", "properties": { "slug": { "type": "string" }, "name_he": { "type": "string" }, "name_en": { "type": "string" }, "cars_on_road": { "type": "integer" }, "models": { "type": "integer" }, "models_with_page": { "type": "integer" }, "url": { "type": [ "string", "null" ] }, "markdown_url": { "type": [ "string", "null" ] }, "api_url": { "type": "string" } } }, "ModelSummary": { "type": "object", "properties": { "key": { "type": "string" }, "make_slug": { "type": "string" }, "make_name_he": { "type": [ "string", "null" ] }, "make_name_en": { "type": [ "string", "null" ] }, "slug": { "type": "string" }, "name_he": { "type": "string" }, "name_latin": { "type": "string" }, "cars_on_road": { "type": "integer" }, "vehicle_class": { "type": "string", "enum": [ "private", "commercial" ], "description": "Class of most cars (commercial = up to 3.5 t)." }, "private_cars": { "type": "integer" }, "commercial_cars": { "type": "integer" }, "years": { "type": [ "object", "null" ], "properties": { "from": { "type": "integer" }, "to": { "type": "integer" } } }, "has_page": { "type": "boolean" }, "url": { "type": [ "string", "null" ] }, "api_url": { "type": "string" } } }, "SafetyAdoption": { "type": "object", "description": "Share (0-1) of cars on the road that have each system.", "properties": { "abs": { "type": "number", "minimum": 0, "maximum": 1 }, "esp": { "type": "number", "minimum": 0, "maximum": 1 }, "fcw": { "type": "number", "minimum": 0, "maximum": 1 }, "ldw": { "type": "number", "minimum": 0, "maximum": 1 }, "aeb": { "type": "number", "minimum": 0, "maximum": 1 }, "adaptive_cruise": { "type": "number", "minimum": 0, "maximum": 1 }, "blind_spot": { "type": "number", "minimum": 0, "maximum": 1 }, "airbags": { "type": "object", "properties": { "min": { "type": [ "integer", "null" ] }, "max": { "type": [ "integer", "null" ] } } } } }, "Trim": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "cars_on_road": { "type": "integer" }, "engine_cc": { "type": [ "integer", "null" ] }, "horsepower": { "type": [ "integer", "null" ] }, "fuel": { "type": [ "string", "null" ] }, "drive": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] }, "automatic": { "type": [ "boolean", "null" ] }, "airbags": { "type": [ "integer", "null" ] }, "safety": { "type": "object", "properties": { "abs": { "type": [ "boolean", "null" ] }, "esp": { "type": [ "boolean", "null" ] }, "fcw": { "type": [ "boolean", "null" ] }, "ldw": { "type": [ "boolean", "null" ] }, "lane_keep": { "type": [ "boolean", "null" ] }, "aeb": { "type": [ "boolean", "null" ] }, "pedestrian_detection": { "type": [ "boolean", "null" ] }, "adaptive_cruise": { "type": [ "boolean", "null" ] }, "blind_spot": { "type": [ "boolean", "null" ] }, "reverse_camera": { "type": [ "boolean", "null" ] } } }, "co2_wltp_g_km": { "type": [ "number", "null" ] }, "list_price_when_new_ils": { "type": [ "integer", "null" ], "description": "Importer list price when new (not current value, not an insurance price)." }, "licence_groups": { "type": "array", "items": { "type": "integer" }, "description": "Official licence-fee price groups (kvuzat_agra_cd, 1-7)." }, "licence_fee_ils": { "type": [ "object", "null" ], "description": "Annual licence fee incl. the 135 ILS broadcasting add-on (table valid 2026-04-01..2027-03-31)." }, "fuel_l_per_100km_estimate": { "type": [ "number", "null" ], "description": "ESTIMATE from the official CO2 figure (carbon balance). Null for EVs, plug-ins and missing CO2." }, "fuel_estimate_basis": { "type": [ "string", "null" ], "enum": [ "WLTP", "NEDC", null ] } } }, "Model": { "type": "object", "properties": { "key": { "type": "string" }, "make": { "type": "object", "properties": { "slug": { "type": "string" }, "name_he": { "type": "string" }, "name_en": { "type": "string" } } }, "slug": { "type": "string" }, "name_he": { "type": "string" }, "name_latin": { "type": "string" }, "url": { "type": "string" }, "markdown_url": { "type": "string" }, "api_url": { "type": "string" }, "cars_on_road": { "type": "integer" }, "cars_inactive": { "type": "integer" }, "removed_since_2017": { "type": "integer" }, "vehicle_class": { "type": "string", "enum": [ "private", "commercial" ] }, "class_split": { "type": "object", "properties": { "private": { "type": "integer" }, "commercial": { "type": "integer" } } }, "years": { "type": [ "object", "null" ], "properties": { "from": { "type": "integer" }, "to": { "type": "integer" } } }, "body_types": { "type": "array", "items": { "type": "object", "properties": { "body": { "type": "string" }, "cars_on_road": { "type": "integer" } } } }, "engine_classes": { "type": "array", "items": { "type": "object", "properties": { "fuel": { "type": "string" }, "cc_band": { "type": "string" }, "cars_on_road": { "type": "integer" } } } }, "list_price_when_new_ils": { "type": [ "object", "null" ] }, "safety_adoption": { "$ref": "#/components/schemas/SafetyAdoption" }, "recalls": { "type": "object", "properties": { "notices": { "type": "integer" }, "notices_last_5_years": { "type": "integer" }, "open_recall_cars": { "type": "integer" }, "open_recall_share": { "type": "number" }, "open_recall_campaigns": { "type": "integer" } } }, "model_years": { "type": "array", "items": { "type": "object" } }, "thefts": { "type": [ "object", "null" ], "description": "Israel Police theft counts for private cars (FOI release published by התנועה לחופש המידע). Facts only, not a risk ranking; rate_per_1000 is null for small samples.", "properties": { "by_year": { "type": "array", "items": { "type": "object", "properties": { "year": { "type": "integer" }, "thefts": { "type": "integer" }, "recovered": { "type": "integer" } } } }, "rate_per_1000": { "type": [ "number", "null" ] }, "rate_year": { "type": "integer" }, "national_rate_per_1000": { "type": "number" }, "cars_on_road_denominator": { "type": "integer" }, "shared_with": { "type": "array", "items": { "type": "string" } }, "attribution": { "type": "string" }, "source_url": { "type": "string" }, "data_url": { "type": "string" }, "checked": { "type": "string" } } } } }, "ModelYear": { "type": "object", "properties": { "year": { "type": "integer" }, "has_page": { "type": "boolean" }, "url": { "type": [ "string", "null" ] }, "markdown_url": { "type": [ "string", "null" ] }, "api_url": { "type": "string" }, "cars_on_road": { "type": "integer" }, "cars_inactive": { "type": "integer" }, "removed_since_2017": { "type": "integer" }, "list_price_when_new_ils": { "type": [ "object", "null" ] }, "safety_adoption": { "$ref": "#/components/schemas/SafetyAdoption" }, "engine_classes": { "type": "array", "items": { "type": "object" } }, "trims": { "type": "array", "items": { "$ref": "#/components/schemas/Trim" } }, "open_recall": { "type": "object", "properties": { "cars": { "type": "integer" }, "campaigns": { "type": "integer" } } }, "licence_fee_ils": { "type": [ "object", "null" ], "description": "Annual licence fee range over the trims {min, max, price_groups, age_tier}." }, "annual_cost_estimate_ils": { "type": [ "object", "null" ], "description": "ESTIMATE: licence fee + petrol at the CBS average km and the regulated petrol price. Insurance never included." }, "model": { "$ref": "#/components/schemas/Model" } } }, "Vehicle": { "type": "object", "properties": { "plate": { "type": "string" }, "plate_display": { "type": "string" }, "registry_status": { "type": "string", "enum": [ "active", "inactive" ] }, "vehicle_class": { "type": "string", "enum": [ "private", "commercial" ] }, "make": { "type": "object" }, "model": { "type": "object" }, "year": { "type": "integer" }, "trim": { "type": [ "string", "null" ] }, "on_road_since": { "type": [ "string", "null" ] }, "ownership": { "type": [ "string", "null" ] }, "color": { "type": [ "string", "null" ] }, "engine": { "type": "object" }, "body": { "type": [ "string", "null" ] }, "doors": { "type": [ "integer", "null" ] }, "seats": { "type": [ "integer", "null" ] }, "safety_systems": { "type": "object" }, "licence": { "type": "object", "properties": { "valid_until": { "type": [ "string", "null" ] }, "last_inspection": { "type": [ "string", "null" ] } } }, "licence_fee_retrofit_discount": { "type": "object", "description": "Ministry list of cars eligible for an annual LICENCE-FEE discount after a safety retrofit. Not an insurance variable." }, "list_price_when_new_ils": { "type": [ "object", "null" ] }, "licence_fee": { "type": [ "object", "null" ], "description": "Exact annual licence fee (אגרת רישוי): official price group x age tier + 135 ILS broadcasting add-on. Null when the model has no group." }, "annual_cost_estimate": { "type": "object", "description": "Labelled ESTIMATE (is_estimate=true): licence fee + fuel at the average km. insurance = \"by_quote\", never summed." }, "open_recalls": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "unavailable" ], "description": "\"unavailable\" means unknown, not \"no recall\"." }, "count": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object" } } } }, "chova_factors": { "type": "array", "items": { "type": "object" }, "description": "Car-side compulsory-insurance pricing variables (no prices)." }, "chova_driver_factors_he": { "type": "array", "items": { "type": "string" } }, "urls": { "type": "object" }, "fetched_at": { "type": "string" } } } } } }