البحث

بحث نصّي حرّ في كتالوج الأماكن لدى Navvo. يتعامل مربّع استعلام واحد مع العربية والإنجليزية والعربيزي (العربية مكتوبةً بحروف لاتينية وأرقام، مثل saydaliyeh أو mat3am) والاستعلامات المختلطة. تتعرّف Navvo على كلمات التصنيفات (pharmacy، صيدلية) والمناطق (cafe in Abdoun) وعبارات «قريب مني» و«مفتوح الآن»، وتتسامح مع الأخطاء الإملائية، وترتّب النتائج بحسب مدى مطابقة اسم المكان أولًا قبل أن تزن المسافة والشعبية.

فهم الاستعلام حتميّ: هو مجموعة قواعد ومفردات منسَّقة، وليس نموذج ذكاء اصطناعي، لذا يُقرأ الاستعلام نفسه دائمًا بالطريقة نفسها ولا ينتظر نموذجًا أبدًا. ويعمل كل ذلك على البنية التحتية الخاصة بـ Navvo.

يشمل التسامح مع الأخطاء الإملائية الكلمات القصيرة أيضًا. خذ كلمة إنجليزية من أربعة إلى ستة أحرف لا يستخدمها أي اسم مكان، لكنها تختلف بحرف واحد عن كلمة تستخدمها أسماء الأماكن. تبحث Navvo أيضًا عن صيغتها المصحّحة إلى جانب الاستعلام كما كُتب، وترتّب مجموعتي النتائج معًا: cafr تجد المقاهي وhotl تجد الفنادق. يُستمدّ التصحيح من الكلمات الواردة في أسماء الأماكن لدى Navvo نفسها، ويفضّل أكثر أخطاء الكتابة شيوعًا، مثل مفتاح مجاور أو حرفين متبادلين. ولا تُصحَّح كلمات العربيزي بهذه الطريقة، لأنها عربية مكتوبة بحروف لاتينية وليست أخطاء إملائية.

النطاق المطلوب: search

GET /search

ابحث عن الأماكن باستعلام نصّي حر.

curl -s "https://navvo.io/api/v1/search?q=coffee&lat=31.9539&lon=35.9106&limit=10" \
  -H "x-api-key: nvvo_YOUR_KEY"

معاملات الاستعلام

ترويسات الطلب

هذه الترويسات كلها اختيارية. الأربع الأولى تتحكّم فيما تسجّله Navvo، وتشرح صفحة تحليلات البحث والخصوصية النموذج الذي تقوم عليه.

الاستجابة

تحمل كل استجابة الترويسة Cache-Control: no-store. لكل استجابة queryId جديد، فالنسخة المخزَّنة مؤقتًا قد تربط نقرات المستخدم ببحث شخص آخر. لا تخزّن استجابات /search مؤقتًا في Service Worker ولا في شبكة توصيل محتوى.

كل عنصر من عناصر places.items[]:

{
  "query": "coffee",
  "locale": "en",
  "queryId": "AaDxmIYgiEC1I4ZdHCWiERmR",
  "understanding": {
    "unavailable": false,
    "purpose": "search_understanding",
    "parsed": { "language": "en", "intent": "place", "category": "Coffee Shop", "categories": ["coffee-shop", "cafe", "coffee-stand", "cafeteria", "cat-cafe", "tea-house"] }
  },
  "places": {
    "items": [
      {
        "id": "e3bacbd9-1e5d-474c-b84e-2fe7e1556541",
        "slug": "coffee-factory-co-jabal-amman-a3ddbd",
        "nameEn": "Coffee Factory & Co. - Jabal Amman",
        "nameAr": null,
        "categories": ["coffee-shop"],
        "canonicalCategorySlug": "coffee-shop",
        "rawCategories": ["Coffee shop"],
        "rating": 4.6,
        "sponsored": false,
        "center": "POINT(35.905152 31.952061)",
        "lat": 31.952061,
        "lng": 35.905152,
        "iconLightUrl": "https://navvo.io/uploads/category-icons/coffee-shop-light.svg",
        "iconDarkUrl": "https://navvo.io/uploads/category-icons/coffee-shop-dark.svg",
        "imageUrl": "https://navvo.io/uploads/place-images/e3/e3bacbd9-1e5d-474c-b84e-2fe7e1556541-dc3949fa.webp",
        "distanceKm": 0.55
      }
    ],
    "total": 1000,
    "page": 1,
    "limit": 10
  },
  "near": { "lat": 31.9539, "lng": 35.9106 },
  "index": { "provider": "navvo-search", "configured": true, "available": true, "mode": "keyword" }
}

