بلاطات الخريطة والأنماط

خريطة أساس متكاملة من المصدر الأول يقدِّمها Navvo Maps. وجِّه عارض Navvo Maps إلى رابط نمط وكل شيء آخر — البلاطات المتجهية، المحارف، الصور المركَّبة، التظليل الجبلي، بلاطات الارتفاعات — يقدِّمه Navvo. والاستثناء الوحيد هو الصور الجوية في نمط satellite: فهي صور مرخّصة من طرف ثالث، ويجلبها المتصفح مباشرةً من شبكة توصيل المحتوى الخاصة بمزوِّد الصور لا من نطاق navvo.io، ولذلك يلزم عرض إسناد المزوِّد إلى جانب إسناد Navvo — انظر الإسناد.

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

GET /tiles/styles

كتالوج أنماط الخريطة المتاحة — لبناء مُبدِّل أنماط. قيمة style لكل عنصر هي ما تمرّره إلى GET /tiles/style?style=؛ وcategory هي base أو imagery.

curl -s "https://navvo.io/api/v1/tiles/styles" -H "x-api-key: $NAVVO_API_KEY"

{
  "provider": "navvo-tiles", "count": 6, "styleUrl": "/tiles/style?style={style}",
  "styles": [
    { "style": "standard", "label": "Standard", "category": "base", "description": "The default road map." },
    { "style": "positron", "label": "Light", "category": "base", "description": "Minimal light basemap." },
    { "style": "dark", "label": "Dark", "category": "base", "description": "Night/dark basemap." },
    { "style": "satellite", "label": "Satellite", "category": "imagery", "description": "Aerial/satellite imagery." },
    { "style": "3d", "label": "3D Buildings", "category": "base", "description": "3D building extrusions (supports ?terrain=1)." },
    { "style": "terrain", "label": "Terrain", "category": "imagery", "description": "Shaded-relief terrain." }
  ]
}

GET /tiles/style

تُعيد مستند نمط Navvo Maps كاملًا (مواصفة النمط المتجهي القياسية، الإصدار v8) لنمط مُسمّى. هذا هو الرابط الذي تعطيه لـ عارض Navvo Maps.

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

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],
  zoom: 12,
});

يشير النمط المُعاد إلى موارد فرعية مستضافة لدى Navvo (المحارف، الصور المركَّبة، وقالب البلاطات المتجهية) — كلها يقدِّمها Navvo. أنت لا تطلب هذه مباشرةً؛ بل يحمِّلها العارض تلقائيًا من النمط.

يحمل المصدر المتجهي قالب البلاطات مباشرةً (tiles) بدل url يشير إلى مستند TileJSON. هذا يحذف رحلة ذهاب وإياب كاملة قبل إمكانية طلب أول بلاطة، ما يسرّع تحميل الخريطة البارد بشكل ملموس. ولا يزال GET /tiles/tilejson/navvo مُتاحًا لمن يفضّل حلّ الفهرس بنفسه:

{
  "version": 8,
  "name": "Navvo standard",
  "sources": {
    "navvo": {
      "type": "vector",
      "tiles": ["https://navvo.io/api/v1/tiles/vector/navvo/planet/{z}/{x}/{y}.pbf?v=<version>"],
      "minzoom": 0, "maxzoom": 14,
      "attribution": "© Navvo"
    }
  },
  "layers": [
    { "id": "background", "type": "background", "paint": { "background-color": "#FAFBFC" } },
    { "id": "water", "type": "fill", "source": "navvo", "source-layer": "water", "paint": { "fill-color": "#D8E7FF" } }
  ],
  "metadata": { "navvoStyle": "standard", "navvoAttribution": "© Navvo" }
}

نمطا satellite وterrain ليسا نمطين نقطيين أحاديّي المصدر، بل هجينان: طبقة نقطية سفلية يعلوها مصدر Navvo المتجهي نفسه.

