نقاط النهاية

كل نقطة نهاية عامة في واجهة API لمنصة Kaleidr موثقة في قسم مستقل.

عنوان URL الأساسي: https://api.kaleidr.com/inference-api/b2b/v1
بيانات الاعتماد: استخدم Authorization: Bearer … أو X-Api-Key: …. من الخادم الخلفي، استخدم مفتاح خادم (kld_sk_live_…)، ومن المتصفح، استخدم رمز جلسة (kld_sess_live_…). لا يُقبل المفتاح القابل للنشر إلا عند تبادل الجلسة. راجع المصادقة والنطاقات.
أجسام الطلبات: تكون بصيغة JSON وترميز UTF-8. أرسل Content-Type: application/json في كل طلب POST. الحد الأقصى لجسم الطلب هو 2 MiB، أو 5 MiB لنقاط النهاية /design/*. تُرفض الطلبات الأكبر برمز 413 request_too_large.
الأخطاء: استجابات 4xx أو 5xx مصحوبة بجسم JSON كما هو موضح في الأخطاء. توجد نقطة نهاية واحدة تعلن الفشل برمز 200: راجع الاتجاهات.

تستخدم الأمثلة مفتاح خادم محفوظاً في متغير بيئة:

export KALEIDR_KEY="kld_sk_live_…"

ملخص

نقطة النهاية	الغرض	النطاق	التكلفة
`POST /sdk/sessions`	تبادل مفتاح قابل للنشر للحصول على جلسة	نطاق المنتج	تحميل خريطة واحد عند استخدام `tile`؛ وبخلاف ذلك مجانًا
`POST /sdk/share-sessions`	تبادل معرّف خريطة منشورة للحصول على جلسة دردشة	لا يوجد	مجانًا
`POST /chat/control/stream`	طرح سؤال وبث الإجابة مع الأماكن والإجراءات والمسارات	`ai`	أرصدة الذكاء الاصطناعي بحسب الرموز المستهلكة
`POST /chat/control/route`	الحصول على اتجاهات بين إحداثيات معروفة	`ai`	مجانًا
`GET /retrieval/geocode/forward`	تحويل النص المدخل إلى أماكن وعناوين	`ai`	أرصدة الذكاء الاصطناعي، رسم ثابت
`POST /spot`	تحديد الموجود في نقطة: المكان وعنوانه ومناطقه ومحتواه اختياريًا	`ai`	أرصدة الذكاء الاصطناعي، رسم ثابت
`POST /spot/overview/stream`	بث نبذة قصيرة عن عنصر من `/spot`	`ai`	أرصدة الذكاء الاصطناعي بحسب الرموز المستهلكة
`GET /retrieval/poi/enrich`	مهملة، استخدم `/spot`. تفاصيل وصور مكان واحد	`ai`	أرصدة الذكاء الاصطناعي، رسم ثابت
`POST /chat/summary/stream`	مهملة، استخدم `/spot/overview/stream`. بث ملخص عن مكان أو مبنى	`ai`	أرصدة الذكاء الاصطناعي بحسب الرموز المستهلكة
`POST /chat/button/stream`	بث إجابة لسؤال واحد عن مكان واحد	`ai`	أرصدة الذكاء الاصطناعي بحسب الرموز المستهلكة
`POST /design/analyze`	اقتراح تصميم خريطة لجدول بيانات	`design`	أرصدة الذكاء الاصطناعي، رسم ثابت
`POST /design/apply-direct`	إنشاء طبقة خريطة من جدول ونمط محدد	`design`	مجانًا
`GET /design/styles`, `/design/samples`, `/design/themes`	كتالوجات التصميم	`design`	مجانًا

ترد تفاصيل الرسوم والحجوزات والحدود في الحصص وحدود المعدل.

قد تعيد أي نقطة نهاية وقت التشغيل الأخطاء المذكورة في الأخطاء المشتركة بين جميع نقاط نهاية وقت التشغيل. تذكر الأقسام التالية الأخطاء الخاصة بكل نقطة فقط.

POST /sdk/sessions

تستبدل هذه النقطة مفتاحًا قابلًا للنشر برمز جلسة قصير الأجل مرتبط بمصدر الطلب ومنتج واحد. يستدعيها SDK تلقائيًا عند كل تركيب يستخدم مفتاحًا. لا تستدعها بنفسك إلا إذا كنت تطوّر عميلًا خاصًا يعمل في المتصفح.

المصادقة: مفتاح قابل للنشر. مطلوب: ترويسة Origin (يضيفها المتصفح). التكلفة: تحميل خريطة واحد عندما تكون قيمة product هي tile؛ ولا شيء بخلاف ذلك.

الحقل	النوع	مطلوب	ملاحظات
`product`	سلسلة نصية	نعم	إحدى القيم `chat` أو `editor` أو `viewer` أو `tile`.

curl -s https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions \
  -H "X-Api-Key: kld_pk_live_…" \
  -H "Origin: https://www.example.com" \
  -H "Content-Type: application/json" \
  -d '{"product":"chat"}'

{
  "session_token": "kld_sess_live_eyJhbGciOi…",
  "expires_in": 900,
  "product": "chat",
  "basemap_style_id": null
}

يمثل basemap_style_id خريطة الأساس الافتراضية لمؤسستك، أو null إذا لم تُعيَّن خريطة افتراضية.

الحالة	الرمز	متى يحدث
401	`Invalid or missing API key`	المفتاح غير معروف أو أُلغي أو انتهت صلاحيته.
403	`publishable_key_required`	أُرسل مفتاح خادم أو مفتاح قديم.
403	`origin_required`	ترويسة `Origin` مفقودة.
403	`origin_not_allowed`	المصدر غير موجود في قائمة المصادر المسموح بها للمفتاح.
403	`product_not_allowed`	قائمة منتجات المفتاح المسموح بها لا تشمل `product`.
403	`tier_capability_not_allowed`	خطتك لا تتضمن المنتج أو نطاقه.
403	`insufficient_scope`	أُنشئ المفتاح دون النطاق المطلوب للمنتج.
422	خطأ التحقق	`product` غير موجود أو ليس واحدة من القيم الأربع.
429	`rate_limited`	حدثت عمليات تبادل كثيرة لهذا المفتاح. `Retry-After: 5`.
429	`map_load_quota_exceeded`	خاص بـ`tile`: استُنفد رصيد تحميل الخرائط.
404	`sessions_disabled`	الجلسات معطلة على المنصة. تواصل مع الدعم.
503	`sessions_not_configured`	خلل في المنصة. أعد المحاولة، واتصل بالدعم إن استمر.

توضح المصادقة والنطاقات: تبادل الجلسة مدة الصلاحية وقاعدة التجديد وترتيب هذه الفحوص.

تستبدل معرّف خريطة منشورة بجلسة دردشة، بحيث يمكن للزوار استخدام الدردشة دون تضمين مفتاح في الصفحة. يجب أن تفعّل لوحة Kaleidr AI الخاصة بالخريطة في Studio الميزة المطلوبة.

المصادقة: لا شيء. مطلوب: ترويسة Origin. التكلفة: لا شيء؛ وتُحمّل تكلفة مكالمات الدردشة بهذه الجلسة على مؤسسة مالك الخريطة.

الحقل	النوع	مطلوب	ملاحظات
`share_id`	سلسلة نصية	نعم	من 1 إلى 128 حرفًا: حروف وأرقام و`_` و`-`.
`feature`	سلسلة نصية	لا	`control_tower` (الافتراضية)، وهي لوحة Ask Kaleidr الخاصة بالخريطة، أو `popups`، وهي محادثة AI في نوافذها المنبثقة. لا تُمنح كل منهما إلا ما دام مفتاحها مفعّلًا.

curl -s https://api.kaleidr.com/inference-api/b2b/v1/sdk/share-sessions \
  -H "Origin: https://www.example.com" \
  -H "Content-Type: application/json" \
  -d '{"share_id":"your-map-id","feature":"control_tower"}'

{ "session_token": "kld_sess_live_eyJhbGciOi…", "expires_in": 300, "product": "chat" }

الحالة	الرمز	متى يحدث
403	`origin_required`	ترويسة `Origin` مفقودة.
404	`not_found`	لا توجد خريطة منشورة أو رابط مشاركة بهذا المعرّف، أو أُلغي نشر خريطة رابط المشاركة.
403	`chat_disabled`	لا يفعّل Kaleidr AI الخاص بالخريطة الميزة المطلوبة.
403	`origin_not_allowed`	الصفحة ليست ضمن النطاقات المسموح بها للخريطة.
403	`owner_has_no_organization`	مالك الخريطة غير تابع لمؤسسة.
403	`tier_capability_not_allowed`	خطة المالك لا تتضمن الدردشة.
422	خطأ التحقق	`share_id` مفقود أو يتضمن أحرفًا غير مسموح بها، أو `feature` ليست أيًّا من القيمتين.
429	`rate_limited`	عمليات تبادل كثيرة لهذه الخريطة أو من هذا العنوان. `Retry-After: 5`.
404	`sessions_disabled`	الجلسات معطلة على المنصة.
503	`share_grant_unavailable`, `sessions_not_configured`	خلل في المنصة. أعد المحاولة.

راجع Kaleidr AI على خريطة منشورة.

POST /chat/control/stream

تتلقى هذه النقطة سؤالًا وتبث الإجابة نصًا أثناء كتابتها، مع الأماكن المذكورة وإحداثياتها وإجراءات الخريطة والمسارات. وهي نقطة النهاية التي تشغّل Kaleidr Chat.

المصادقة: مفتاح خادم أو رمز جلسة أو مفتاح قديم. النطاق: ai. التكلفة: رصيد AI بحسب عدد الرموز التي استخدمتها الإجابة. الاستجابة: text/event-stream كما توضح مواصفات نقل SSE.

الحقل	النوع	مطلوب	الافتراضي	ملاحظات
`messages`	مصفوفة من `{ role, content }`	لا	`[]`	المحادثة حتى الآن، من الأقدم إلى الأحدث، وتنتهي برسالة المستخدم الجديدة. يجب أن يكون `role` هو `user` أو `assistant`. تُتجاهل الرسائل بأي دور آخر، بما في ذلك `system`، وكذلك الرسائل التي يكون فيها `content` فارغًا. السؤال الذي تجيب عنه المنصة هو آخر رسالة `user`. حدود الحجم موضحة أدناه.
`session_id`	سلسلة نصية	لا	يُنشأ تلقائيًا	معرّف المحادثة: من 1 إلى 128 حرفًا من الحروف والأرقام و`_` و`.` و`:` و`-`. أرسل معرّفًا ثابتًا وكرره في كل تفاعل. عند إغفاله ينشئ الخادم معرّفًا للطلب ويعيده في حدثَي `phase` و`start`.
`location`	كائن `{ lat, lng }`	لا	لا يوجد	الموضع الذي ينظر إليه المستخدم، أي مركز الخريطة. يُستخدم لفهم «بالقرب من هنا».
`map_zoom`	رقم	لا	لا يوجد	مستوى تكبير الخريطة.
`lang`	سلسلة نصية	لا	`"en"`	لغة الإجابة بعلامة BCP 47 مثل `fr` أو `pt-BR`. بحد أقصى 35 حرفًا.
`layout`	سلسلة نصية	لا	لا يوجد	تخطيط viewer الذي تجري فيه المحادثة: `"guide"` ما دام viewer المضمَّن يعرض تخطيط الدليل؛ ويُحذف في غير ذلك. بحد أقصى 16 حرفًا.
`app_snapshot`	كائن	لا	لا يوجد	مقبول لكنه غير ضروري؛ يُفضّل تركه.
`auto_actions`	قيمة منطقية	لا	لا يوجد	مقبول لكنه غير ضروري؛ يُفضّل تركه.

تُقبل الحقول غير المعروفة ولكن تُتجاهل. لا يوجد حقل لتعليمات النظام أو الشخصية أو الأدوات أو سياق مخصص من جانبك؛ يحمل الطلب المحادثة والموقع واللغة فحسب.

لا يحتفظ الخادم بنص المحادثة نيابة عنك. أرسل التبادلات السابقة ضمن messages في كل مرة، مع session_id نفسه.

session_id خاص بمؤسستك. تُحفظ حالة المحادثة قصيرة الأجل لكل مؤسسة على حدة، لذلك لا تستطيع مؤسسة أخرى تقرأ المعرّف نفسه الوصول إلى محادثتك أو تعديلها. داخل مؤسستك، امنح محادثة كل مستخدم نهائي معرّفًا فريدًا.

حدود الطلبات

أي طلب يتجاوز هذه الحدود يُرفض بالرمز 422 قبل توليد الإجابة، ولا تُفرض عليه رسوم. يكون المتن {"detail": "<code>"}.

الحد	القيمة	الرمز
عدد الرسائل في `messages`	400	`too_many_messages`
طول `content` في الرسالة الواحدة	64,000 حرف	`message_too_long`
مجموع أطوال كل قيم `content`	200,000 حرف	`conversation_too_long`
`session_id`	من 1 إلى 128 حرفًا: حروف وأرقام و`_` و`.` و`:` و`-`	`invalid_session_id`
`lang`	35 حرفًا	`lang_too_long`
`layout`	16 حرفًا	`invalid_layout`

تُحتسب جميع الرسائل ضمن هذه الحدود، حتى الرسائل التي تُتجاهل. غالبًا ما تصل المحادثة الطويلة إلى حد الطول الإجمالي قبل حد عدد الرسائل؛ لذلك أرسل أحدث التفاعلات اللازمة واحذف الأقدم. راجع قراءة البث.

curl -N https://api.kaleidr.com/inference-api/b2b/v1/chat/control/stream \
  -H "Authorization: Bearer $KALEIDR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "session_id": "trip-42",
    "messages": [{"role": "user", "content": "Where is the Louvre, and what is next to it?"}],
    "location": {"lat": 48.8566, "lng": 2.3522},
    "map_zoom": 12,
    "lang": "en"
  }'

يعطّل الخيار -N التخزين المؤقت لمخرجات curl لتظهر الإطارات عند وصولها. وهذه استجابة مختصرة بقيم توضيحية:

event: phase
data: {"type": "phase", "phase": "thinking", "session_id": "trip-42"}

: keep-alive

event: start
data: {"type": "start", "session_id": "trip-42", "purpose": "control"}

data: {"text": "The [[Louvre Museum]] is on the right bank of the Seine"}

event: place
data: {"name": "Louvre Museum", "coordinates": {"lat": 48.8606, "lng": 2.3376}, "category": "museum"}

data: {"text": ", with the [[Tuileries Garden]] directly to its west."}

event: place
data: {"name": "Tuileries Garden", "coordinates": {"lat": 48.8635, "lng": 2.3275}, "category": "park"}

event: early_actions
data: {"type": "early_actions", "actions": [{"type": "map.fitBounds", "payload": {"coordinates": [[2.3376, 48.8606], [2.3275, 48.8635]], "padding": 50, "maxZoom": 15, "duration": 1000}}], "places_count": 2, "is_partial": true}

event: end
data: {"type": "end", "full_text": "The [[Louvre Museum]] is on the right bank of the Seine, with the [[Tuileries Garden]] directly to its west.", "places": [{"name": "Louvre Museum", "coordinates": {"lat": 48.8606, "lng": 2.3376}, "category": "museum"}, {"name": "Tuileries Garden", "coordinates": {"lat": 48.8635, "lng": 2.3275}, "category": "park"}], "actions": [], "question_type": "…", "response_time": 6.4, "total_tokens": 3120}

event: quota
data: {"type": "quota", "product": "b2b", "meter": "b2b.tokens", "tier": "pro", "used": 184223, "limit": 5000000, "reset_at": "2026-11-01T04:00:00+00:00", "period": "month"}

الحالة	الرمز	متى يحدث
413	`request_too_large`	جسم الطلب أكبر من 2 MiB.
422	خطأ التحقق	الجسم ليس JSON صالحًا أو يوجد حقل بنوع خاطئ.
422	`too_many_messages`, `message_too_long`, `conversation_too_long`, `invalid_session_id`, `lang_too_long`, `invalid_layout`	تجاوز الطلب حدود الطلبات.
429	`quota_exceeded`	لا تكفي أرصدة الذكاء الاصطناعي أو السقف الشهري لهذا المفتاح لتغطية الاستدعاء.

حدث quota الموضّح في المثال هو ما يتلقاه مفتاح الخادم. يكون الحدث أقصر في البث المقروء برمز جلسة؛ راجع حدث quota.

بعد بدء البث، يصل الفشل في صورة حدث error وليس رمز حالة HTTP. لبناء عميل، اتبع قراءة البث.

POST /chat/control/route

يُخطِّط مساراً بين إحداثيات متاحة لديك مسبقاً. لا يُطرح سؤال ولا يُولَّد نص.

المصادقة: مفتاح خادم أو رمز جلسة أو مفتاح قديم. النطاق: ai. التكلفة: لا شيء. ومع ذلك، يجب أن تتوفر سعة كافية ضمن رصيد AI لقبول الاستدعاء.

الحقل	النوع	مطلوب	الافتراضي	ملاحظات
`places`	مصفوفة كائنات	نعم، عنصران على الأقل	`[]`	كل عنصر بالشكل `{ lat, lng, name? }` ويحتوي على `lat` و`lng` رقميين في المستوى الأعلى من الكائن. يمكن استخدام `label` بدلًا من `name`. يُتجاهل العنصر الذي لا يتضمن `lat` و`lng` رقميين دون خطأ.
`profile`	سلسلة نصية	لا	`"driving"`	إحدى القيم `driving` أو `walking` أو `cycling` أو `transit`. وأي قيمة أخرى تعامل كـ`driving`.
`raw_query`	سلسلة نصية	لا	`"Show directions"`	الكلمات التي كتبها المستخدم، إن وجدت.

المكان الأول هو نقطة البداية، والمكان الأخير هو الوجهة.

تختلف بنية المكان عن بنية البث

يضع حدث place في بث الدردشة الموضع داخل كائن متداخل: { "coordinates": { "lat": …, "lng": … } }. لكن نقطة النهاية هذه تتطلب lat وlng مباشرة في المستوى الأعلى من الكائن. إذا مررت المكان كما ورد في البث دون تغيير فستحصل على جواب error لعدم وجود عناصر بإحداثيات صالحة.

curl -s https://api.kaleidr.com/inference-api/b2b/v1/chat/control/route \
  -H "Authorization: Bearer $KALEIDR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "places": [
      {"name": "Louvre Museum", "lat": 48.8606, "lng": 2.3376},
      {"name": "Tuileries Garden", "lat": 48.8635, "lng": 2.3275}
    ],
    "profile": "walking"
  }'

النجاح هو استجابة 200 تتضمن action (القيم للتوضيح):

{
  "action": {
    "type": "map.showRoute",
    "payload": {
      "id": "control-directions",
      "label": "Directions",
      "profile": "walking",
      "coordinates": [[2.3376, 48.8606], [2.3352, 48.8619], [2.3275, 48.8635]],
      "distance_m": 870,
      "duration_s": 640,
      "turn_by_turn": [{ "text": "Walk west on Rue de Rivoli." }],
      "attribution": {
        "text": "© OpenStreetMap contributors",
        "url": "https://www.openstreetmap.org/copyright",
        "license": "https://opendatacommons.org/licenses/odbl/"
      }
    }
  },
  "route": { "…": "the full planning result the action was built from" }
}

ارسم action.payload.coordinates وهي قائمة من أزواج [lng, lat]. تقاس distance_m بالأمتار وduration_s بالثواني. أينما عرضت المسار، اعرض attribution.text مع ربطه بـattribution.url.

عند استخدام profile: "transit" يتضمن payload.transit رحلة بوسيلة نقل واحدة: مشيًا ثم ركوبًا واحدًا ثم مشيًا. لا يحتوي المستوى الأعلى من البيانات على attribution، بل توجد بيانات اعتماد المشغّل في payload.transit.attribution. اعرضها بجوار الرحلة.

تُبلّغ نقطة النهاية هذه عن الفشل برمز HTTP 200

تعذّر تخطيط المسار ليس خطأ 4xx. تكون الاستجابة 200 مع سلسلة error وبدون action:

{ "error": "Route planning failed." }

يحدث ذلك عندما يتعذر على مخطط المسارات وصل الأماكن، أو عندما يفشل التخطيط لأي سبب آخر. إذا وُجد أقل من مكانين بإحداثيات صالحة، تظهر الرسالة At least two resolved places are required to build a route. وهي نص مصمم للعرض للمستخدم كما هو؛ لذلك افحص وجود حقل error بدلًا من مطابقة صياغته. وتُعاد النتيجة نفسها عند عدم توفر رحلة نقل عام مباشرة، مع وصف السبب وثلاثة حقول إضافية: reason وcovered وavailable.

افحص متن الاستجابة، لا رمز الحالة:

const res = await fetch(`${API}/chat/control/route`, { method: 'POST', headers, body });
if (!res.ok) throw new Error(`route request refused: ${res.status}`); // 401, 403, 422, 429
const data = await res.json();
if (data.error) {
  showMessage(data.error); // a 200 that is a failure
} else {
  drawLine(data.action.payload.coordinates);
}

تبقى حالات فشل المصادقة والنطاق والتحقق والحصة وحد المعدل استجابات عادية برموز 401 و403 و422 و429.

GET /retrieval/geocode/forward

يحوّل النص المكتوب إلى أماكن وعناوين شوارع مطابقة. وهو مصمم لحقل بحث أو حقلي الانطلاق/الوجهة.

المصادقة: مفتاح خادم أو رمز جلسة أو مفتاح قديم. النطاق: ai. التكلفة: رصيد AI، برسم ثابت لكل استدعاء، ويُفرض حتى إن كانت results فارغة.

المعامل	النوع	مطلوب	الافتراضي	ملاحظات
`q`	سلسلة نصية	نعم		من 1 إلى 200 حرف: اسم مكان، أو عنوان شارع برقم مبنى، أو `lat,lng` مكتوب مباشرة.
`near_lat`	رقم	لا		من −90 إلى 90؛ يقدّم النتائج الأقرب. يُستخدم فقط مع `near_lng`.
`near_lng`	رقم	لا		من −180 إلى 180؛ يُستخدم فقط مع `near_lat`.
`limit`	عدد صحيح	لا	`5`	من 1 إلى 20.
`mode`	سلسلة نصية	لا		وسيلة التنقل (`driving` أو `walking` أو `cycling` أو `transit`). في الرحلات القصيرة تُفضّل النتائج القريبة.

curl -s -G https://api.kaleidr.com/inference-api/b2b/v1/retrieval/geocode/forward \
  -H "Authorization: Bearer $KALEIDR_KEY" \
  --data-urlencode "q=20 W 34th St, New York" \
  --data-urlencode "limit=3"

{
  "query": "20 W 34th St, New York",
  "results": [
    {
      "lat": 40.7484,
      "lng": -73.9857,
      "display_name": "20 W 34th St, New York, NY 10001",
      "type": "address",
      "source": "…",
      "id": "…",
      "confidence": "exact",
      "attribution": {
        "dataset": "us/ny/city_of_new_york",
        "license": "…",
        "attribution": "Address data from the NYC Department of City Planning."
      }
    }
  ],
  "attribution": {
    "text": "Overture Maps Foundation, overturemaps.org",
    "licenses": [
      "https://cdla.dev/permissive-2-0/",
      "https://www.apache.org/licenses/LICENSE-2.0",
      "https://opensource.foursquare.com/places-notice-txt/",
      "https://docs.overturemaps.org/attribution/"
    ],
    "sources": [
      {
        "dataset": "us/ny/city_of_new_york",
        "license": "…",
        "attribution": "Address data from the NYC Department of City Planning."
      }
    ]
  }
}

تحتوي كل نتيجة على lat وlng وdisplay_name وtype وsource. وتظهر الحقول الأخرى عند انطباقها:

حقل النتيجة	المعنى
`id`	في عناوين الشوارع: معرّف Kaleidr لذلك المدخل. يظل ثابتًا بعد تحديث البيانات ويمكن حفظه ومقارنته.
`confidence`	كيفية تطابق النتيجة مع النص (الجدول أدناه). لا يوجد عند إدخال `lat,lng` مباشرة.
`approximate`, `method`, `matched_numbers`, `within_m`, `score`	تظهر للعناوين المقدّرة فقط (موضحة أدناه).
`attribution`	شروط مجموعة البيانات التي أتت منها النتيجة: `dataset` و`license`، وعند انطباقها `license_url` و`attribution` (الاعتماد المطلوب إظهاره) و`use_restriction`.

`confidence`	طبيعة النتيجة
`exact`	الرقم والشارع والمنطقة مطابقة لما أُدخل.
`fuzzy`	العنوان نفسه رغم خطأ في كتابة اسم الشارع.
`name_exact`	مكان يطابق اسمه الكلمات المكتوبة.
`locality`	المدينة أو المنطقة أو الحي المذكور في النص.
`interpolated`, `nearest`	تقدير لموقع رقم مبنى غير متوفر في البيانات.
`partial`	اسم شارع أطول يبدأ بالنص المدخل.
`name_partial`	اسم مكان يشارك بعض الكلمات المدخلة.
`ambiguous`	عنوان بلا منطقة مسماة أو نقطة مرجعية قريبة؛ أحد عدة احتمالات.

العناوين المقدّرة. عندما لا يكون رقم المبنى المدخل ضمن البيانات، توضع النتيجة على شارعه: بين أقرب رقمين معروفين على الجانب نفسه، أو عند أقرب رقم معروف، أو ضمن المقطع الذي يحتوي نطاق أرقامه على الرقم المطلوب. وتُعلَّم النتيجة بـapproximate: true وتتضمن:

الحقل	المعنى
`method`	`"interpolated"` بين رقمين معروفين، أو `"nearest"` عند أقرب رقم معروف، أو `"range"` على امتداد المقطع.
`matched_numbers`	الأرقام التي استُخدمت لتقدير الموقع.
`within_m`	المسافة بالمتر بين تلك الأرقام أو طول المقطع: أكبر خطأ محتمل إذا كانت أرقام الشارع مرتبة. لا يظهر مع `"nearest"`.
`score`	رقم من 0 إلى 1 يعبّر عن درجة الثقة. تعامل مع القيمة المنخفضة كموقع على مستوى الشارع، لا باب مبنى محدد.

المطابقة التامة لا تتضمن هذه الحقول أبداً.

الإسناد. أرفق attribution الموجود في المستوى الأعلى بالنتائج. يحتوي text على الاعتماد المطلوب عرضه، وlicenses على شروط المصادر التي يجب إبقاؤها مع البيانات. إذا تضمنت النتائج عناوين شوارع، يسرد attribution.sources مجموعات بيانات العناوين المستخدمة. تلتزم عند استخدام تلك النتائج بقيود use_restriction لكل مجموعة بيانات:

مجموعة البيانات	الاعتماد الذي يجب عرضه	قيود الاستخدام
`au/countrywide` (G-NAF)	G-NAF © Geoscape Australia مرخّص من كومنولث أستراليا بموجب Open Geo-coded National Address File (G-NAF) End User Licence Agreement.	لا يجوز إنشاء عنوان أو مجموعة عناوين لإرسال البريد إلا إذا جرى التحقق من قابلية كل عنوان لاستقبال البريد من مصدر غير G-NAF؛ ويجب أن يتوافق الاستخدام مع Australian Privacy Principles.
`ca/countrywide` (Statistics Canada)	مقتبس من Statistics Canada, National Address Register, 2025-07-29. لا يعني ذلك أن Statistics Canada تؤيد هذا المنتج.	لا يجوز استخدامها لتحديد هوية أي شخص أو نشاط تجاري أو مؤسسة، أو للإيحاء بموافقة Statistics Canada.
`us/ny/city_of_new_york`	بيانات العناوين من NYC Department of City Planning.	لا توجد.
`us/ma/statewide` (MassGIS)	MassGIS (Bureau of Geographic Information), Commonwealth of Massachusetts EOTSS	لا توجد (ملكية عامة).

عدم العثور على تطابق والإخفاق الداخلي يبدوان بالشكل نفسه. عند عدم وجود نتائج، تُعاد استجابة 200 مع "results": []. وينطبق الأمر نفسه على البحث الذي يفشل داخليًا، لكن لا يُفرض رسم في حالة الفشل الداخلي. تعامل مع القائمة الفارغة على أنها «لا شيء للعرض»، لا خطأ.

الحالة	الرمز	متى يحدث
422	خطأ التحقق	`q` مفقود أو فارغ أو أطول من 200 حرف، أو `limit` أو أحد الإحداثيات خارج النطاق المسموح.
429	`quota_exceeded`	أرصدة الذكاء الاصطناعي غير كافية لتغطية الاستدعاء.

POST /spot

توضح هذه النقطة ما يوجد عند موضع محدد: المكان الذي نقره المستخدم وأقرب عنوان شارع والمناطق التي تحتوي النقطة. ويُرفق بكل قيمة الإسناد الذي يجب عرضه معها. ويمكن عند الطلب إضافة وصف المكان وصوره.

المصادقة: مفتاح خادم أو رمز جلسة أو مفتاح قديم. النطاق: ai. التكلفة: رصيد AI برسم ثابت لكل استدعاء، يحدده الجزء الأعلى تكلفة من العناصر المطلوبة في want ويُفرض حتى لو لم يُعثر على شيء: تكلف content أو photos رسم /retrieval/poi/enrich عندما يُجلب المحتوى لهذا الاستدعاء، وإلا فإن address يكلف رسم /retrieval/geocode/forward. والمحتوى الذي جُلب لطلب سابق لا يكلف شيئًا، لذا فإن مثل هذا الاستدعاء إذا طلب address أيضًا يُفرض عليه رسم الترميز الجغرافي. والاستدعاء الذي يطلب فقط entities أو regions أو boundaries أو tenants مجاني. تتضمن want الافتراضية address، لذا فإن حذف want يؤدي إلى فرض رسم الترميز الجغرافي.

الحقل	النوع	مطلوب	الافتراضي	ملاحظات
`lat`	رقم	نعم		من −90 إلى 90. خط عرض النقطة.
`lng`	رقم	نعم		من −180 إلى 180. خط الطول.
`zoom`	رقم	لا		من 0 إلى 24. مستوى تكبير الخريطة.
`hint`	كائن	لا		العنصر الذي نقره المستخدم (أدناه).
`want`	مصفوفة سلاسل نصية	لا	`["entities", "address", "regions"]`	أجزاء النتيجة المطلوب إرجاعها (أدناه).
`lang`	سلسلة نصية	لا	`"en"`	لغة `content`. بحد أقصى 16 حرفًا.

تحدد النقطة النتيجة، ولا يفعل التلميح سوى اختيار العنصر. يختار التلميح من العناصر الموجودة عند النقطة، ولا يغيّر موقع النتيجة أبدًا. فلا يُعاد مكان يبعد أكثر من 75 مترًا عن lat وlng مهما كان الاسم الوارد في التلميح.

حقل `hint`	ملاحظات
`id`	معرّف المكان لدى Kaleidr: الجزء من مرجع `poi:` الذي يأتي بعد النقطتين الرأسيتين.
`name`	اسم المكان كما يظهر في تسمية الخريطة. بحد أقصى 200 حرف. يُطابَق تطابقًا تامًا مع الأماكن الموجودة عند النقطة، ويُستخدم لتسمية المكان في `content`. وإذا كانت قيمة `region_level` هي `county` أو `state` أو `country`، فإنه يختار أيضًا المنطقة في ذلك المستوى التي يطابق اسمها الاسم المحدد، دون مراعاة حالة الأحرف أو علامات التشكيل، من بين المناطق الموجودة عند النقطة (وبالنسبة إلى الولاية أو الدولة، يشمل ذلك أيضًا المناطق الواقعة على بُعد يصل إلى 5 km من النقطة). وإذا لم يطابق الاسم أيًا منها، فلن يتغير شيء.
`category`	فئة المكان. بحد أقصى 100 حرف. تُستخدم في `content`.
`region_level`	عند طلب `boundaries`، يُرجَع مخطط حدود المنطقة في هذا المستوى فقط (`city` أو `county` أو `state` أو `country`)؛ وبدونه تُرجَع حدود جميع المناطق. وعند تحديد `name`، تكون المنطقة في هذا المستوى ضمن كلٍّ من `regions` و`boundaries` هي المنطقة التي يختارها الاسم.
`layer`, `wiki_title`, `ta_location_id`, `yelp_business_id`, `data_source`	حقول مقبولة. تستخدمها تطبيقات Kaleidr الخاصة؛ اتركها خارج الطلب.

قيمة `want`	ما تضيفه
`entities`	المكان الذي نُقر عليه، إذا كان `hint` يسمّي مكانًا موجودًا عند النقطة.
`address`	أقرب عنوان شارع.
`regions`	المدينة والمقاطعة (في الولايات المتحدة فقط)، والولاية والدولة التي تقع النقطة ضمنها. وإذا كانت النقطة في البحر على بُعد يصل إلى 5 km من الساحل، فتُرجَع أقرب ولاية ودولة.
`boundaries`	`regions` مع مخطط حدود كل منطقة (مستوى واحد فقط عند تحديد `hint.region_level`).
`content`	المحتوى الوصفي للمكان: ملخص وصور ورابط. يتطلب اسم مكان، إما من المكان الذي نُقر عليه أو من `hint.name`.
`photos`	صور المكان فقط. تكلفتها مماثلة لتكلفة `content`.
`tenants`	الأماكن المسماة القريبة من النقطة، بدءًا بالأقرب: الأنشطة التجارية الموجودة في مبنى. يحتفظ تطبيقك بالأماكن الواقعة داخل المساحة التي يعرضها المبنى على الخريطة.

curl -s https://api.kaleidr.com/inference-api/b2b/v1/spot \
  -H "Authorization: Bearer $KALEIDR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lat": 40.7484,
    "lng": -73.9857,
    "zoom": 17,
    "hint": {"name": "Empire State Building", "category": "landmark"},
    "want": ["entities", "address", "regions"]
  }'

استجابة مختصرة بقيم توضيحية:

{
  "spot": { "lat": 40.7484, "lng": -73.9857, "zoom": 17 },
  "entities": [
    {
      "ref": "poi:3f1c2a9e-…",
      "kind": "poi",
      "role": "clicked",
      "name": { "value": "Empire State Building", "license": "CDLA-Permissive-2.0", "attr": "a1" },
      "at": { "lat": 40.74844, "lng": -73.98566 },
      "facts": {
        "category": { "value": "landmark_and_historical_building", "license": "CDLA-Permissive-2.0", "attr": "a1" },
        "website": { "value": "https://www.esbnyc.com", "license": "CDLA-Permissive-2.0", "attr": "a1" }
      }
    }
  ],
  "address": {
    "ref": "address:ka1…",
    "line": { "value": "20 W 34th St, New York, NY 10001", "license": "CDLA-Permissive-2.0", "attr": "a2" },
    "at": { "lat": 40.7484, "lng": -73.9857 }
  },
  "regions": [
    {
      "ref": "region:tiger:3651000",
      "kind": "region",
      "level": "city",
      "name": { "value": "New York", "license": "LicenseRef-Public-Domain", "attr": "a3" },
      "label": { "lat": 40.6976, "lng": -73.9795 }
    },
    {
      "ref": "region:tiger:36",
      "kind": "region",
      "level": "state",
      "name": { "value": "New York", "license": "LicenseRef-Public-Domain", "attr": "a3" },
      "label": { "lat": 42.7559, "lng": -75.8099 }
    }
  ],
  "attributions": {
    "a1": { "text": "© Overture Maps Foundation", "license": "CDLA-Permissive-2.0" },
    "a2": { "text": "Address data from the NYC Department of City Planning.", "license": "CDLA-Permissive-2.0" },
    "a3": { "text": "U.S. Census Bureau, TIGER/Line", "license": "LicenseRef-Public-Domain" }
  },
  "withheld": ["building_facts"]
}

الحقل	المعنى
`spot`	النقطة التي أرسلتها: `{ lat, lng, zoom }`.
`entities`	المكان الذي نُقر، ثم المستأجرون إن طلبتهم، أو قائمة فارغة. يتضمن كل عنصر `ref` و`kind` (القيمة `"poi"` للمكان المنقور و`"tenant"` للمستأجر) و`role` (`"clicked"` أو `"inside"`) و`name` و`at` (موضع المكان `{ lat, lng }`) و`facts` (حقل `category` و`website` للمكان المنقور إن كان معروفًا). يكون `ref` الخاص بالمستأجر مرجع `poi:` أيضًا، ولذلك يمكن بث نبذته. تجاهل أي عنصر من `kind` غير معروف.
`address`	أقرب عنوان شارع أو `null`: `{ ref, line, at }`.
`regions`	المناطق التي تحتوي النقطة، من الأصغر إلى الأكبر. يتضمن كل عنصر `ref` و`kind` (`"region"`) و`level` (`city` أو `county` أو `state` أو `country`) و`name` و`label`، وهو موضع وضع اسم المنطقة `{ lat, lng }` أو `null`. ومع `want: ["boundaries"]` يتضمن كل عنصر أيضًا `geometry`، أي حدود المنطقة بهندسة GeoJSON.
`content`	يظهر عندما يتضمن `want` القيمة `content` أو `photos` ويكون اسم المكان معروفًا ويسمح بإرجاع المحتوى. وهو الكائن الذي تعيده `/retrieval/poi/enrich` (انظر الحقول)، أو `{ photos, source, cached }` عند طلب `photos` وحدها، مع إضافة `license` و`attr` مثل القيم الأخرى. وقد تكون القيمة `null` عند تعذر جلب المحتوى.
`attributions`	بيانات الاعتماد المستخدمة في الاستجابة: `{ text, license }` مفهرسة بقيمة `attr` لكل عنصر.
`withheld`	أنواع المعلومات التي حُجبت لأن API لا يستطيع إرجاعها. وتكون قائمة فارغة إذا لم يُحجب شيء.

يشير ref إلى العنصر الذي يمكن وصفه بواسطة /spot/overview/stream: poi:<id> للمكان، وaddress:<id> للعنوان، وregion:<source>:<id> للمنطقة (حيث تكون <source> إحدى القيم tiger أو nuts أو ne). تستخدم تطبيقات Kaleidr أيضًا building:<id>، لكن API لا يعيده. تعامل مع المرجع كسلسلة معتمة لا تفسّر بنيتها.

أظهر إسناد المصدر لكل قيمة

كل قيمة مأخوذة من مجموعة بيانات تأتي في كائن { value, license, attr } يتضمن البيانات وترخيصها ومفتاحًا ضمن attributions. أينما عرضت القيمة، اعرض معها attributions[attr].text بجوارها أو في مساحة اعتمادات يمكن الوصول إليها. قد تجمع استجابة واحدة مصادر مختلفة، لذا لا يكفي اعتماد واحد للاستجابة كلها. احتفظ بـlicense والاعتماد مع أي قيمة تخزنها أو تمررها.

يتطلب content إسنادًا بالطريقة نفسها عبر قيمة attr الخاصة به. ولا يجوز عرض قيمة تحمل live_only: true إلا للمستخدم الحالي، ولا يجوز تخزينها أو نقلها إلى غيره.

راجع تراخيص البيانات للاطلاع على متطلبات كل ترخيص.

ما لا تُرجعه واجهة API

تعرض تطبيقات Kaleidr نفسها معلومات عن نقطة أكثر مما تعيده واجهة API، لأن بعض البيانات غير مرخصة للاستخدام على مواقع أخرى:

القيم الخاضعة لترخيص ODbL والمشتقة من OpenStreetMap: خصائص المبنى مثل عدد الطوابق والارتفاع والتصنيف. ولا تتوفر نبذة المبنى أيضًا.
نتائج مزودي الخدمات الخارجيين: عمليات البحث عن العناوين من خدمات الترميز الجغرافي، والتقييمات والمراجعات والصور من Yelp وTripadvisor.

يساعد withheld على التمييز بين «لا توجد معلومات معروفة هنا» و«المعلومات غير متاحة عبر API». وهو يسرد أنواع المعلومات فقط وليس القيم: مثل building_facts إذا كانت النقطة داخل مبنى، أو content عندما يكون محتوى المكان الوحيد غير قابل للإرجاع. وتوضح إدخالات أخرى أجزاء الاستجابة المحجوبة بالطريقة نفسها.

الأخطاء المحتملة في POST /spot:

الحالة	الرمز	متى يحدث
413	`request_too_large`	جسم الطلب أكبر من 2 MiB.
422	خطأ التحقق	`lat` أو `lng` مفقود أو خارج النطاق، أو `zoom` خارج 0 إلى 24، أو توجد قيمة مجهولة في `want`، أو حقل طويل جدًا أو بصيغة غير صحيحة.
429	`quota_exceeded`	لا تكفي أرصدة الذكاء الاصطناعي لتغطية الاستدعاء.

يعود أي جزء تعذر البحث عنه فارغاً (null أو []). وتظل المكالمة محسوبة التكلفة.

POST /spot/overview/stream

يبث وصفاً كتابياً قصيراً لعنصر أعادته /spot، ويُحدَّد العنصر بواسطة ref الخاص به.

المصادقة: مفتاح خادم أو رمز جلسة أو مفتاح قديم. النطاق: ai. التكلفة: رصيد AI بحسب الرموز المستخدمة. يُكتب كل وصف خاصاً بطلبه. الاستجابة: text/event-stream: عادةً إطار place يحمل الاسم الكامل للمكان، مثل "Springfield, Ohio, United States of America"، ثم إطارات ملخص مكان؛ راجع تدفقات الملخصات والأزرار.

الحقل	النوع	مطلوب	الافتراضي	ملاحظات
`ref`	سلسلة نصية	نعم		قيمة `ref` من استجابة `/spot` بحد أقصى 128 حرفًا، أو `place:` (أدناه).
`lat`, `lng`	رقم	نعم		النقطة التي أرسلتها إلى `/spot`.
`lang`	سلسلة نصية	لا	`"en"`	لغة كتابة النبذة، بحد أقصى 16 حرفًا.
`hint`	كائن	عند استخدام `place:` فقط		`{ name, category? }`: التسمية المطلوب وصفها.

`ref`	موضوع النبذة
`poi:<id>`	المكان.
`region:<source>:<id>`	المنطقة.
`place:`	تسمية لمكان لا يحتفظ Kaleidr بسجل له، مثل مكان لم يعثر له `/spot` على كيان. أرسل اسمه في `hint.name`.
`address:<id>`, `building:<id>`	غير متاح عبر API: يرسل البث إطار `error` واحدًا. راجع ما لا يعيده API.

يُعاد البحث عن العنصر عند lat وlng، لذلك لا يُعد أي وصف في الطلب حقيقة مؤكدة عنه. يؤدي مرجع poi: الذي يبعد أكثر من 75 مترًا عن النقطة، أو مرجع region: لمنطقة لا تحتوي النقطة، أو place: دون hint.name، إلى إطار error أيضًا.

curl -N https://api.kaleidr.com/inference-api/b2b/v1/spot/overview/stream \
  -H "Authorization: Bearer $KALEIDR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ref": "poi:3f1c2a9e-…", "lat": 40.7484, "lng": -73.9857, "lang": "en"}'

عندما يتعذر وصف مرجع، تُرسل هذه الإطارة بدلاً من الملخص. وتتضمن ref دون partial_text:

event: error
data: {"type": "error", "message": "Nothing to describe here.", "ref": "address:ka1…"}

الحالة	الرمز	متى يحدث
413	`request_too_large`	جسم الطلب أكبر من 2 MiB.
422	خطأ التحقق	`ref` لا يطابق الأشكال المذكورة، أو `lat` أو `lng` مفقود أو خارج النطاق، أو `lang` يتجاوز 16 حرفًا.
429	`quota_exceeded`	أرصدة الذكاء الاصطناعي غير كافية.

الانتقال من نقاط النهاية المهملة

تُعد GET /retrieval/poi/enrich وPOST /chat/summary/stream نقطتي نهاية مهملتين. ستستمران في الإجابة كالسابق حتى 2027-01-15، وقد تُزالان في أي وقت بعد ذلك. تُبيّن ترويسات كل استجابة هذه الحالة؛ ويشير Deprecation إلى تاريخ بدء الإهمال، 2026-10-16، بصيغة وقت Unix:

Deprecation: @1792108800
Sunset: Fri, 15 Jan 2027 00:00:00 GMT
Link: </inference-api/b2b/v1/spot>; rel="successor-version"

تشير ترويسة Link في /chat/summary/stream إلى /inference-api/b2b/v1/spot/overview/stream. سجّل ترويسة Sunset لتحديد المكالمات التي لا تزال تستخدمها.

من GET /retrieval/poi/enrich إلى POST /spot:

قبل	بعد
`lat`, `lon` (في الاستعلام)	`lat`, `lng` (في الجسم). انتبه إلى الاسم.
`name`, `category`	`hint.name`, `hint.category`
`lang`	`lang`، حتى 16 حرفًا
بحث كامل	`want: ["content"]`
`photos_only=true`	`want: ["photos"]`
`radius`, `dataSource`, `ta_location_id`, `regionLevel`	اتركها.
جسم الاستجابة	`content`: الكائن نفسه مع إضافة `live_only`
`attribution`	`content.attribution`

التكلفة هي نفسها أو أقل: لا يفرض /spot رسمًا على المحتوى الذي جُلب لطلب سابق. يُحتسب رسم البحث وفق أغلى عنصر في want، لذا عندما يُجلب المحتوى للاستدعاء، فإن إضافة entities أو address أو regions تعيدها في الاستدعاء نفسه بلا تكلفة إضافية.

من POST /chat/summary/stream إلى POST /spot/overview/stream:

قبل	بعد
المكان: `location`, `building_properties.name`, `.category`	استدعِ `/spot` مع النقطة و`hint: { name, category }`، ثم ابث نبذة `ref` الخاصة بالمكان ضمن `entities` مع `lat` و`lng` نفسيهما. إذا كانت `entities` فارغة فأرسل `ref: "place:"` مع `hint` نفسه.
`building_properties.pid`	`ref: "poi:<id>"`
`lang`	`lang`، حتى 16 حرفًا
`max_tokens`	اتركه.
المبنى: `type: "building"` وحقوله	لا يوجد بديل. نبذة المبنى غير متاحة عبر API.
الإطارات	إطارات نبذة المكان، بعد إطار `place` جديد يسمّي المكان.

GET /retrieval/poi/enrich

نقطة نهاية مهملة

هذه النقطة مهملة وقد تُزال بعد 2027-01-15. استخدم POST /spot مع want: ["content"]. راجع الانتقال من نقاط النهاية المهملة.

يعيد محتوى وصفياً لمكان واحد: عنواناً وملخصاً وصوراً ورابطاً.

المصادقة: مفتاح خادم أو رمز جلسة أو مفتاح قديم. النطاق: ai. التكلفة: رصيد AI، برسم ثابت لكل استدعاء. يُفرض الرسم سواء عُثر على محتوى أم لا.

المعامل	النوع	مطلوب	الافتراضي	ملاحظات
`lat`	رقم	نعم		خط عرض المكان.
`lon`	رقم	نعم		خط طول المكان. الاسم هو `lon` وليس `lng`.
`name`	سلسلة نصية	لا		اسم المكان. يُنصح به لأن الإحداثيات وحدها غالبًا لا تكفي للمطابقة.
`category`	سلسلة نصية	لا		تصنيف المكان كما ورد في حدث `place`.
`radius`	عدد صحيح	لا	`250`	نصف قطر البحث حول النقطة بالأمتار.
`lang`	سلسلة نصية	لا	`"en"`	لغة المحتوى.
`photos_only`	قيمة منطقية	لا	`false`	إعادة الصور فقط (استجابة أصغر، أدناه).
`dataSource`, `ta_location_id`, `regionLevel`	سلسلة نصية	لا		تُقبل كتلميحات خاصة بتطبيقات Kaleidr؛ اتركها.

curl -s -G https://api.kaleidr.com/inference-api/b2b/v1/retrieval/poi/enrich \
  -H "Authorization: Bearer $KALEIDR_KEY" \
  --data-urlencode "lat=48.8606" \
  --data-urlencode "lon=2.3376" \
  --data-urlencode "name=Louvre Museum" \
  --data-urlencode "category=museum"

{
  "source": "wikipedia",
  "found": true,
  "title": "Louvre",
  "photos": ["https://upload.wikimedia.org/…/Louvre_Museum.jpg"],
  "summary": "The Louvre is a national art museum in Paris, France…",
  "rating": null,
  "phone": null,
  "hours": null,
  "reviews": [],
  "url": "https://en.wikipedia.org/wiki/Louvre",
  "attribution": ["Wikipedia"]
}

الحقل	النوع	المعنى
`source`	سلسلة نصية	مصدر المحتوى. وتعني `"omitted"` أن المحتوى موجود لكنه لا يجوز إرجاعه عبر API (أدناه).
`found`	قيمة منطقية	تكون `false` عند عدم العثور على شيء، وتكون الحقول الأخرى فارغة حينها.
`title`	سلسلة نصية	عنوان المكان في المصدر.
`summary`	سلسلة نصية أو null	وصف قصير.
`photos`	مصفوفة عناوين URL	قد تكون فارغة.
`url`	سلسلة نصية أو null	رابط صفحة المصدر.
`attribution`	مصفوفة سلاسل	أسماء المصادر التي يجب ذكرها، مثل `["Wikipedia"]`. اعرضها مع المحتوى.
`rating`, `phone`, `hours`, `reviews`		قد تكون `null` أو فارغة. لا تُعاد التقييمات والمراجعات من مزودين ذوي تراخيص خاصة عبر API.
`unverified`	قيمة منطقية	حقل اختياري. تشير `true` إلى أن مطابقة المكان غير مؤكدة.

عند استخدام photos_only=true، تكون الاستجابة { "photos": […], "source": "…", "cached": false }.

المحتوى المحجوب. بعض المحتوى مرخّص لتطبيقات Kaleidr فقط. إذا كان هذا هو المحتوى الوحيد المتاح لمكان ما، تكون الاستجابة 200 مع "source": "omitted" و"found": false ودون محتوى. وتظل تكلفة الاستدعاء مستحقة. راجع تراخيص البيانات.

الحالة	الرمز	متى يحدث
422	خطأ التحقق	`lat` أو `lon` مفقود أو ليس رقمًا.
429	`quota_exceeded`	أرصدة الذكاء الاصطناعي غير كافية.
500	`An internal error occurred. Please try again.`	فشل البحث. ويظل الاستدعاء مدفوعًا.

POST /chat/summary/stream

نقطة نهاية مهملة

هذه النقطة مهملة ويمكن حذفها بعد 2027-01-15. استخدم POST /spot/overview/stream. لا يوجد بديل لملخص المبنى. راجع الانتقال من نقاط النهاية المهملة.

يبث ملخصاً كتابياً قصيراً لمكان واحد أو مبنى واحد، وهو ما يدعم بطاقة المكان في Kaleidr Chat.

المصادقة: مفتاح خادم أو رمز جلسة أو مفتاح قديم. النطاق: ai. التكلفة: رصيد AI بحسب الرموز المستخدمة. يُكتب كل ملخص خصيصاً لطلبه. الاستجابة: text/event-stream. راجع تدفقات الملخصات والأزرار.

يحدد حقل type في المتن نوع الملخص.

مبنى ("type": "building"):

الحقل	النوع	مطلوب	ملاحظات
`type`	سلسلة نصية	نعم	`"building"`.
`address`	سلسلة نصية	نعم	العنوان الكامل للمبنى، حتى 500 حرف.
`lat`, `lng`	رقم	لا	موضع المبنى.
`building_levels`	عدد صحيح	لا	عدد الطوابق، إن عُرف.
`building_height_m`	رقم	لا	ارتفاع المبنى بالأمتار، إن عُرف.
`tenant_names`	مصفوفة سلاسل نصية	لا	أسماء الأنشطة التجارية في المبنى، حتى 100 اسم لا يزيد كل منها على 200 حرف.
`poi_count`	عدد صحيح	لا	عدد الأماكن داخل المبنى.
`lang`	سلسلة نصية	لا	القيمة الافتراضية `"en"`، حتى 35 حرفًا.

curl -N https://api.kaleidr.com/inference-api/b2b/v1/chat/summary/stream \
  -H "Authorization: Bearer $KALEIDR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "building", "address": "20 W 34th St, New York, NY 10001", "lat": 40.7484, "lng": -73.9857}'

event: start
data: {"type": "start", "address": "20 W 34th St, New York, NY 10001"}

data: {"text": "A landmark office tower in Midtown Manhattan"}

event: end
data: {"type": "end", "full_text": "A landmark office tower in Midtown Manhattan…", "parsed": {"…": "…"}, "total_tokens": 910}

event: quota
data: {"type": "quota", "product": "b2b", "meter": "b2b.tokens", "tier": "pro", "used": 185133, "limit": 5000000, "reset_at": "2026-11-01T04:00:00+00:00", "period": "month"}

المكان (عند غياب type أو مساواته لـ"poi"). يقبل الجسم location (كائن { lat, lng }) وbuilding_properties (كائنًا) وlang وmax_tokens (عددًا صحيحًا). صُمم هذا الشكل للوحة Kaleidr الخاصة، ومعاني حقوله ليست جزءًا من عقد API المنشور بعد. يُفضّل استخدام /chat/control/stream لطرح سؤال عن مكان من شيفرتك.

حقل المكان	الحد
`building_properties.name`, `.type`, `.category`, `.poi_type`	200 حرف لكل منها
`building_properties.pid`	128 حرفًا
كل حقل نصي في `building_properties.event`	4,000 حرف
`lang`	35 حرفًا
`max_tokens`	تُخفض أي قيمة أكبر من الافتراضي لنقطة النهاية إلى القيمة الافتراضية. لا يمكنك طلب ملخص أطول.

يقرأ كلا الشكلين الحقول المذكورة هنا فقط. تُتجاهل أي حقول إضافية في الجسم. ويُرفض الحقل الذي يتجاوز حد طوله برمز 422 field_too_long قبل إنشاء أي ملخص.

الحالة	الرمز	متى يحدث
413	`request_too_large`	جسم الطلب أكبر من 2 MiB.
422	`field_too_long`	أحد الحقول أطول من المسموح، أو تتضمن `tenant_names` أكثر من 100 عنصر. يكون الجسم `{"detail": "field_too_long"}`.
500	`Summary stream error`	تعذر قراءة الجسم أو لا يحتوي طلب المبنى على `address`. أي جسم غير صالح آخر يرجع 500 بدلًا من 422.
429	`quota_exceeded`	أرصدة الذكاء الاصطناعي غير كافية.

POST /chat/button/stream

يبث الإجابة عن سؤال واحد بشأن مكان واحد، مثل «ما ساعات العمل؟». وهو أساس أزرار الأسئلة في بطاقة المكان داخل Kaleidr Chat. لا يحمل سياق محادثة؛ فكل استدعاء مستقل.

المصادقة: مفتاح خادم أو رمز جلسة أو مفتاح قديم. النطاق: ai. التكلفة: رصيد AI بحسب عدد الرموز المستخدمة. الاستجابة: text/event-stream. راجع تدفقات الملخصات والأزرار.

الحقل	النوع	مطلوب	الافتراضي	ملاحظات
`query`	سلسلة نصية	نعم		السؤال، حتى 4,000 حرف.
`place_name`	سلسلة نصية	لا		اسم المكان موضوع السؤال، حتى 200 حرف.
`place_type`	سلسلة نصية	لا		تصنيفه، حتى 200 حرف.
`address`	سلسلة نصية	لا		عنوانه، حتى 500 حرف.
`location`	كائن `{ lat, lng }`	لا		موضعه.
`lang`	سلسلة نصية	لا	`"en"`	لغة الإجابة، حتى 35 حرفًا.
`description`	سلسلة نصية	لا		وصف للمكان لديك مسبقًا، حتى 4,000 حرف.
`website`	سلسلة نصية	لا		موقع المكان الإلكتروني إن عُرف، حتى 2,048 حرفًا.
`stores_preview`	مصفوفة كائنات `{ name }`	لا		الأنشطة التجارية في المكان إن كانت معروفة، حتى 50 عنصرًا و200 حرف لكل `name`. تُتجاهل بقية حقول العنصر.
`button_id`, `session_id`, `place_id`	سلسلة نصية	لا		معرّفاتك لربط الطلبات ببعضها، حتى 128 حرفًا لكل منها.

تُتجاهل الحقول غير الواردة في هذا الجدول. ويُرفض أي حقل يتجاوز طوله المسموح برمز 422 field_too_long قبل إنتاج الإجابة.

curl -N https://api.kaleidr.com/inference-api/b2b/v1/chat/button/stream \
  -H "Authorization: Bearer $KALEIDR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is this place known for?",
    "place_name": "Louvre Museum",
    "place_type": "museum",
    "location": {"lat": 48.8606, "lng": 2.3376}
  }'

event: start
data: {"type": "start", "query_type": "…"}

data: {"text": "The Louvre is best known for"}

event: end
data: {"type": "end", "full_text": "The Louvre is best known for…", "reply": "The Louvre is best known for…", "query_type": "…", "first_token_ms": 820, "total_ms": 3900, "total_tokens": 640}

الحالة	الرمز	متى يحدث
413	`request_too_large`	جسم الطلب أكبر من 2 MiB.
422	`field_too_long`	الحقل أطول من حده أو تحتوي `stores_preview` على أكثر من 50 عنصرًا. يكون الجسم `{"detail": "field_too_long"}`.
500	`Button chat stream error`	تعذر قراءة الجسم أو لا يحتوي على `query`. أي جسم غير صالح آخر يرجع 500 بدلًا من 422.
429	`quota_exceeded`	أرصدة الذكاء الاصطناعي غير كافية.

POST /design/analyze

يفحص الأعمدة وعينة من الجدول ويوصي بكيفية تمثيلها على الخريطة.

لا يستدعي تضمين Editor نقاط نهاية التصميم؛ فهي واجهة REST مخصصة لأدواتك.

المصادقة: مفتاح خادم أو رمز جلسة أو مفتاح قديم. النطاق: design. التكلفة: رصيد AI، برسم ثابت لكل استدعاء ناجح. لا تُفرض رسوم على الاستدعاء الفاشل.

الحقل	النوع	مطلوب	ملاحظات
`columns`	مصفوفة سلاسل نصية	نعم	من 1 إلى 256 اسم عمود، ويجب أن تكون جميعها فريدة.
`sampleRows`	مصفوفة كائنات	لا	حتى 1,000 صف، كل صف كائن مفهرس بأسماء الأعمدة.
`datasetName`	سلسلة نصية	لا	حتى 512 حرفًا.
`rowCount`	عدد صحيح	لا	إجمالي صفوف الجدول الكامل، صفر أو أكثر.
`userGoal`	سلسلة نصية	لا	حتى 1,000 حرف، تصف ما يجب أن تعرضه الخريطة.
`supportedStyles`	مصفوفة سلاسل نصية	لا	معرّفات الأنماط المتاحة للاختيار، بحروف صغيرة وكلمات تفصلها شرطات.

أسماء الحقول مكتوبة بصيغة camelCase. يتم تجاهل الحقول غير المعروفة.

curl -s https://api.kaleidr.com/inference-api/b2b/v1/design/analyze \
  -H "Authorization: Bearer $KALEIDR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "datasetName": "stores.csv",
    "columns": ["name", "lat", "lng", "revenue"],
    "sampleRows": [
      {"name": "Downtown", "lat": 40.7128, "lng": -74.0060, "revenue": 120000},
      {"name": "Uptown", "lat": 40.7831, "lng": -73.9712, "revenue": 86000}
    ],
    "rowCount": 240,
    "userGoal": "Show which stores earn the most"
  }'

{
  "datasetProfile": { "…": "what was detected in each column" },
  "designPlan": { "…": "the recommended style, theme and reasoning" },
  "issues": [],
  "recommendation": { "…": "…" },
  "suggestedConfig": { "…": "…" },
  "explanation": "…"
}

اقرأ designPlan؛ فقد تكون قيمته null. أما recommendation وsuggestedConfig وexplanation فهي حقول قديمة أبقي عليها للتوافق ومن المقرر إزالتها؛ فلا تعتمد عليها في بناء التطبيق. يسرد issues المشكلات المكتشفة في البيانات.

الحالة	الرمز	متى يحدث
413	`request_too_large`	جسم الطلب أكبر من 5 MiB. وينطبق الحد نفسه على `/design/apply-direct`.
422	خطأ التحقق	`columns` مفقود أو فارغ أو طويل جدًا أو يحوي تكرارات، أو تجاوز أحد الحدود المذكورة.
429	`quota_exceeded`	أرصدة الذكاء الاصطناعي غير كافية.
500	`map_design_analyze_failed`	فشل التحليل، دون فرض رسوم.

POST /design/apply-direct

يبني طبقة خريطة من جدول ونمط مختار دون إجراء تحليل.

المصادقة: مفتاح خادم أو رمز جلسة أو مفتاح قديم. النطاق: design. التكلفة: لا شيء.

الحقل	النوع	مطلوب	ملاحظات
`style`	سلسلة نصية	نعم	معرّف نمط من 1 إلى 64 حرفًا. تظهر المعرّفات في `/design/styles`.
`config`	كائن	نعم	يحتوي على `location` و`metric` و`visual`. يجب تحديد `location.mode` (إما `"coordinates"` أو `"region"`) و`visual.layerName`؛ أما الحقول الفرعية الأخرى فلم تُوثق بعد.
`table`	كائن	نعم	`{ fileName?, columns[], rows[] }`. كل صف كائن يربط أسماء الأعمدة بالقيم، ويجب أن تكون كل قيمة سلسلة JSON: أرسل `"120000"` لا `120000`. يُرفض الصف الذي يتضمن رقمًا أو `null` برمز 422.
`layerLabel`	سلسلة نصية	نعم	الاسم المعروض للطبقة، من 1 إلى 512 حرفًا.
`themePackId`	سلسلة نصية	لا	معرّف سمة من `/design/themes`. تُتجاهل المعرّفات غير المعروفة.
`datasetSource`	كائن	لا	`{ label, url? }`: ناشر البيانات للاعتراف بالمصدر في الطبقة.
`datasetId`	سلسلة نصية	لا	حتى 128 حرفًا، تُستخدم معرّفًا للطبقة.
`year`	عدد صحيح	لا	من 1800 إلى 2100.

تحتوي الاستجابة دائماً على status:

{ "status": "applied", "message": null, "spec": { "…": "a partial map specification" } }

`status`	المعنى
`applied`	تحتوي `spec` على الطبقة.
`unsupported-style`	لا يمكن إنشاء النمط من البيانات المقدمة، وتشرح `message` السبب.
`insufficient-data`	يفتقر الجدول إلى بيانات يتطلبها النمط، مثل أعمدة الموقع، وتحدد `message` ما ينقص.

الاستجابات الثلاث كلها 200. افحص status.

GET /design/styles, /design/samples, /design/themes

ثلاثة فهارس للقراءة فقط: أنماط الخرائط المتاحة وخرائط أمثلة عملية وحزم السمات.

المصادقة: مفتاح خادم أو رمز جلسة أو مفتاح قديم. النطاق: design. التكلفة: لا شيء. تُحسب الاستدعاءات ضمن حد طلبات المفتاح في الدقيقة، ولكن ليس ضمن التزامن.

curl -s https://api.kaleidr.com/inference-api/b2b/v1/design/styles \
  -H "Authorization: Bearer $KALEIDR_KEY"

تضم كل استجابة قائمتها داخل مفتاح واحد:

{ "styles": [ { "…": "…" } ] }

تعيد /design/samples القيمة { "samples": [ … ] } وتعيد /design/themes القيمة { "themes": [ … ] }.

الأخطاء المشتركة بين جميع نقاط نهاية التشغيل

يمكن لكل نقطة نهاية عدا نقطتي تبادل الجلسات إعادة هذه الأخطاء قبل بدء أي معالجة خاصة بنقطة النهاية. ويتم فحصها بالترتيب التالي.

الترتيب	الحالة	الرمز	متى يحدث
1	401	`Invalid or missing API key`	لم تُرسل بيانات اعتماد أو كان المفتاح مجهولًا أو ملغى أو منتهي الصلاحية.
2	401	`publishable_requires_session`	أُرسل مفتاح قابل للنشر. يجب تبادله أولًا.
2	403	`server_key_in_browser`	وصل مفتاح خادم مع ترويسة `Origin`.
2	403	`session_origin_mismatch`	استُخدم رمز جلسة من مصدر آخر.
2	403	`ip_not_allowed`	استُخدم مفتاح خادم أو مفتاح قديم مع قائمة عناوين IP مسموحة من خارجها.
3	403	`insufficient_scope`	يفتقر المفتاح إلى النطاق المطلوب لنقطة النهاية.
3	403	`tier_capability_not_allowed`	يحتوي المفتاح على النطاق لكن خطتك لم تعد تتيحه.
3	403	`product_not_allowed`	استُخدم مفتاح خادم أو مفتاح قديم مقتصر على منتجات محددة لاستدعاء نقطة نهاية لمنتج آخر. راجع تقييد المفتاح.
4	429	`quota_exceeded`	في نقاط النهاية المدفوعة فقط: لا يكفي الرصيد المشترك أو سقف المفتاح لتغطية الاستدعاء.
5	429	`visitor_limit_reached`	في جلسات الخرائط المنشورة فقط: أجرى هذا الزائر طلبات كثيرة.
6	429	`rate_limited`	استُنفد الحد الأقصى لطلبات المفتاح في الدقيقة.
7	429	`b2b_overloaded`, `org_overloaded`	توجد طلبات كثيرة قيد التنفيذ.

يُرفض جسم الطلب الذي يتجاوز الحد بالحالة 413 request_too_large: الحد 2 MiB لكل نقطة نهاية، و5 MiB لنقاط النهاية /design/*. وعندما يعلن الطلب طول جسمه، يجري هذا الرفض قبل جميع الفحوص السابقة.

تجد أجسام الاستجابات وكيفية التعامل معها في الأخطاء والحصص وحدود المعدل.

موضوعات ذات صلة

بدء سريع من الخادم: الاستدعاء الأول خطوة بخطوة.
عقد بث SSE: جميع الأحداث على القنوات المتدفقة.
قراءة البث: تطبيقات عميلة مكتملة.
تراخيص البيانات: الإسناد الذي يجب عرضه.

ملخص​

POST /sdk/sessions​

POST /sdk/share-sessions​

POST /chat/control/stream​

حدود الطلبات​

POST /chat/control/route​

تُبلّغ نقطة النهاية هذه عن الفشل برمز HTTP 200​

GET /retrieval/geocode/forward​

POST /spot​

أظهر إسناد المصدر لكل قيمة​

ما لا تُرجعه واجهة API​

POST /spot/overview/stream​

الانتقال من نقاط النهاية المهملة​

GET /retrieval/poi/enrich​

POST /chat/summary/stream​

POST /chat/button/stream​

POST /design/analyze​

POST /design/apply-direct​

GET /design/styles, /design/samples, /design/themes​

الأخطاء المشتركة بين جميع نقاط نهاية التشغيل​

موضوعات ذات صلة​