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

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

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

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

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

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

طلبات الخريطة لا يمكنها إرسال ترويسات. المتصفحات تجلب روابط النمط/البلاطة/المحارف/الصور المركَّبة مباشرةً ولا يمكنها إرفاق ترويسة x-api-key. مرِّر المفتاح كمعامل استعلام على رابط النمط: ?api_key=nvvo_YOUR_KEY.
بدون مفتاح API؟ الخريطة عليها علامة مائية. بدون مفتاح API، تُعرَض خريطة الأساس مع علامة مائية "Navvo Map Developer (Provide Your API Key)" مكرَّرة عبر كل بلاطة على خلفية داكنة شبه شفافة. مرِّر مفتاح api_key (كمعامل استعلام على رابط النمط، أو apiKey في الـ SDK) للحصول على خريطة نظيفة بلا علامة مائية.

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.

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

style
string
أحد القيم: standard (افتراضي)، أو road (اسم بديل لـ standard)، أو positron، أو dark، أو satellite، أو terrain، أو 3d. القائمة الكاملة بالتسميات في GET /tiles/styles. القيم غير المعروفة تُعيد 400.
version
string
وسم تجميلي فقط — يصبح اسم النمط name.
terrain
string
1/true لتضمين مصدر تضاريس الارتفاع في نمط 3d (عند توفره).
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. أنت لا تطلب هذه مباشرةً؛ بل يحمِّلها العارض تلقائيًا من النمط:

{
  "version": 8,
  "name": "Navvo standard",
  "sources": {
    "navvo": { "type": "vector", "url": "https://navvo.io/api/v1/tiles/tilejson/navvo", "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 نمطان نقطيان يشير مصدرهما الوحيد إلى نقطة نهاية البلاطات النقطية.

الأنماط standard/dark/positron/3d متجهية؛ بينما satellite/terrain نقطية. استخدم /tiles/style كنقطة دخول وحيدة — ويتولى Navvo Maps حل البقية.
المباني. في الأنماط المتجهية غير 3d (standard/dark/positron)، تُعرض المباني كـأشكال ثنائية الأبعاد مسطّحة عبر طبقة building من نوع fill، وهي مرئية افتراضيًا لكنها تظهر فقط عند التقريب (minzoom ≈ 15.5). لا يُرفع أي شيء — تبقى المخططات مسطّحة حتى عند إمالة الكاميرا (مثلًا أثناء الملاحة).لـرفع المباني إلى ثلاثية الأبعاد على تلك الأنماط، أضِف طبقة fill-extrusion خاصة بك فوق طبقة المصدر نفسها:
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(...))
يتضمّن نمط 3d المخصّص هذه الطبقة المرفوعة (navvo-3d-buildings) جاهزةً مع كاميرا مائلة — استخدمه عندما تريد مبانيَ ثلاثية الأبعاد جاهزة.
التخزين المؤقت. تُرسَل استجابات /tiles/style مع الترويسة Cache-Control: public, max-age=300, stale-while-revalidate=86400. لذا يمكن إعادة استخدام مستند النمط لمدة 5 دقائق (ويُقدَّم بصيغة stale-while-revalidate حتى يوم كامل)، ما يسمح للمُصيِّر أو عامل الخدمة (service worker) أو شبكة CDN بتخزينه مؤقتًا عبر عمليات إعادة التحميل بدل جلبه في كل مرة تُفتح فيها الخريطة. تظهر تعديلات النمط خلال ~5 دقائق.
الضغط. تُضغَط البلاطات المتجهية والخطوط (glyphs) وملف السبرايت JSON وبلاطات تغطية/إشارات/نقاط Mapillary باستخدام gzip (Content-Encoding: gzip) عندما يرسل طلبك Accept-Encoding: gzip — وهو ما يفعله كل متصفح وكل عميل HTTP قياسي (ومُصيِّر Navvo) تلقائيًا، مع فك الضغط بشفافية عند الاستلام. يقلّل ذلك حجم نقل بلاطات التغطية إلى النصف تقريبًا وبلاطات المتجهات بنحو 35%. أما البلاطات النقطية/الصور (PNG/JPEG) فهي مضغوطة أصلًا وتُقدَّم كما هي. تحمل الاستجابات Vary: Accept-Encoding كي يخزّن أي وسيط تخزين النسخة الصحيحة.

الإسناد

يقدِّم Navvo خريطة الأساس بالكامل بنفسه — لا توجد أي طلبات وقت تشغيل لأي مزوِّد خارجي. تحمل استجابات خريطة أساس Navvo إسناد © Navvo. اعرض إسناد Navvo؛ ولا يلزم أي إسناد لطرف ثالث في تطبيقك.

  • خريطة الأساس وصور الأقمار الصناعية/الصور: © Navvo. أبقِ عنصر التحكم المُصغَّر بالإسناد على الخريطة ظاهرًا — تعرضه حِزم Navvo SDK افتراضيًا.
  • تُعيد GET /map/config كائن attribution لتتمكن من عرض إسناد Navvo في واجهة مخصصة إذا بنيت سطح إسناد خاصًا بك.

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

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

نقطة النهايةتُعيد
GET /tiles/vector/navvo/planet/{z}/{x}/{y}.pbfبلاطة متجهية واحدة (protobuf)، application/x-protobuf. عادةً ما يكون المقطع بعد navvo بقيمة planet؛ ويُقبَل امتداد .pbf على {y}. مُخزَّنة مؤقتًا public, max-age=86400.
GET /tiles/tilejson/navvoفهرس البلاطات المتجهية (TileJSON) الذي تشير إليه الأنماط المتجهية كرابط url لمصدرها — قالب البلاطة، مدى التكبير، والطبقات المتجهية.
GET /tiles/raster/{source}/{z}/{x}/{y}.pngبلاطة نقطية واحدة (PNG/JPEG). source ∈ standard, dark, satellite, terrain, navvo-natural-earth.
GET /tiles/glyphs/navvo/{fontstack}/{range}.pbfنطاقات محارف الخطوط (.pbf) التي يشير إليها glyphs في النمط.
GET /tiles/sprites/navvo/spriteالرابط الأساسي لأطلس الصور المركَّبة؛ يُلحِق العارض .json (الفهرس) و.png و@2x.png (الصور).
قيم {source} النقطية: standard/dark أساس محايد نظيف، وsatellite صور Navvo بالأقمار الصناعية، وterrain ارتفاع مُظلَّل، وnavvo-natural-earth أساس عالمي بتكبير منخفض. كل الموارد الفرعية يقدِّمها Navvo بالكامل — لا يحتوي النمط على أي أسماء مزوِّدين خارجيين ولا يجري أي طلبات وقت التشغيل خارج Navvo.

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

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

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",
    "satelliteRaster": "/api/v1/tiles/raster/satellite/{z}/{x}/{y}.png"
  }
}
للحصول على طبقات الخريطة العلوية (حركة المرور، الحوادث، الطقس، النقل العام، مناطق اللوجستيات) وبيان إعداد الخريطة الكامل، انظر بيانات الخريطة والمخاطر.