• satellite — طبقة الصور الجوية النقطية (معرّف المصدر satellite) في الأسفل، وفوقها مصدر Navvo المتجهي (navvo) الذي يرسم الطرق وأسماء الشوارع وتسميات الأماكن، مع glyphs وsprite من Navvo. يعيد الطلب المُوثَّق ‏مصدرين و75 طبقة: طبقة خلفية واحدة، وطبقة satellite نقطية واحدة، و73 طبقة من navvo.
• terrain — طبقة التظليل الجبلي النقطية التي تستضيفها Navvo (معرّف المصدر ne2_shaded، maxzoom يساوي 6) تحت مصدر Navvo المتجهي الكامل (navvo). يعيد الطلب المُوثَّق ‏مصدرين و110 طبقات، بلا أي مضيف خارجي وبلا مصدر ارتفاعات (DEM).

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

map.addLayer({
  id: 'buildings-3d', type: 'fill-extrusion',
  source: 'navvo', 'source-layer': 'building', minzoom: 15.5,
  paint: {
    'fill-extrusion-color': '#cfd5e0',
    'fill-extrusion-height': ['coalesce', ['get', 'render_height'], ['get', 'height'], 6],
    'fill-extrusion-base': ['coalesce', ['get', 'render_min_height'], ['get', 'min_height'], 0],
  },
});
// (لا تظهر البثوق ثلاثية الأبعاد إلا عند إمالة الكاميرا — استخدم map.setPitch(...))

الإسناد

يستضيف Navvo خريطة الأساس بنفسه — البلاطات المتجهية والمحارف والصور المركَّبة وخلفية التظليل الجبلي وبلاطات الارتفاعات (DEM) — وكلها تحمل إسناد © Navvo.

• أنماط الأساس (standard، dark، positron، 3d، terrain): يكفي إسناد © Navvo، ولا يلزم أي إسناد لطرف ثالث. أبقِ عنصر التحكم المُصغَّر بالإسناد على الخريطة ظاهرًا — تعرضه حِزم Navvo SDK افتراضيًا.
• نمط satellite: الصور الجوية فيه صور مرخّصة من طرف ثالث، ويشير مصدرها مباشرةً إلى شبكة توصيل المحتوى الخاصة بمزوِّد الصور. لذلك يحمل هذا المصدر إسناد المزوِّد Imagery © Esri, Maxar, Earthstar Geographics إضافةً إلى © Navvo، ويجب عرض الإسنادَين معًا. يقوم عنصر التحكم بالإسناد في عارض Navvo بذلك تلقائيًا انطلاقًا من مستند النمط نفسه، فلا حاجة إلى كتابة النص يدويًا ما دمت تستخدم العارض.
• تُعيد GET /map/config كائن attribution لواجهات الإسناد المخصّصة — لكن انتبه إلى أنّ قيمة satellite فيه هي © Navvo وليست إسناد مزوّد الصور. لذا يجب على أي سطح إسناد مخصّص أن يقرأ إسناد الصور من حقل attribution الخاص بمصدر satellite داخل مستند النمط، وإلا فسيُسقط إسنادًا واجبًا تعاقديًا.

ماذا تعرض الخريطة الأساسية

الخريطة الأساسية جغرافيا لا دليل أعمال: شوارع ومبانٍ واستعمالات أراضٍ ومياه وحدائق وأسماء أماكن إدارية. ولا تحمل أي متاجر أو مطاعم أو عيادات أو فنادق أو مكاتب أو بنوك أو مواقف نقل.

وهذا مفروض في بيانات البلاطة لا في النمط. فطبقة poi القادمة من المصدر تُزال من كل بلاطة متجهية قبل تقديمها، فتغيب أيًّا كان النمط الذي يرسمها — نمطنا، أو نمط كتبته بنفسك، أو نمط طرف ثالث جاهز توجّهه إلى بلاطاتنا. والنمط الذي يشير إلى source-layer: "poi" لن يرسم شيئًا ببساطة.

والأماكن الوحيدة التي يعرضها نافّو هي التي في كتالوج نافّو نفسه، ولا تُرسم على الخريطة الأساسية تلقائيًا أبدًا. اطلبها فتظهر:

اعرض النتائج كعلامات خاصة بك فوق الخريطة. فلا يظهر شيء لم تطلبه، وهذا يعني أيضًا أن لقطة الخريطة الأساسية مستقرّة: لا تتغيّر لأن أحدهم عدّل مسحًا خارجيًا.