فهم الاستعلام

يخبرك understanding كيف قرأت Navvo الاستعلام. النتائج تعكسه أصلًا، فلا يلزمك التصرّف بناءً عليه. استخدمه بدلًا من ذلك لتلميحات الواجهة، كإظهار شارة «مفتوح الآن» عندما يكتب المستخدم «مفتوح الآن». تُنتجه مجموعة قواعد دون أي نموذج، لذا تُقرأ الاستعلامات المتطابقة دائمًا بالطريقة نفسها، ويكون unavailable دائمًا false. وقد أُبقي الحقل للتوافق.

كل ما هو مفيد موجود تحت understanding.parsed:

لا تظهر المفاتيح إلا عند انطباقها. بالنسبة إلى cafe in Abdoun:

"parsed": { "language": "en", "intent": "category", "category": "Coffee Shop", "categories": ["coffee-shop", "cafe", "coffee-stand", "cafeteria", "cat-cafe", "tea-house"], "locality": "Abdoun" }

الأوجه

يضيف facets=category,amenities أعدادًا يمكنك تحويلها إلى شارات تصفية:

"facets": {
  "category": [
    { "slug": "coffee-shop", "name": { "en": "Coffee Shop", "ar": "مقهى" }, "count": 812 },
    { "slug": "cafe", "name": { "en": "Cafe", "ar": "مقهى" }, "count": 108 },
    { "slug": "coffee-roastery", "name": { "en": "Coffee Roastery", "ar": "محمصة قهوة" }, "count": 10 }
  ],
  "amenities": [
    { "slug": "wheelchair-accessible-entrance", "count": 301 },
    { "slug": "delivery", "count": 188 }
  ]
}

• كل قائمة مرتَّبة حسب count، الأعلى أولًا. وقد يكون name.en أو name.ar لتصنيف ما null.
• تشمل الأعداد الأماكن التي تطابق كلمات الاستعلام ومرشّحاتك. وقد تتضمّن items أيضًا نتائج قريبة أو نتائج بالمعنى، لذا تُرشد الأعداد واجهة التصفية ولا تمثّل تفصيلًا دقيقًا للقائمة.
• مرّر أي slug مباشرةً كـ category= أو amenities= لتطبيق المرشّح.
• يغيب facets إذا لم تطلبه، وقد يغيب عندما يجيب البديل (index.available: false).

الإبراز

مع highlight=true، يحمل العنصر الذي يطابق اسمُه الاستعلامَ highlight.nameEn و/أو highlight.nameAr. كلٌّ منهما هو الاسم مُهرَّبًا بصيغة HTML، مع إحاطة الكلمات المطابقة بـ <em>…</em>. ولا يظهر المفتاح إلا عندما يحتوي ذلك الاسم على تطابق:

"highlight": { "nameEn": "<em>Coffee</em> Factory &amp; Co. - Jabal Amman" }

إدراج السلسلة كـ HTML آمن. لكن النهج الأمتن هو عرضها كعُقد نصية: قسّمها عند الوسوم وفكّ ترميز الكيانات بنفسك، ولا تمرّرها أبدًا إلى innerHTML أو dangerouslySetInnerHTML:

