Schuna Intelligence API

Base URL

https://schuna.co.il/api/v1

Authentication

The free tier requires no authentication — requests are rate-limited by IP (50 req/day). For higher limits, include your API key in the request header:

X-API-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

To get an API key, contact avi2k3x@gmail.com.

Rate limit status is returned in every response via headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Plan matrix endpoint: GET /api/v1/plans or /pricing.

GET /api/v1/plans

Returns the current public freemium / pro / enterprise plan matrix for API consumers.

curl "https://schuna.co.il/api/v1/plans"

Response Shape

{
  "currency": "ILS",
  "billingCycle": "monthly",
  "plans": [
    {
      "id": "free",
      "name": "Free",
      "monthlyPriceIls": 0,
      "dailyRequestLimit": 50,
      "apiKeyRequired": false
    },
    {
      "id": "pro",
      "name": "Pro",
      "monthlyPriceIls": 399,
      "dailyRequestLimit": 1000,
      "apiKeyRequired": true
    }
  ],
  "upgradeContact": "avi2k3x@gmail.com"
}

GET /api/v1/intelligence

Returns full intelligence data for a single Israeli address or coordinate.

Query Parameters

Example Request — by address

curl "https://schuna.co.il/api/v1/intelligence?address=רוטשילד+71+תל+אביב" \
  -H "X-API-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Example Request — by coordinates

curl "https://schuna.co.il/api/v1/intelligence?lat=32.065&lng=34.778" \
  -H "X-API-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response Structure

{
  "address": {
    "displayName": "רוטשילד 71, תל אביב-יפו",
    "city": "תל אביב-יפו",
    "street": "רוטשילד",
    "houseNumber": "71",
    "lat": 32.065,
    "lng": 34.778
  },
  "score": {
    "total": 82,          // 0-100 composite score
    "grade": "A",         // A+ / A / A- / B+ ... D
    "label": "מצוין",     // Hebrew label
    "summary": "תחנת שלמה הגנדי — 4 דק' הליכה · אין בנייה פעילה בסביבה",
    "percentileRank": 89, // Higher than 89% of addresses
    "flags": [
      { "type": "positive", "icon": "✓", "labelHe": "בית ספר יסודי בטווח הליכה" },
      { "type": "info",     "icon": "·", "labelHe": "תוכנית פינוי-בינוי בסביבה" }
    ]
  },
  "layers": {
    "transport": {
      "stops": [
        {
          "id": "...",
          "nameHe": "שלמה הגנדי",
          "line": "קו כחול",
          "type": "METRO",
          "status": "OPERATIONAL",
          "distanceM": 280,
          "walkMinutes": 4
        }
      ],
      "count": 3
    },
    "planning": {
      "zones": [
        {
          "id": "...",
          "nameHe": "תכנית פינוי-בינוי שדרות רוטשילד",
          "type": "PINUI_BINUI",
          "status": "APPROVED"
        }
      ],
      "count": 1
    },
    "permits": {
      "permits": [ /* building permit objects */ ],
      "count": 2
    },
    "antennas": {
      "summary": { "total": 3, "nearest": 180 },
      "antennas": [ /* antenna objects */ ],
      "count": 3
    },
    "schools": {
      "schools": [ /* school objects */ ],
      "count": 4
    },
    "airQuality": {
      "stations": [ /* air quality station objects */ ],
      "count": 1
    },
    "floodRisk": {
      "level": "LOW",
      "nearestWatercourse": null,
      "distanceM": null
    },
    "noise": {
      "level": "MEDIUM",
      "sources": [ /* road/rail source objects */ ],
      "summary": "שדרות רוטשילד — דרך ראשית ב-45מ'"
    }
  },
  "meta": {
    "requestId": "req_abc123",
    "tier": "pro",
    "rateLimitLimit": 1000,
    "rateLimitRemaining": 987,
    "rateLimitReset": 1740000000
  }
}

Widget / Embed

Embed an address intelligence widget on any website — no API key required for the free tier. The widget renders inside an <iframe> hosted on schuna.co.il.

Option 1 — JS Snippet (recommended)

Add a data-schuna-address attribute to any <div>, then load the script once. Works with multiple widgets on the same page.

<!-- 1. Place a div with your address -->
<div data-schuna-address="רוטשילד 71 תל אביב"></div>

<!-- 2. Load the script once, anywhere on the page -->
<script src="https://schuna.co.il/widget.js"></script>

Option 2 — Direct iframe

<iframe
  src="https://schuna.co.il/widget?address=רוטשילד+71+תל+אביב"
  width="100%"
  height="360"
  style="border:none;border-radius:12px;"
  title="שכונה — בינה שכונתית"
></iframe>

Widget Parameters

Dark Theme Example

<div
  data-schuna-address="דיזנגוף 50 תל אביב"
  data-schuna-theme="dark"
  data-schuna-height="380"
></div>
<script src="https://schuna.co.il/widget.js"></script>

For white-label widget licensing (custom branding, no שכונה attribution), contact avi2k3x@gmail.com.

Error Codes

Error Response Shape

{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Daily limit of 50 requests reached. Resets at midnight UTC.",
  "retryAfter": 1740000000
}

Data Sources

All data is cached (7 days for most sources) and served from the Skhuna infrastructure. Response times are typically 200–800ms depending on cache hit rate.

Legal