مصادر البلاطات

تدعم نقاط النهاية هذه الأنماط المذكورة أعلاه. يطلبها العارض نيابةً عنك عند تحميل النمط — وعادةً لا تستدعيها يدويًا. وهي مدرجة للاكتمال وللعارضات المتقدمة/المخصصة.

يمكنك أيضًا توصيل مصدر نقطي مباشرةً:

map.addSource("nav-sat", {
  type: "raster",
  tiles: ["https://navvo.io/api/v1/tiles/raster/satellite/{z}/{x}/{y}.png"],
  tileSize: 256,
  maxzoom: 19,
  attribution: "© Navvo · Imagery © Esri, Maxar, Earthstar Geographics",
});

يوصل هذا المقطع المسار الذي ينقله Navvo للصور (مفيد إن احتجت مسارًا من الأصل نفسه)، بينما يشير النمط الافتراضي /tiles/style?style=satellite مباشرةً إلى شبكة توصيل المحتوى الخاصة بمزوِّد الصور للحصول على زمن استجابة أقل. وفي كلتا الحالتين يبقى إسناد الصور مطلوبًا، ولهذا يظهر في attribution أعلاه.

GET /tiles/layers

فهرس اكتشاف صغير للطبقات المنطقية المتاحة، وروابط الأنماط، وقوالب البلاطات النقطية.

{
  "layers": ["administrative", "water", "buildings", "roads", "poi", "places"],
  "styles": {
    "standard": "/api/v1/tiles/style?style=standard",
    "dark": "/api/v1/tiles/style?style=dark",
    "satellite": "/api/v1/tiles/style?style=satellite",
    "terrain": "/api/v1/tiles/style?style=terrain"
  },
  "tileProxy": {
    "standardRaster": "/api/v1/tiles/raster/standard/{z}/{x}/{y}.png",
    "darkRaster": "/api/v1/tiles/raster/dark/{z}/{x}/{y}.png",
    "satelliteRaster": "/api/v1/tiles/raster/satellite/{z}/{x}/{y}.png",
    "terrainRaster": "/api/v1/tiles/raster/terrain/{z}/{x}/{y}.png"
  },
  "timeMachine": {
    "template": "/api/v1/tiles/gibs/{layer}/{z}/{x}/{y}?date={date}",
    "defaultDate": "2026-07-25",
    "layers": [
      { "key": "truecolor", "label": "True color (morning)", "maxZoom": 9 },
      { "key": "truecolor-aqua", "label": "True color (afternoon)", "maxZoom": 9 },
      { "key": "truecolor-viirs", "label": "True color (hi-res)", "maxZoom": 9 },
      { "key": "snow", "label": "Snow cover", "maxZoom": 8 },
      { "key": "aerosol", "label": "Aerosol / dust", "maxZoom": 6 }
    ]
  }
}

GET /tiles/cache/status

خلافًا لبقية هذه الصفحة، لا يحتاج هذا الطلب إلى مفتاح API.

لقطة للقراءة فقط عن حالة ذاكرة Navvo المؤقتة للبلاطات على الخادم — مفيدة لتشخيص بطء تحميل البلاطات ومعرفة ما إذا كان الطلب يُخدَم من المخزن المؤقت أم يُبنى من جديد. القيم إخبارية فقط وقد تتغيّر، فلا تبنِ عليها منطق تطبيقك.

curl -s "https://navvo.io/api/v1/tiles/cache/status"

تتضمّن الاستجابة:

• strategy — معرّف الاستراتيجية المستخدَمة.
• memory — طبقة الذاكرة: entries (عدد البلاطات المخزَّنة)، bytes (الحجم المستهلك)، maxBytes (السقف)، ttlSeconds (مدة الصلاحية).
• disk — طبقة القرص: enabled، maxBytes، ttlSeconds.
• inflight — عدد الطلبات الجارية حاليًا نحو المنبع.
• metrics — عدّادات تراكمية: memoryHits، diskHits، misses، inflightJoins، upstreamErrors.
• policies — سياسة التخزين المؤقّت التي يستقرّ عليها كل صنف من البلاطات.
• warming — حالة التسخين المسبق للبلاطات: active، runs، requested، completed، failed، إضافةً إلى أوقات آخر تشغيل ومدّته.