// "<em>Coffee</em> Factory &amp; Co." -> [{ text: "Coffee", match: true }, { text: " Factory & Co.", match: false }]
function highlightSegments(html) {
  const decode = (s) => s
    .replace(/&lt;/g, "<").replace(/&gt;/g, ">")
    .replace(/&quot;/g, '"').replace(/&#39;/g, "'")
    .replace(/&amp;/g, "&");
  return html.split(/(<em>.*?<\/em>)/g).filter(Boolean).map((part) => {
    const m = part.match(/^<em>(.*)<\/em>$/);
    return { text: decode(m ? m[1] : part), match: Boolean(m) };
  });
}

didYouMean وجميع حقول GET /search/suggestions نص عادي لا يحمل أي وسوم.

تفاصيل النتيجة

يمكن أن يحمل العنصر ما تعرضه قائمة النتائج أو بطاقة الخريطة: reviewCount وcategoryName وpriceRange وpriceLevel وaddress وarea وhours وhighlights. يأتي كل منها من سجل المكان، ويُحذف إذا لم تتوفّر للمكان تلك البيانات، لذا تحقّق من وجود الحقل قبل استخدامه. وتظهر الحقول نفسها في suggestions عند عدم وجود نتائج وفي الأماكن المشابهة.

يصف hours اليوم الحالي بتوقيت الأردن، ويُحسب لحظة تنفيذ البحث، فلا تخزّن الاستجابة مؤقتًا أكثر من بضع دقائق.

"hours": { "state": "closed", "opensAt": "09:00", "opensDay": "sunday" }

يبقى المكان الذي يغلق الساعة 2 فجرًا open بعد منتصف الليل، مع "closesAt": "02:00".

الترتيب

يوضع كل مرشَّح أولًا في نطاق مطابقة. النطاقات لا تختلط، فالنطاق الأفضل يتقدّم دائمًا على الأسوأ:

1. مطابقة تامة. الاستعلام هو اسم المكان أو أحد أسمائه البديلة، بما في ذلك بعد تحويل إملائي (استعلام بالعربيزي حُوِّل إلى العربية مثلًا).
2. مطابقة قوية. يحتوي الاسم على كل كلمات الاستعلام مكتوبةً بشكل صحيح، أو يبدأ بما كتبه المستخدم مع mode=typeahead.
3. مطابقة كاملة. كل الكلمات مطابقة مع السماح بأخطاء إملائية، أو تتوزّع الكلمات على الاسم والتصنيف والحيّ (cafe abdoun يجد مقهى في عبدون)، أو ينتمي المكان إلى التصنيف الذي يطلبه الاستعلام.
4. مطابقة جزئية. بعض الكلمات فقط مطابقة.
5. بالمعنى. عُثر على المكان عبر المطابقة بالمعنى وحدها.

داخل النطاق الواحد، تجمع Navvo بين المسافة عن نقطة الأصل، والشعبية (حجم المراجعات وبروز المكان على الخريطة)، وصلة النص، والأخطاء الإملائية، والتعزيزات التحريرية. وتشكّل بضع قواعد هذا الترتيب:

• بحث التصنيف يساوي بين الجميع. في pharmacy أو صيدلية قريبة لا يحظى مكان اسمه حرفيًا «صيدلية» بأي أفضلية. تتقدّم الأماكن القريبة والشائعة في ذلك التصنيف.
• المناطق تنقل نقطة الأصل. في cafe in Abdoun تُرتَّب النتائج حول عبدون لا حول lat/lon. وبدون كلمة ربط (cafe abdoun) تبقى نقطة الأصل الخاصة بك وتحصل الأماكن في عبدون على تعزيز. وإذا كان الاستعلام كله اسم منطقة، تبحث Navvo عنها بالاسم.
• المرافق المساندة تتراجع. مواقف الحافلات ومواقف السيارات ومواقف سيارات الأجرة والبوابات والمداخل وأجهزة الصراف الآلي تأتي بعد المكان الرئيسي ما لم يطلبها الاستعلام.
• الأردن أولًا. بدون نقطة أصل، تتقدّم الأماكن في الأردن على مطابقات بالجودة نفسها في الخارج.
• الفرع البعيد لا يتقدّم على الفروع القريبة. مع وجود نقطة أصل، تتنافس مطابقة الاسم التامة التي تبعد أكثر من 25 كم، من حيث المسافة، مع الأماكن الأقرب التي تتضمّن أسماؤها الاستعلام، فيعرض البحث عن carrefour من عمّان فروع عمّان أولًا. أما المكان الكبير فيحتفظ بتقدّمه مهما بعُد (Petra وAl-Aqsa Mosque).
• «مفتوح الآن» في الاستعلام يؤخّر الأماكن المعروف أنها مغلقة (المفتوحة أولًا، ثم مجهولة الساعات، ثم المغلقة) حتى دون openNow=true. أما openNow=true فيزيل كل ما ليس مفتوحًا.
• الأماكن المُموَّلة ذات الصلة بالاستعلام تحصل على تعزيز صغير داخل نطاقها، ولا تقفز أبدًا إلى نطاق أفضل. والنتائج التي تثبّتها قاعدة من Navvo تحمل promoted: true، وsponsored: true أيضًا عندما يكون الموضع مدفوعًا.

يحلّ sort=distance وsort=rating محلّ هذا الترتيب كليًّا.

المطابقة بالمعنى

تجد المطابقة بالكلمات الأماكن التي تحتوي أسماؤها وتصنيفاتها على كلمات الاستعلام. أمّا المطابقة بالمعنى فتجد أيضًا الأماكن التي تناسب وصفًا، مثل quiet place to study أو مكان للعشاء مع العائلة، حتى حين لا تتطابق أي كلمة، وذلك عبر العربية والإنجليزية أيضًا. وتعمل بالكامل على البنية التحتية الخاصة بـ Navvo، فلا يذهب نص الاستعلام إلى أي طرف ثالث.

• هي بديل احتياطي فقط. لا تضيف نتائج إلا عندما تجد المطابقة بالكلمات مطابقات قوية قليلة. فالاستعلام الذي يملك مطابقات أسماء جيدة لا يتغيّر، ونتائج المعنى تأتي دائمًا بعد نتائج الكلمات (النطاق 5).
• تحتاج إلى قرينة في الاستعلام: يجب أن تطابق كلمة واحدة على الأقل محتوى الدليل (مع التسامح مع الأخطاء الإملائية)، أو أن يسمّي الاستعلام فئة، أو أن يحمل مرشّحًا. ولا تحصل الحروف العشوائية والأسئلة غير المتعلقة بالأماكن على نتائج بالمعنى.
• تتطلّب استعلامًا من كلمتين كاملتين على الأقل، وmode=submit، واستعلامًا ليس بحث تصنيف خالصًا. ولا تعمل أبدًا مع typeahead.
• تنتظرها Navvo 350 مللي ثانية على الأكثر. إن كانت أبطأ أو غير متاحة، تحصل على نتائج الكلمات دونها ودون أي خطأ.
• semantic=off يعطّلها. وsemantic=on يسمح بها في طلبات مفاتيح API، حيث تتصرّف auto مثل off.
• يكون index.mode في الاستجابة hybrid عندما تُسهم المطابقة بالمعنى في تلك الاستجابة، وkeyword فيما عدا ذلك.

عند عدم وجود نتائج

عندما لا يطابق شيء، تكون places.items فارغة وplaces.total مساويًا 0، ولا تملأ Navvo القائمة أبدًا بأماكن غير ذات صلة. بدلًا من ذلك:

• suggestions[] تسرد أماكن شائعة قرب نقطة الأصل، أو أماكن شائعة في الأردن عند غياب نقطة الأصل، بنفس بنية العناصر. اعرضها تحت عنوان مثل «لا نتائج — أماكن شائعة»، لا كنتائج.
• didYouMean يظهر عندما يبدو الاستعلام خطأً إملائيًا لشيء موجود في المفردات المعتمدة لدى Navvo (أسماء التصنيفات وأسماء الأماكن المعروفة). اعرضه كرابط يعيد البحث.

ترقيم الصفحات

يتنقّل page وlimit في قائمة مرتَّبة واحدة. يرتّب كل استعلام أفضل 200 مرشَّح على الأكثر، لذا توقّف عندما تعود صفحة بعدد عناصر أقل من limit. ولا تحسب الصفحة الأخيرة من places.total، فهو تقدير.

لجلب التفاصيل الكاملة لمكان (ساعات العمل، الصور، المداخل)، استدعِ GET /places/{slug} باستخدام slug من إحدى النتائج.

الأخطاء

إذا تعذّر الوصول إلى فهرس البحث، فلا يفشل /search. يجيب بديل أبسط من قاعدة البيانات بدلًا منه، ويكون index.available مساويًا false. وتتبع أجسام الأخطاء البنية القياسية الموضّحة في المواصفات.

القياس وحدود المعدّل

يُحتسب كل طلب بحث طلبًا واحدًا من حصة مفتاحك في الدقيقة واليوم، ويُحتسب طلبات موزونة لفوترة خطتك (راجع الخطط والقياس). أما المفتاح غير المحدود فلا حصة له، لكن طلباته تبقى موزونة:

لا تغيّر المطابقة بالمعنى وزن الطلب. والطلبات التي لا تحمل مفتاح API تحصل على المطابقة بالمعنى ضمن حصّة ساعية تقريبية لكل عنوان IP للعميل: نحو 120 بحثًا تعمل فيها المطابقة بالمعنى فعلًا، وبعد تجاوزها تكتفي بصمت بالمطابقة بالكلمات.

حالة الفهرس والمراقبة

تحمل كل استجابة كائن index: