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

المهام (بيانات الحشود)

تحسين بيانات تشاركي مُحفَّز — إظهار مهام صغيرة لسدّ فجوات البيانات القريبة، وجمع الإجابات في قائمة المراجعة، ومنح المساهمين نقاطاً.

المهام

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

النطاق المطلوب: places (لـ GET /quests ولوحة المتصدّرين). والإجابة متاحة بدون تسجيل دخول.

GET /quests

مهام سدّ فجوات البيانات القريبة، الأعلى قيمة أولاً.

الاستعلام	النوع	ملاحظات
`bbox`	string	`minLng,minLat,maxLng,maxLat` — حصرها على نطاق الخريطة (مُستحسَن)
`limit`	number	أقصى عدد مهام (افتراضي 20، أقصى 100)
`types`	string	تصفية اختيارية، مفصولة بفواصل: `hours,accessibility,name_ar,category,description`

curl -s "https://navvo.io/api/v1/quests?bbox=35.8,31.9,36.0,32.05&limit=6" \
  -H "x-api-key: $NAVVO_API_KEY"

{
  "count": 6,
  "candidatesScanned": 226,
  "quests": [
    {
      "id": "a1b2c3d4-…:hours",
      "placeId": "a1b2c3d4-…",
      "slug": "abo-shosha-taxi-85dc70",
      "placeName": "Abo Shosha Taxi",
      "type": "hours",
      "action": "Add opening hours",
      "question": "What are the opening hours of Abo Shosha Taxi?",
      "points": 15,
      "location": { "lat": 31.95, "lng": 35.91 }
    }
  ]
}

نوع المهمة	النقاط	يُكتشَف عندما
`hours`	15	لا توجد ساعات عمل للمكان
`accessibility`	10	لا توجد مجموعة سمات إمكانية الوصول
`category`	10	لا يوجد تصنيف مُسنَد
`name_ar`	10	الاسم العربي غائب
`description`	5	لا يوجد وصف (إنجليزي أو عربي)

المعرّف id ثابت ({placeId}:{type}) — مرّره مباشرةً إلى POST /quests/solve.

POST /quests/solve

أرسِل إجابة. الإجابة بدون تسجيل دخول مسموحة؛ مرّر reporterUserId لتجميع النقاط نحو لوحة المتصدّرين. لا تُطبَّق الإجابة مباشرةً — بل تدخل قائمة المراجعة.

الحقل	النوع	ملاحظات
`questId`	string	معرّف المهمة `id` (أو زوّد `placeId` + `type` منفصلين)
`answer`	any	القيمة المُساهَم بها (نص، أو منظّمة للساعات) — مطلوب
`lat` / `lng`	number	اختياري، الموضع الذي أجاب منه المساهم
`reporterUserId`	string	اختياري، معرّف المستخدم المُسجَّل

curl -X POST "https://navvo.io/api/v1/quests/solve" \
  -H "content-type: application/json" \
  -d '{ "questId": "a1b2c3d4-…:hours", "answer": "Mo-Fr 09:00-17:00", "reporterUserId": "user-123" }'

{ "ok": true, "points": 15, "total": 35, "message": "Thanks! +15 points" }

total هو نقاط المساهم التراكمية (تُحذَف/تساوي points للمجهول). الطلبات غير الصالحة تُعيد { "ok": false, "error": "answer required" | "unknown quest type" | "placeId required" }.

GET /quests/leaderboard

أعلى المساهمين بالنقاط (المعرّفات مُجهَّلة إلى بادئة قصيرة).

{
  "contributors": [
    { "contributor": "user-1…", "points": 35, "solved": 3 },
    { "contributor": "anonymous", "points": 5, "solved": 1 }
  ],
  "totalSolved": 4
}

GET /quests/me

إجماليات المساهم المُسجَّل نفسه (تتطلّب جلسة مستخدم — Bearer JWT، وليس مفتاح API).

{ "userId": "user-123", "solved": 3, "points": 35 }

إجابات المهام مصدرها الحشود وتُراجَع قبل النشر. تظهر في /platform-admin → Feedback مُصفّاةً بـ source: quest ليتحقّق منها المحررون ويطبّقوها.

الترميز الجغرافي

ترميز جغرافي أمامي وعكسي مدعوم ببيانات خرائط Navvo.

وكيل أطلس (تحكّم لغوي)

حوِّل الأوامر بالّلغة الطبيعية إلى إجراءات خريطة مُهيكلة — بحث، اتجاهات، دبابيس، تحكّم بالطبقات، والآن خطط رحلات يومية وتحسين مسارات الأساطيل.