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

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

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

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

حوِّل العناوين النصّية الحرة إلى إحداثيات (أمامي) والإحداثيات إلى عناوين (عكسي). الترميز الجغرافي طبقة تطبيع فوق محرّك الترميز الجغرافي لدى Navvo.

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

تُعيد كلتا نقطتي النهاية مغلّفاً بصيغة { provider, available, data }. عندما يتعذّر الوصول إلى محرّك الترميز الجغرافي، ما زلت تحصل على 200 مع available: false وحقل status — تحقّق دائماً من available قبل قراءة data.

GET /geocode/search

الترميز الجغرافي الأمامي — حلّ سلسلة استعلام إلى أماكن مرشّحة.

curl -s "https://navvo.io/api/v1/geocode/search?q=Abdali%20Hospital%2C%20Amman&limit=5" \
  -H "x-api-key: nvvo_YOUR_KEY"

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

string required

استعلام نصّي حر، مثل Abdali Hospital, Amman. يجب ألا يكون فارغاً.

locale

string

تفضيل اللغة. القيمة الافتراضية ar,en (العربية أولاً). يُستخدم كتلميح accept-language.

limit

string

أقصى عدد للنتائج. القيمة الافتراضية 20، بحدّ أقصى صارم 50.

lat

string

خط العرض لانحياز القرب (يُطبَّق فقط عند اقترانه بـ lon).

lon

string

خط الطول لانحياز القرب (مقترن بـ lat).

bbox

string

انحياز نافذة العرض بصيغة west,south,east,north (خط الطول أولاً).

الاستجابة

المغلّف: provider ("navvo")، وavailable (boolean)، وdata — وهو مصفوفة من النتائج، كل منها بالشكل أدناه.

{
  "provider": "navvo",
  "available": true,
  "data": [
    {
      "place_id": 12345678,
      "osm_type": "way",
      "osm_id": 98765432,
      "lat": "31.9637400",
      "lon": "35.9221300",
      "category": "amenity",
      "type": "hospital",
      "name": "Abdali Hospital",
      "display_name": "Abdali Hospital, Al Abdali, Amman, Jordan",
      "address": { "suburb": "Al Abdali", "city": "Amman", "country": "Jordan", "country_code": "jo" },
      "boundingbox": ["31.963", "31.964", "35.921", "35.923"]
    }
  ]
}

عندما يفشل محرّك الترميز الجغرافي أو لا يكون مُهيَّأً:

{ "provider": "navvo", "available": false, "status": 502 }

يُعاد lat/lon على شكل سلاسل نصّية. حلّلها قبل استخدامها كأرقام.

الأخطاء

الحالة	متى
`400`	`q` مفقود/فارغ، أو `limit`/`lat`/`lon` ليست أرقاماً.
`401` / `403`	مفتاح مفقود/غير صالح، أو مفتاح يفتقر إلى النطاق `geocode`.

تظهر إخفاقات محرّك الترميز الجغرافي على شكل available: false داخل استجابة 200، وليس أبداً على شكل 5xx.

GET /geocode/autocomplete

إكمال تلقائي خفيف — النقطة التي تستدعيها مع كل ضغطة مفتاح في صندوق البحث. تطبّق المطابقة المراعية للعربية/العربيزي نفسها التي في /geocode/search لكنها تعيد حمولة مُشذّبة جاهزة للعرض (معرّف، تسمية، إحداثيات رقمية). فضّلها على استدعاء /geocode/search المتكرر للاقتراحات: استجابات أصغر، وlat/lng رقمية، وحدّ افتراضي معقول.

curl -s "https://navvo.io/api/v1/geocode/autocomplete?q=abdali&limit=8" \
  -H "x-api-key: $NAVVO_API_KEY"

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

المعاملات نفسها في /geocode/search (q مطلوب؛ وlocale وترجيح القرب lat/lon وbbox اختيارية)، باستثناء أن limit افتراضيه 8 وسقفه 15.

الاستجابة

{
  "provider": "navvo-geocode",
  "query": "abdali",
  "suggestions": [
    {
      "id": "131530",
      "label": "العبدلي, منطقة زهران, عمان, الأردن",
      "name": "العبدلي",
      "lat": 31.9593159,
      "lng": 35.9187494,
      "type": "neighbourhood",
      "category": "place"
    }
  ]
}

الحقل	النوع	ملاحظات
`suggestions[].id`	string	معرّف مرشّح ثابت
`suggestions[].label`	string	سطر العرض الكامل لصف القائمة المنسدلة
`suggestions[].name`	string	الاسم الأساسي القصير
`suggestions[].lat` / `lng`	number \| null	إحداثيات رقمية (بخلاف `/geocode/search`، لا حاجة لتحليل سلاسل)
`normalizedQuery`	string	يظهر عندما يُطبَّع الاستعلام (تنويعات عربية / عربيزي) قبل المطابقة

GET /geocode/reverse

الترميز الجغرافي العكسي — حلّ إحداثية إلى أقرب عنوان. يُحلّل دائماً بتفصيل الشارع/المبنى (zoom=18).

curl -s "https://navvo.io/api/v1/geocode/reverse?lat=31.95&lon=35.91" \
  -H "x-api-key: nvvo_YOUR_KEY"

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

