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

البحث

بحث نصّي كامل عن الأماكن في الشرق الأوسط، مع فهم الاستعلام بالذكاء الاصطناعي وترتيب يراعي المُموَّل.

البحث

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

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

GET /search

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

curl -s "https://navvo.io/api/v1/search?q=coffee%20in%20Abdoun&limit=10" \
  -H "x-api-key: nvvo_YOUR_KEY"

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

string required

استعلام البحث. نص حر — مثل coffee in Abdoun أو pharmacy near me. يجب ألا يكون فارغاً.

locale

string

اللغة المفضّلة، en (الافتراضية) أو ar. يُعاد صداها في الاستجابة.

page

number

رقم الصفحة بدءاً من 1. القيمة الافتراضية 1.

limit

number

أقصى عدد للعناصر المُعادة. القيمة الافتراضية 25.

الاستجابة

الحقل	النوع	الوصف
`query`	string	استعلامك، يُعاد صداه.
`locale`	string	اللغة المُحدَّدة.
`understanding`	object	مخرجات مخطِّط الاستعلام بالذكاء الاصطناعي. يُجاب ضمن مهلة قصيرة — عند أول ظهور لاستعلام ما يكون غالبًا `unavailable` (يواصل المخطِّط عمله في الخلفية ويُخزَّن للاستعلامات المكررة). نتائج البحث لا تنتظره أبدًا.
`places.items[]`	array	النتائج المرتَّبة (انظر أدناه). تكون فارغة عند عدم وجود تطابق — لا نتائج حشو غير ذات صلة.
`places.total`	number	إجمالي عدد النتائج المطابقة (`0` عند عدم وجود تطابق فعلي).
`places.page` / `places.limit`	number	صدى ترقيم الصفحات.
`suggestions[]`	array	يظهر فقط عندما تكون `places.items` فارغة: أماكن شائعة قريبة يمكن عرضها كبديل «لا نتائج — جرّب هذه». بنفس بنية عناصر `places.items[]`.
`index`	object	حالة فهرس البحث لدى Navvo (`provider`، `configured`، `available`، `host`).

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

الحقل	النوع	الوصف
`id`	string	معرّف المكان.
`slug`	string	معرّف الرابط (يُستخدم مع `GET /places/{slug}`).
`nameEn` / `nameAr`	string	الأسماء.
`categories`	string	معرّفات الفئات القياسية (الفئة القياسية أولاً).
`canonicalCategorySlug`	string	الفئة الأساسية.
`rawCategories`	string	الفئات الأصلية غير المُطبَّعة.
`rating`	number	التقييم (`0` إن لم يوجد).
`sponsored`	boolean	إدراج مُموَّل.
`center`	string	الموقع بصيغة WKT على شكل `POINT(<lng> <lat>)` — خط الطول أولاً.

{
  "query": "coffee in Abdoun",
  "locale": "en",
  "understanding": { "model": "navvo-ai", "unavailable": false, "purpose": "search_understanding", "content": "{\"categoryHints\":[\"coffee\"]}" },
  "places": {
    "items": [
      {
        "id": "b1f3c2a0-1234-4abc-9def-0123456789ab",
        "slug": "rumi-cafe-abdoun",
        "nameEn": "Rumi Cafe",
        "nameAr": "مقهى رومي",
        "categories": ["cafe", "coffee-shop"],
        "canonicalCategorySlug": "cafe",
        "rawCategories": ["Coffee shop", "Cafe"],
        "rating": 4.7,
        "sponsored": true,
        "center": "POINT(35.8806 31.9461)"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 25
  },
  "index": { "provider": "navvo", "configured": true, "available": true, "host": "configured" }
}

الترتيب

تُرتَّب النتائج كالتالي: (1) مدى مطابقة الاسم لاستعلامك — الاسم المطابق تمامًا أولًا، ثم الأسماء التي تبدأ بالاستعلام، ثم المطابقات الجزئية (تُتجاهَل أدوات التعريف في البداية مثل "The" و"ال")؛ (2) المُموَّل و ذو الصلة بالاستعلام؛ (3) حسب التقييم rating تنازليًا. المكان الذي يحمل حرفيًا الاسم الذي بحثت عنه يتقدّم دائمًا على نتيجة عالية التقييم غير ذات صلة.

الأخطاء

الحالة	متى
`400`	`q` مفقود أو فارغ.
`401` / `403`	مفتاح مفقود/غير صالح، أو مفتاح يفتقر إلى النطاق `search`.

ترقيم الصفحات ليس له مؤشّر — قارن page * limit مع places.total. لجلب التفاصيل الكاملة لمكان (ساعات العمل، الصور، المداخل)، استدعِ GET /places/{slug} باستخدام slug من إحدى النتائج.

بوابة المطوّرين

استخدم بوابة مطوّري Navvo لإنشاء المؤسسات والمشاريع، وإدارة مفاتيح API، ومراقبة الاستخدام الحيّ، وتجربة نقاط النهاية في بيئة الاختبار.

تفاصيل Geo ثلاثية الأبعاد

ميزات المباني والطرق والغطاء النباتي والبنية التحتية ثلاثية الأبعاد لمشاهد خرائط غنية.