بلاطات الارتفاعات (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": "…",
  "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 }
}

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

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

لا تحتاج عادةً إلى وصل DEM يدوياً: طلب GET /tiles/style?style=3d&terrain=1 يعيد نمطاً يحمل مصدر navvo-terrain-dem ومعه معاملات فك الترميز الدقيقة — عوامل الترميز المخصّص (redFactor، greenFactor، blueFactor، baseShift، أي elevation = baseShift + R·redFactor + G·greenFactor + B·blueFactor) — بالإضافة إلى terrain.exaggeration مضبوط. استخدم النمط وسيفكّ العارض ترميز الارتفاع تلقائياً.

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

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

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

center
string required
lat,lng — مركز الخريطة (لاحظ: خط العرض أولاً).
zoom
number
تكبير 1–19. الافتراضي 13.
size
string
WxH بالبكسل، كل ضلع 64–1280. الافتراضي 600x400.
markers
string
دبابيس مفصولة بفاصلة منقوطة: lat,lng;lat,lng;…. يُرسم كل منها كدبوس Navvo.
style
string
standard (الافتراضي)، dark، satellite، أو terrain.
format
string
احذفه لصيغة SVG (الافتراضية — حادّة عند أي مقياس). وpng يعيد PNG نقطية حقيقية — استخدمها لـog:image / معاينات المشاركة الاجتماعية، لأن زواحف المواقع لا تعرض SVG.
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&format=png" \
  -H "x-api-key: $NAVVO_API_KEY" -o preview.png

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

القياسات

إرسال رحلات مجهولة لتحسين حركة المرور، وقراءة بيانات حركة المرور المجمَّعة.

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

إعداد الخريطة، أنماط الفئات، الطبقات العلوية، الطقس، وتقييم مخاطر المسار المراعي للأحوال.

Copyright © 2026