api/templates/main/bing-api-guide.html.twig

597 lines
32 KiB
Twig
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

{% extends 'base.html.twig' %}
{% block title %}راهنمای API تایل‌های Bing | می‌مپس{% endblock %}
{% block description %}راهنمای کامل استفاده از API تایل‌های Bing می‌مپس - نحوه استفاده با Leaflet، OpenLayers و مثال‌های عملی با سیستم کش و محدودیت جغرافیایی ایران{% endblock %}
{% block keywords %}API Bing, تایل Bing, نقشه Bing, Leaflet Bing, OpenLayers Bing, کش تایل Bing, API نقشه Bing{% endblock %}
{% block og_title %}راهنمای API تایل‌های Bing می‌مپس{% endblock %}
{% block og_description %}راهنمای کامل استفاده از API تایل‌های Bing می‌مپس با سیستم کش و محدودیت به ایران{% endblock %}
{% block body %}
<!-- Hero Section -->
<section class="hero-section text-white">
<div class="container">
<div class="text-center">
<h1 class="display-4 fw-bold mb-4">
راهنمای API تایل‌های Bing
<span class="d-block">سرویس می‌مپس</span>
</h1>
<p class="lead opacity-90">
دسترسی سریع و پایدار به تایل‌های Bing Maps با کش خودکار و محدودیت جغرافیایی ایران
</p>
</div>
</div>
</section>
<!-- Table of Contents -->
<section class="py-5 bg-light">
<div class="container">
<div class="card border-0 shadow-sm">
<div class="card-body p-4">
<h2 class="h3 fw-bold mb-4">فهرست مطالب</h2>
<div class="row g-3">
<div class="col-lg-4 col-md-6">
<a href="#introduction" class="text-decoration-none">
<div class="card h-100 border-0 shadow-sm hover-card">
<div class="card-body text-center p-3">
<div class="bg-primary text-white rounded-circle d-inline-flex align-items-center justify-content-center mb-2" style="width: 40px; height: 40px;">
<span class="fw-bold">1</span>
</div>
<h6 class="card-title mb-0 text-dark">معرفی API</h6>
</div>
</div>
</a>
</div>
<div class="col-lg-4 col-md-6">
<a href="#features" class="text-decoration-none">
<div class="card h-100 border-0 shadow-sm hover-card">
<div class="card-body text-center p-3">
<div class="bg-success text-white rounded-circle d-inline-flex align-items-center justify-content-center mb-2" style="width: 40px; height: 40px;">
<span class="fw-bold">2</span>
</div>
<h6 class="card-title mb-0 text-dark">ویژگی‌ها</h6>
</div>
</div>
</a>
</div>
<div class="col-lg-4 col-md-6">
<a href="#endpoint" class="text-decoration-none">
<div class="card h-100 border-0 shadow-sm hover-card">
<div class="card-body text-center p-3">
<div class="bg-warning text-white rounded-circle d-inline-flex align-items-center justify-content-center mb-2" style="width: 40px; height: 40px;">
<span class="fw-bold">3</span>
</div>
<h6 class="card-title mb-0 text-dark">نقطه پایانی</h6>
</div>
</div>
</a>
</div>
<div class="col-lg-4 col-md-6">
<a href="#layers" class="text-decoration-none">
<div class="card h-100 border-0 shadow-sm hover-card">
<div class="card-body text-center p-3">
<div class="bg-info text-white rounded-circle d-inline-flex align-items-center justify-content-center mb-2" style="width: 40px; height: 40px;">
<span class="fw-bold">4</span>
</div>
<h6 class="card-title mb-0 text-dark">انواع لایه‌ها</h6>
</div>
</div>
</a>
</div>
<div class="col-lg-4 col-md-6">
<a href="#iran-restriction" class="text-decoration-none">
<div class="card h-100 border-0 shadow-sm hover-card">
<div class="card-body text-center p-3">
<div class="bg-secondary text-white rounded-circle d-inline-flex align-items-center justify-content-center mb-2" style="width: 40px; height: 40px;">
<span class="fw-bold">5</span>
</div>
<h6 class="card-title mb-0 text-dark">محدودیت ایران</h6>
</div>
</div>
</a>
</div>
<div class="col-lg-4 col-md-6">
<a href="#examples" class="text-decoration-none">
<div class="card h-100 border-0 shadow-sm hover-card">
<div class="card-body text-center p-3">
<div class="bg-dark text-white rounded-circle d-inline-flex align-items-center justify-content-center mb-2" style="width: 40px; height: 40px;">
<span class="fw-bold">6</span>
</div>
<h6 class="card-title mb-0 text-dark">مثال‌های عملی</h6>
</div>
</div>
</a>
</div>
<div class="col-lg-4 col-md-6">
<a href="#cache" class="text-decoration-none">
<div class="card h-100 border-0 shadow-sm hover-card">
<div class="card-body text-center p-3">
<div class="bg-primary text-white rounded-circle d-inline-flex align-items-center justify-content-center mb-2" style="width: 40px; height: 40px;">
<span class="fw-bold">7</span>
</div>
<h6 class="card-title mb-0 text-dark">سیستم کش</h6>
</div>
</div>
</a>
</div>
</div>
</div>
</div>
</div>
</section>
<!-- Introduction Section -->
<section id="introduction" class="py-5">
<div class="container">
<div class="row justify-content-center">
<div class="col-lg-8">
<div class="text-center mb-5">
<h2 class="display-5 fw-bold text-gradient mb-3">دسترسی به تایل‌های Bing از طریق می‌مپس</h2>
<p class="lead text-muted">
سرویس می‌مپس تایل‌های Bing Maps را با کش خودکار و محدودیت جغرافیایی به ایران ارائه می‌دهد
</p>
</div>
<div class="card border-0 shadow-sm mb-4">
<div class="card-body p-4">
<div class="alert alert-info mb-4">
<h5 class="alert-heading">چرا API Bing می‌مپس؟</h5>
<ul class="mb-0 mt-2">
<li>🇮🇷 <strong>محدود به ایران:</strong> تایل‌ها فقط برای محدوده ایران از Bing دریافت می‌شوند؛ خارج از ایران تایل سفید بدون درخواست به سرور</li>
<li>⚡ <strong>سرعت با کش:</strong> تایل‌های یک‌بار دریافت‌شده در کش ذخیره و در درخواست‌های بعدی از سرور داخلی سرو می‌شوند</li>
<li>📦 <strong>کاهش درخواست به Bing:</strong> پس از کش شدن، دیگر نیازی به درخواست به سرورهای Bing نیست</li>
<li>🔒 <strong>کلید اختیاری:</strong> می‌توانید با تنظیم BING_MAPS_KEY از Bing Maps Portal استفاده رسمی کنید</li>
</ul>
</div>
<div class="alert alert-success">
<h5 class="alert-heading">مزایای سرویس</h5>
<ul class="mb-0 mt-2">
<li>✅ <strong>سرور داخل کشور:</strong> سرو تایل از اینترنت داخلی</li>
<li>✅ <strong>کش خودکار:</strong> ذخیره تایل‌ها و بازگردانی در درخواست‌های بعدی</li>
<li>✅ <strong>لایه‌های جاده، ماهواره و ترکیبی:</strong> سازگار با استاندارد XYZ</li>
<li>✅ <strong>پشتیبانی CORS:</strong> استفاده مستقیم از مرورگر و فریمورک‌های وب</li>
</ul>
</div>
</div>
</div>
</div>
</div>
</div>
</section>
<!-- Features Section -->
<section id="features" class="py-5 bg-light">
<div class="container">
<div class="text-center mb-5">
<h2 class="display-5 fw-bold text-gradient mb-3">ویژگی‌های کلیدی</h2>
<p class="lead text-muted">
کش، محدودیت ایران و سازگاری با کتابخانه‌های نقشه
</p>
</div>
<div class="row g-4">
<div class="col-lg-6">
<div class="card h-100 border-0 shadow-sm">
<div class="card-header bg-success text-white">
<h5 class="mb-0">⚡ کش و سرعت</h5>
</div>
<div class="card-body">
<p class="card-text">
تایل‌های داخل ایران یک‌بار از Bing دریافت و در کش ذخیره می‌شوند. درخواست‌های بعدی همان تایل از کش پاسخ داده می‌شوند و به Bing ارسال نمی‌شوند.
</p>
</div>
</div>
</div>
<div class="col-lg-6">
<div class="card h-100 border-0 shadow-sm">
<div class="card-header bg-primary text-white">
<h5 class="mb-0">🇮🇷 محدودیت ایران</h5>
</div>
<div class="card-body">
<p class="card-text">
فقط تایل‌هایی که با محدوده جغرافیایی ایران تلاقی دارند از Bing گرفته می‌شوند. برای نواحی خارج از ایران یک تایل کاملاً سفید برگردانده می‌شود و هیچ درخواستی به Bing ارسال نمی‌شود.
</p>
</div>
</div>
</div>
<div class="col-lg-6">
<div class="card h-100 border-0 shadow-sm">
<div class="card-header bg-warning text-dark">
<h5 class="mb-0">🗺️ لایه‌های Bing</h5>
</div>
<div class="card-body">
<p class="card-text">
سه لایه در دسترس: <strong>road</strong> (نقشه جاده)، <strong>aerial</strong> (ماهواره)، <strong>hybrid</strong> (ترکیب ماهواره و برچسب‌ها). زوم از ۱ تا ۲۳.
</p>
</div>
</div>
</div>
<div class="col-lg-6">
<div class="card h-100 border-0 shadow-sm">
<div class="card-header bg-info text-white">
<h5 class="mb-0">💡 سازگاری</h5>
</div>
<div class="card-body">
<p class="card-text">
URL به صورت استاندارد XYZ (<code>{z}/{x}/{y}</code>) است و با Leaflet، OpenLayers و سایر کتابخانه‌های نقشه سازگار است.
</p>
</div>
</div>
</div>
</div>
</div>
</section>
<!-- Endpoint Section -->
<section id="endpoint" class="py-5">
<div class="container">
<div class="text-center mb-5">
<h2 class="display-5 fw-bold text-gradient mb-3">نقطه پایانی API</h2>
<p class="lead text-muted">
آدرس و پارامترهای API تایل‌های Bing
</p>
</div>
<div class="row g-4">
<div class="col-lg-8 mx-auto">
<div class="card border-0 shadow-sm">
<div class="card-header bg-primary text-white">
<h5 class="mb-0">نقطه پایانی دریافت تایل</h5>
</div>
<div class="card-body">
<div class="bg-dark text-light p-4 rounded text-end" dir="ltr">
<strong>URL:</strong><br>
<code class="text-info">https://memaps.ir/api/bing/{layer}/{z}/{x}/{y}.{ext}</code><br><br>
<strong>Method:</strong><br>
<code class="text-success">GET</code><br><br>
<strong>Content-Type:</strong><br>
<code class="text-warning">image/png</code> (لایه road) یا <code class="text-warning">image/jpeg</code> (لایه‌های aerial و hybrid)
</div>
<div class="mt-4">
<h6 class="fw-bold mb-3">پارامترهای URL:</h6>
<div class="table-responsive">
<table class="table table-striped">
<thead class="table-dark">
<tr>
<th>پارامتر</th>
<th>توضیح</th>
<th>مثال</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>{layer}</code></td>
<td>نوع لایه: road، aerial، hybrid</td>
<td><code>road</code></td>
</tr>
<tr>
<td><code>{z}</code></td>
<td>سطح زوم (۱ تا ۲۳)</td>
<td><code>10</code></td>
</tr>
<tr>
<td><code>{x}</code></td>
<td>مختصات X تایل</td>
<td><code>512</code></td>
</tr>
<tr>
<td><code>{y}</code></td>
<td>مختصات Y تایل</td>
<td><code>512</code></td>
</tr>
<tr>
<td><code>{ext}</code></td>
<td>پسوند: png (برای road) یا jpg/jpeg (برای aerial و hybrid)</td>
<td><code>png</code> / <code>jpg</code></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="mt-4">
<h6 class="fw-bold mb-3">مثال‌های URL:</h6>
<pre class="bg-light p-3 rounded text-end" dir="ltr"><code>// نقشه جاده
GET https://memaps.ir/api/bing/road/10/512/512.png
// ماهواره
GET https://memaps.ir/api/bing/aerial/10/512/512.jpg
// ترکیبی
GET https://memaps.ir/api/bing/hybrid/15/16384/16384.jpg</code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
</section>
<!-- Layers Section -->
<section id="layers" class="py-5 bg-light">
<div class="container">
<div class="text-center mb-5">
<h2 class="display-5 fw-bold text-gradient mb-3">انواع لایه‌های Bing</h2>
<p class="lead text-muted">
سه لایه در دسترس با پسوند مناسب
</p>
</div>
<div class="row g-4">
<div class="col-lg-4">
<div class="card h-100 border-0 shadow-sm">
<div class="card-header bg-primary text-white">
<h5 class="mb-0">🛣️ جاده (Road)</h5>
</div>
<div class="card-body">
<p class="card-text">نقشه جاده با نام خیابان‌ها و مکان‌ها. پسوند: <code>.png</code></p>
<div class="bg-dark text-light p-2 rounded text-end small" dir="ltr">
<code>.../bing/road/{z}/{x}/{y}.png</code>
</div>
</div>
</div>
</div>
<div class="col-lg-4">
<div class="card h-100 border-0 shadow-sm">
<div class="card-header bg-success text-white">
<h5 class="mb-0">🛰️ ماهواره (Aerial)</h5>
</div>
<div class="card-body">
<p class="card-text">تصاویر ماهواره‌ای. پسوند: <code>.jpg</code></p>
<div class="bg-dark text-light p-2 rounded text-end small" dir="ltr">
<code>.../bing/aerial/{z}/{x}/{y}.jpg</code>
</div>
</div>
</div>
</div>
<div class="col-lg-4">
<div class="card h-100 border-0 shadow-sm">
<div class="card-header bg-info text-white">
<h5 class="mb-0">🌐 ترکیبی (Hybrid)</h5>
</div>
<div class="card-body">
<p class="card-text">ماهواره به همراه برچسب و نام مکان‌ها. پسوند: <code>.jpg</code></p>
<div class="bg-dark text-light p-2 rounded text-end small" dir="ltr">
<code>.../bing/hybrid/{z}/{x}/{y}.jpg</code>
</div>
</div>
</div>
</div>
</div>
</div>
</section>
<!-- Iran Restriction Section -->
<section id="iran-restriction" class="py-5">
<div class="container">
<div class="row justify-content-center">
<div class="col-lg-8">
<div class="card border-0 shadow-sm">
<div class="card-header bg-secondary text-white">
<h5 class="mb-0">🇮🇷 محدودیت جغرافیایی به ایران</h5>
</div>
<div class="card-body p-4">
<p class="card-text">
سرویس تایل Bing می‌مپس <strong>فقط برای محدوده ایران</strong> از سرورهای Bing درخواست می‌زند:
</p>
<ul>
<li>اگر تایل با مرزهای ایران (تقریبی) <strong>تلاقی داشته باشد</strong>: از کش خوانده می‌شود یا در صورت نبود از Bing دریافت، کش و برگردانده می‌شود.</li>
<li>اگر تایل <strong>خارج از ایران</strong> باشد: یک تایل کاملاً <strong>سفید</strong> (۲۵۶×۲۵۶ پیکسل) برگردانده می‌شود و <strong>هیچ درخواستی به سرورهای Bing ارسال نمی‌شود</strong>.</li>
</ul>
<div class="alert alert-info mb-0">
این محدودیت باعث کاهش مصرف پهنای باند و رعایت استفاده معقول از سرویس Bing می‌شود و برای نقشه‌های متمرکز بر ایران کافی است.
</div>
</div>
</div>
</div>
</div>
</div>
</section>
<!-- Examples Section -->
<section id="examples" class="py-5 bg-light">
<div class="container">
<div class="text-center mb-5">
<h2 class="display-5 fw-bold text-gradient mb-3">مثال‌های عملی</h2>
<p class="lead text-muted">
استفاده با Leaflet و OpenLayers
</p>
</div>
<div class="row g-4">
<div class="col-lg-6">
<div class="card h-100 border-0 shadow-sm">
<div class="card-header bg-success text-white">
<h5 class="mb-0">Leaflet - نقشه جاده</h5>
</div>
<div class="card-body">
<pre class="bg-dark text-light p-3 rounded text-end" dir="ltr"><code>&lt;!DOCTYPE html&gt;
&lt;html&gt;
&lt;head&gt;
&lt;link rel="stylesheet"
href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css" /&gt;
&lt;script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"&gt;&lt;/script&gt;
&lt;/head&gt;
&lt;body&gt;
&lt;div id="map" style="height: 400px;"&gt;&lt;/div&gt;
&lt;script&gt;
var map = L.map('map').setView([35.6892, 51.3890], 10);
L.tileLayer('https://memaps.ir/api/bing/road/{z}/{x}/{y}.png', {
attribution: '© Bing via Memaps.ir',
maxZoom: 23
}).addTo(map);
&lt;/script&gt;
&lt;/body&gt;
&lt;/html&gt;</code></pre>
</div>
</div>
</div>
<div class="col-lg-6">
<div class="card h-100 border-0 shadow-sm">
<div class="card-header bg-primary text-white">
<h5 class="mb-0">Leaflet - ماهواره و ترکیبی</h5>
</div>
<div class="card-body">
<pre class="bg-dark text-light p-3 rounded text-end" dir="ltr"><code>var map = L.map('map').setView([35.6892, 51.3890], 10);
var roadLayer = L.tileLayer(
'https://memaps.ir/api/bing/road/{z}/{x}/{y}.png',
{ attribution: '© Bing via Memaps.ir', maxZoom: 23 }
);
var aerialLayer = L.tileLayer(
'https://memaps.ir/api/bing/aerial/{z}/{x}/{y}.jpg',
{ attribution: '© Bing via Memaps.ir', maxZoom: 23 }
);
var hybridLayer = L.tileLayer(
'https://memaps.ir/api/bing/hybrid/{z}/{x}/{y}.jpg',
{ attribution: '© Bing via Memaps.ir', maxZoom: 23 }
);
roadLayer.addTo(map);
L.control.layers({
'جاده': roadLayer,
'ماهواره': aerialLayer,
'ترکیبی': hybridLayer
}).addTo(map);</code></pre>
</div>
</div>
</div>
<div class="col-lg-6">
<div class="card h-100 border-0 shadow-sm">
<div class="card-header bg-warning text-dark">
<h5 class="mb-0">OpenLayers - Bing جاده</h5>
</div>
<div class="card-body">
<pre class="bg-dark text-light p-3 rounded text-end" dir="ltr"><code>&lt;!DOCTYPE html&gt;
&lt;html&gt;
&lt;head&gt;
&lt;link rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/ol@v7.4.0/ol.css"&gt;
&lt;script src="https://cdn.jsdelivr.net/npm/ol@v7.4.0/dist/ol.js"&gt;&lt;/script&gt;
&lt;/head&gt;
&lt;body&gt;
&lt;div id="map" style="height: 400px;"&gt;&lt;/div&gt;
&lt;script&gt;
var layer = new ol.layer.Tile({
source: new ol.source.XYZ({
url: 'https://memaps.ir/api/bing/road/{z}/{x}/{y}.png',
crossOrigin: 'anonymous'
})
});
var map = new ol.Map({
target: 'map',
layers: [layer],
view: new ol.View({
center: ol.proj.fromLonLat([51.3890, 35.6892]),
zoom: 10
})
});
&lt;/script&gt;
&lt;/body&gt;
&lt;/html&gt;</code></pre>
</div>
</div>
</div>
<div class="col-lg-6">
<div class="card h-100 border-0 shadow-sm">
<div class="card-header bg-info text-white">
<h5 class="mb-0">JavaScript - دریافت مستقیم</h5>
</div>
<div class="card-body">
<pre class="bg-dark text-light p-3 rounded text-end" dir="ltr"><code>async function getBingTile(layer, z, x, y, ext) {
ext = ext || (layer === 'road' ? 'png' : 'jpg');
const url = `https://memaps.ir/api/bing/${layer}/${z}/${x}/${y}.${ext}`;
const response = await fetch(url);
if (response.ok) return await response.blob();
return null;
}
getBingTile('road', 10, 512, 512); // PNG
getBingTile('aerial', 10, 512, 512); // JPG</code></pre>
</div>
</div>
</div>
</div>
</div>
</section>
<!-- Cache Section -->
<section id="cache" class="py-5">
<div class="container">
<div class="text-center mb-5">
<h2 class="display-5 fw-bold text-gradient mb-3">سیستم کش خودکار</h2>
<p class="lead text-muted">
کش تایل‌های داخل ایران؛ درخواست‌های بعدی بدون تماس با Bing
</p>
</div>
<div class="row g-4">
<div class="col-lg-8 mx-auto">
<div class="card border-0 shadow-sm">
<div class="card-body p-4">
<h3 class="h4 fw-bold mb-4">نحوه کار</h3>
<ol class="mb-4">
<li class="mb-2"><strong>بررسی محدوده ایران:</strong> اگر تایل خارج از ایران باشد، بلافاصله تایل سفید برگردانده می‌شود (بدون درخواست به Bing).</li>
<li class="mb-2"><strong>بررسی کش:</strong> اگر تایل داخل ایران است، ابتدا وجود آن در کش بررسی می‌شود.</li>
<li class="mb-2"><strong>بازگشت از کش:</strong> در صورت وجود در کش، همان فایل به کاربر برگردانده می‌شود.</li>
<li class="mb-2"><strong>دریافت از Bing:</strong> در صورت نبود در کش، تایل از Bing دریافت، در کش ذخیره و به کاربر برگردانده می‌شود.</li>
</ol>
<div class="alert alert-success">
<strong>اطلاعات کش:</strong><br>
<code dir="ltr">GET https://memaps.ir/api/bing/cache/info</code><br>
<span class="text-muted">خروجی شامل حجم کش، تعداد فایل و مسیر دایرکتوری کش است.</span>
</div>
</div>
</div>
</div>
</div>
</div>
</section>
<!-- CORS Section -->
<section class="py-5 bg-light">
<div class="container">
<div class="row justify-content-center">
<div class="col-lg-8">
<div class="card border-0 shadow-sm">
<div class="card-header bg-success text-white">
<h5 class="mb-0">پشتیبانی از CORS</h5>
</div>
<div class="card-body">
<p class="card-text">
API تایل‌های Bing می‌مپس از CORS پشتیبانی می‌کند و می‌توانید مستقیماً از مرورگر استفاده کنید:
</p>
<pre class="bg-dark text-light p-3 rounded text-end" dir="ltr"><code>const img = document.createElement('img');
img.src = 'https://memaps.ir/api/bing/road/10/512/512.png';
img.crossOrigin = 'anonymous';
document.body.appendChild(img);</code></pre>
</div>
</div>
</div>
</div>
</div>
</section>
{% endblock %}
{% block stylesheets %}
<style>
.hover-card {
transition: transform 0.3s ease, box-shadow 0.3s ease;
}
.hover-card:hover {
transform: translateY(-5px);
box-shadow: 0 10px 25px rgba(0,0,0,0.1) !important;
}
pre { font-size: 0.9rem; line-height: 1.4; }
code { font-family: 'Courier New', monospace; }
</style>
{% endblock %}