مرجع الواجهة البرمجية

اقتراحات البحث

اقتراحات الإكمال التلقائي لمربّع البحث — أسماء تصنيفات وأماكن ومناطق من مفردات Navvo الخاصة، إضافةً إلى عبارات بحث راجعها فريق Navvo.

اقتراحات البحث

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

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

GET /search/suggestions

curl -s "https://navvo.io/api/v1/search/suggestions?q=abd&locale=en&limit=5" \
  -H "x-api-key: nvvo_YOUR_KEY"

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

string

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

locale

string

en أو ar، أو وسم لغة كامل مثل ar-JO (الوسوم التي تبدأ بـ ar تُحَلّ إلى ar وكل ما عداها إلى en). لا يؤثّر إلا عندما يكون q فارغًا، إذ يحدّد لغة قائمة البداية. أمّا مع q غير فارغ، فكتابة الاستعلام هي التي تحدّد اللغة.

limit

number

أقصى عدد من الاقتراحات. القيمة الافتراضية 8، مُقيَّدة إلى 1–20.

الاستجابة

{
  "query": "abd",
  "suggestions": [
    { "text": "Abdali Mall", "kind": "place", "slug": "abdali-mall-e18cf2", "categorySlug": "shopping-mall" },
    { "text": "Abdoun", "kind": "area" },
    { "text": "Abdali", "kind": "area" }
  ]
}

الحقل	النوع	الوصف
`query`	string	قيمة `q` التي أرسلتها، يُعاد صداها.
`suggestions[]`	array	مرتَّبة من الأفضل إلى الأقل. وقد تكون فارغة.
`suggestions[].text`	string	النص المعروض. وهو نص عادي بلا وسوم، فاعرضه كنص.
`suggestions[].kind`	string	`category` أو `place` أو `area` أو `term` (انظر أدناه).
`suggestions[].slug`	string	لـ `place`: معرّف رابط المكان، يُستخدم مع `GET /places/{slug}`.
`suggestions[].categorySlug`	string	لـ `category`: التصنيف الذي تُصفّى النتائج به. ولـ `place`: التصنيف الأساسي للمكان، ويمكنك استخدامه لاختيار أيقونة.

ماذا تفعل عندما يختار المستخدم اقتراحًا

`kind`	ما هو	الإجراء المقترح
`category`	اسم تصنيف (`Pharmacy`، `صيدلية`، `Saydaliyya`)	نفّذ `GET /search` بـ `q=<text>`، أو اعرض ذلك التصنيف مباشرةً بـ `category=<categorySlug>`.
`place`	مكان معروف	افتح المكان بـ `GET /places/{slug}`، ولا تُجرِ بحثًا آخر.
`area`	حيّ أو منطقة أو مدينة	نفّذ `GET /search` بـ `q=<text>`، أو احتفظ بها كمنطقة (`cafe in <text>`).
`term`	عبارة بحث راجعتها Navvo	نفّذ `GET /search` بـ `q=<text>`.

تعمل الاقتراحات والنتائج معًا بشكل جيد. أثناء كتابة المستخدم، استدعِ هذه النقطة وGET /search مع mode=typeahead بالتوازي، ثم اعرض الاقتراحات فوق النتائج الأولى. تجيب الاقتراحات عن «ماذا قد يقصد؟»، وتجيب النتائج عن «أيّ الأماكن تطابق؟».

يُعاد بناء قوائم الاقتراحات كل ليلة من الكتالوج، لذا قد تستغرق تغييرات الكتالوج حتى يوم كامل لتظهر هنا. أمّا GET /search فيلتقطها خلال دقائق.

الأخطاء

الحالة	متى
`400`	`locale` أطول من 35 حرفًا، أو معامل من نوع خاطئ.
`401` / `403`	المفتاح مفقود أو غير صالح، أو يفتقر إلى النطاق `search`، أو تجاوز حصته.

يُحتسب كل استدعاء طلبًا موزونًا واحدًا (راجع البحث ← القياس وحدود المعدّل).

الأخبار والأسواق

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

أماكن مشابهة

صفّ «المزيد من هذا النوع» لصفحة مكان — أماكن تشبه مكانًا معيّنًا في المعنى، مع بديل احتياطي من أماكن قريبة في التصنيف نفسه.