البدء

البدء السريع

احصل على مفتاح API ونفّذ أول استدعاء لواجهة Navvo البرمجية خلال دقائق قليلة.

البدء السريع

ينقلك هذا الدليل من الصفر إلى أول استدعاء ناجح للواجهة البرمجية.

1. احصل على مفتاح API

تتم مصادقة الوصول إلى الواجهة البرمجية بمفتاح. تُنشأ المفاتيح في بوابة المطوّرين ضمن مؤسسة ← مشروع. يُوثَّق التدفّق الكامل (حساب، مؤسسة، مشروع، مفتاح) في المصادقة؛ والنسخة المختصرة:

سجّل الدخول إلى بوابة المطوّرين

صادِق للحصول على رمز جلسة (POST /auth/login).

أنشئ مؤسسة ومشروعًا

POST /developer/organizations، ثم POST /developer/organizations/{id}/projects.

أصدر مفتاح API

POST /developer/api-keys. تتضمّن الاستجابة المفتاح بنصّه الصريح مرّة واحدة فقط — انسخه الآن.

يبدو المفتاح هكذا:

nvvo_3f9c2a1e8b7d6c5f4a3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b

يُعرَض المفتاح بنصّه الصريح فقط في استجابة الإنشاء. تخزّن Navvo تجزئة منه فحسب — إذا فقدته، أصدر مفتاحًا جديدًا.

2. نفّذ أول طلب لك

أرسل المفتاح في ترويسة x-api-key. إليك بحثًا عن أماكن حول عمّان:

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

const res = await fetch(
  "https://navvo.io/api/v1/search?" + new URLSearchParams({ q: "coffee in Abdoun" }),
  { headers: { "x-api-key": "nvvo_YOUR_KEY" } }
);
const data = await res.json();
console.log(data.places.items);

import requests

res = requests.get(
    "https://navvo.io/api/v1/search",
    params={"q": "coffee in Abdoun"},
    headers={"x-api-key": "nvvo_YOUR_KEY"},
)
res.raise_for_status()
print(res.json()["places"]["items"])

استجابة ناجحة (مقتطعة):

{
  "query": "coffee in Abdoun",
  "locale": "en",
  "places": {
    "items": [
      {
        "id": "b1f3c2a0-1234-4abc-9def-0123456789ab",
        "slug": "rumi-cafe-abdoun",
        "nameEn": "Rumi Cafe",
        "nameAr": "مقهى رومي",
        "categories": ["cafe", "coffee-shop"],
        "rating": 4.7,
        "sponsored": true,
        "center": "POINT(35.8806 31.9461)"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 25
  }
}

تعود إحداثيات المكان كسلسلة نقطة بصيغة WKT، POINT(<lng> <lat>) — خط الطول أولًا. تختلف مواصفات الإحداثيات حسب نقطة النهاية؛ راجع المواصفات.

3. أضف خريطة (اختياري)

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

<link href="https://docs.navvo.io/navvo-maps/navvo-maps.css" rel="stylesheet" />
<script src="https://docs.navvo.io/navvo-maps/navvo-maps.js"></script>
<div id="map" style="height: 420px;"></div>
<script>
  const map = new NavvoMaps.Map({
    container: "map",
    style: "https://navvo.io/api/v1/tiles/style?style=standard&api_key=nvvo_YOUR_KEY",
    center: [35.91, 31.95], // [lng, lat] — Amman
    zoom: 12,
  });
</script>

راجع دليل عرض خريطة للاطّلاع على الشرح الكامل.

4. الخطوات التالية

المصادقة والمفاتيح

النطاقات، وإدارة المفاتيح، وتدفّق بيانات الاعتماد الكامل.

المواصفات

ترتيب الإحداثيات، وصيغة bbox، والبلاطات، والتصفيح، وأنواع المحتوى.

حدود المعدّل

الحصص لكل مفتاح ولكل عنوان IP، والخطط، وكيفية سلوك التقييد.

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

كل نقطة نهاية ومعامل وشكل استجابة.

مقدمة

ما هي واجهة Navvo البرمجية، ولمن هي موجّهة، وما الذي يمكنك بناؤه بها.

المصادقة

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