lat

string required

خط العرض بالدرجات العشرية.

lon

string required

خط الطول بالدرجات العشرية.

locale

string

لغة العنوان — ar أو en أو قائمة تفضيل مثل ar,en (الافتراضي). تتحكم بلغة display_name وأجزاء address، بالاتفاقية نفسها في الترميز الأمامي.

الاستجابة

حقل data في المغلّف هو كائن مفرد (نتيجة الترميز العكسي الخام من المحرّك):

{
  "provider": "navvo",
  "available": true,
  "data": {
    "place_id": 12345678,
    "osm_type": "way",
    "lat": "31.95",
    "lon": "35.91",
    "category": "highway",
    "type": "residential",
    "name": "King Hussein Street",
    "display_name": "King Hussein Street, Al Abdali, Amman, Jordan",
    "address": { "road": "King Hussein Street", "suburb": "Al Abdali", "city": "Amman", "country": "Jordan", "country_code": "jo" }
  }
}

الأخطاء

الحالة	متى
`400`	`lat` أو `lon` مفقود / ليس رقماً.
`401` / `403`	مفتاح مفقود/غير صالح، أو مفتاح يفتقر إلى النطاق `geocode`.

POST /geocode/batch

ترميز جغرافي أمامي بالجملة — حلّ عناوين كثيرة في طلب واحد (استيراد CSV، إثراء البيانات). يعيد أفضل تطابق لكل استعلام. حتى 50 استعلاماً لكل طلب؛ وتنطبق المطابقة المراعية للعربية/العربيزي نفسها التي في /geocode/search على كل استعلام.

curl -s -X POST "https://navvo.io/api/v1/geocode/batch" \
  -H "x-api-key: $NAVVO_API_KEY" -H "content-type: application/json" \
  -d '{ "queries": ["Amman", "Aqaba", "Irbid"], "locale": "ar" }'

الحقل	النوع	ملاحظات
`queries`	string	مطلوب — العناوين/الأماكن المراد ترميزها (حتى 50)
`locale`	string	تلميح لغة النتائج (اختياري)
`bbox`	string	`minLng,minLat,maxLng,maxLat` اختياري لترجيح النتائج

{
  "provider": "navvo-geocode", "count": 3, "found": 3,
  "results": [
    { "query": "Amman", "found": true, "lat": 31.9539, "lng": 35.9106, "displayName": "عمان, الأردن", "type": "city", "category": "place" },
    { "query": "Aqaba", "found": true, "lat": 29.58, "lng": 35.289, "displayName": "العقبة, الأردن", "type": "city", "category": "place" }
  ]
}

الحقل	النوع	ملاحظات
`count`	number	عدد الاستعلامات المعالَجة
`found`	number	كم استعلاماً تحوّل إلى إحداثيات
`results[]`	array	`{ query, found, lat, lng, displayName, type, category }` — و`found:false` (بإحداثيات null) عندما لا تطابق للاستعلام

تعمل الاستعلامات بتزامن محدود لاحترام حدود معدّل المزوّد؛ توقّع بضع مئات من المللي ثانية لكل ~4 عناوين.

الأخطاء

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

POST /geocode/reverse-batch

ترميز جغرافي عكسي بالجملة — حوّل إحداثيات كثيرة إلى عناوين في طلب واحد (عكس /geocode/batch). أفضل تطابق لكل نقطة؛ حتى 50 نقطة لكل طلب.

curl -s -X POST "https://navvo.io/api/v1/geocode/reverse-batch" \
  -H "x-api-key: $NAVVO_API_KEY" -H "content-type: application/json" \
  -d '{ "points": [ {"lat":31.9539,"lng":35.9106}, {"lat":29.532,"lng":35.006} ] }'

الحقل	النوع	ملاحظات
`points`	array	مطلوب — كائنات `{ lat, lng }` (أو `lon`)، حتى 50
`locale`	string	لغة العنوان اختيارياً — `ar` أو `en` أو `ar,en` (الافتراضي)، تُطبَّق على كل نقطة

{
  "provider": "navvo-geocode", "count": 2, "found": 2,
  "results": [
    { "lat": 31.9539, "lng": 35.9106, "found": true, "displayName": "الدوار الثالث, منطقة زهران, عمان, الأردن", "type": "…", "address": { } }
  ]
}

النقطة التي لا تطابق لها (أو إحداثيات غير صالحة) تعيد found: false.

الأخطاء

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

إعدادات العنونة. يعيد GET /geo/addressing/config إعدادات العنونة في المنصة — هل رموز المواقع القصيرة مفعّلة (plusCodesEnabled، defaultCodeLength)، وأساس رابط المشاركة، وحالة تكامل العنوان الوطني — كي تقرر العملاء أي صيغ عناوين تعرضها. انظر العنونة لواجهة العنونة الكاملة.

تحسين المسارات

تحسين مسارات ذاتي الاستضافة عبر OR-Tools — مسائل توجيه المركبات (VRP/VRPTW) مع السعة والنوافذ الزمنية والاستلام والتسليم وتعدّد المستودعات، إضافة إلى تعبئة الحاويات وجدولة السائقين وإعادة التحسين الحيّة والتحسين كمَهمّة غير متزامنة.

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

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