آلة الزمن للصور الفضائية (Satellite Time-Machine)

صور فضائية مؤرَّخة ومتعدّدة الطبقات، منقولة عبر Navvo ومنزوعة العلامات التجارية للمصدر. اطلب أي طبقة مسجَّلة عند أي تاريخ.

GET /tiles/gibs/{layer}/{z}/{x}/{y}?date=YYYY-MM-DD

الطبقات: truecolor، truecolor-aqua، truecolor-viirs، snow، aerosol (الغبار/جودة الهواء). راجع GET /tiles/layers → timeMachine للحصول على السجلّ الحيّ والتاريخ الافتراضي. حذف date يستخدم تاريخًا يسبق اليوم بيومين تقريبًا (لا يوجد بحث عن أحدث صورة متاحة)؛ وGET /tiles/layers ← timeMachine.defaultDate هو المرجع الموثوق.

بلاطات الارتفاعات (DEM)

بلاطات ارتفاعات تستضيفها Navvo (raster-dem) — المصدر خلف التضاريس ثلاثية الأبعاد (/tiles/style?style=3d&terrain=1) والتظليل الجبلي. التغطية هي الأردن؛ والبلاطات خارج حدود التغطية تعيد 404 (عامل ذلك على أنه «مسطّح»، لا خطأ).

GET /terrain/tilejson

واصف مجموعة بلاطات DEM بصيغة (TileJSON): قالب البلاطة، مدى التكبير، الحدود، وترميز الارتفاع encoding.

curl -s "https://navvo.io/api/v1/terrain/tilejson" -H "x-api-key: $NAVVO_API_KEY"

{
  "tilejson": "2.2.0", "name": "Navvo Jordan terrain", "scheme": "xyz",
  "type": "raster-dem", "format": "png",
  "encoding": "custom", "redFactor": 6553.6, "greenFactor": 25.6, "blueFactor": 0.1, "baseShift": -10000,
  "attribution": "© Navvo",
  "minzoom": 0, "maxzoom": 14, "bounds": [34.88, 29.12, 39.32, 33.38],
  "tiles": ["/api/v1/terrain/tiles/{z}/{x}/{y}.png"],
  "metadata": { "license": "ODbL", "generatedAt": "…", "tileCount": 61968 }
}

يستخدم نموذج الارتفاعات الرقمي (DEM) ترميزاً مخصّصاً (custom). فُكّ ترميز كل بكسل من البلاطة إلى أمتار عبر:

elevation_m = -10000 + R·6553.6 + G·25.6 + B·0.1

أي elevation = baseShift + R·redFactor + G·greenFactor + B·blueFactor. ويطبّق عارض Navvo Maps هذه العوامل نيابةً عنك (انظر الملاحظة أدناه)؛ ولا تحتاج إلى فكّ الترميز يدوياً إلّا لمسارات معالجة أصلية مخصّصة.

GET /terrain/tiles/{z}/{x}/{y}.png

بلاطة ارتفاع واحدة (PNG بترميز RGB للارتفاع). مخزّنة public, max-age=604800, immutable. البلاطات خارج الحدود أو غير المبنية → 404.

صور الخرائط الثابتة

يعرض GET /tiles/static صورة خريطة غير تفاعلية — للرسائل البريدية والإيصالات ومعاينات الدردشة وبطاقات المشاركة الاجتماعية. لا حاجة لعارض؛ ضع الرابط مباشرةً في <img> أو في og:image. وتُعيد PNG افتراضياً.

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

curl -s "https://navvo.io/api/v1/tiles/static?center=31.9539,35.9106&zoom=14&size=600x400&markers=31.9539,35.9106&style=standard" \
  -H "x-api-key: $NAVVO_API_KEY" -o preview.png

الاستجابات مخزّنة (Cache-Control: public, max-age=3600) وتحمل شريط إسناد © Navvo مدموجاً في الصورة. النطاق: tiles.