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

{% extends 'base.html.twig' %}

{% block title %}راهنمای API مسیریابی ماتریسی | می‌مپس{% endblock %}

{% block description %}راهنمای کامل API مسیریابی ماتریسی می‌مپس - محاسبه فاصله و زمان بین چند مبدأ و مقصد روی شبکه جاده ایران با داده OSM{% endblock %}

{% block keywords %}API مسیریابی ماتریسی, Matrix API, فاصله جاده, زمان سفر, pgRouting, OSM, مسیریابی ایران{% endblock %}

{% block og_title %}راهنمای API مسیریابی ماتریسی می‌مپس{% endblock %}

{% block og_description %}راهنمای کامل API مسیریابی ماتریسی می‌مپس - فاصله و زمان بین نقاط روی جاده‌های ایران{% 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 مسیریابی ماتریسی
                    <span class="d-block">سرویس می‌مپس</span>
                </h1>
                <p class="lead opacity-90">
                    محاسبه ماتریس فاصله و زمان سفر بین چند مبدأ و مقصد روی شبکه جاده‌های ایران (داده OpenStreetMap)
                </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">معرفی</h6>
                                    </div>
                                </div>
                            </a>
                        </div>
                        <div class="col-lg-4 col-md-6">
                            <a href="#iran-only" 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="#request" 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">ورودی (Request)</h6>
                                    </div>
                                </div>
                            </a>
                        </div>
                        <div class="col-lg-4 col-md-6">
                            <a href="#response" 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">خروجی (Response)</h6>
                                    </div>
                                </div>
                            </a>
                        </div>
                        <div class="col-lg-4 col-md-6">
                            <a href="#errors" 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="#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-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 id="introduction" class="py-5">
        <div class="container">
            <div class="row justify-content-center">
                <div class="col-lg-8">
                    <h2 class="display-6 fw-bold text-gradient mb-4">معرفی API مسیریابی ماتریسی</h2>
                    <p class="lead text-muted mb-4">
                        با این API می‌توانید برای چند نقطه مبدأ و چند نقطه مقصد، ماتریس فاصله (متر) و زمان سفر (ثانیه) روی شبکه جاده را در یک درخواست دریافت کنید. داده‌های جاده از OpenStreetMap و موتور مسیریابی pgRouting استفاده می‌شود.
                    </p>
                    <div class="card border-0 shadow-sm mb-4">
                        <div class="card-body p-4">
                            <h3 class="h5 fw-bold mb-3">کاربردها</h3>
                            <ul class="mb-0">
                                <li>بهینه‌سازی توزیع و انتخاب نزدیک‌ترین انبار به هر مشتری</li>
                                <li>برآورد هزینه حمل و زمان سفر برای نرم‌افزارهای لجستیک</li>
                                <li>محاسبه ماتریس فاصله/زمان برای الگوریتم‌های مسیریابی (مثلاً VRP)</li>
                            </ul>
                        </div>
                    </div>
                </div>
            </div>
        </div>
    </section>

    <!-- Iran only -->
    <section id="iran-only" class="py-5 bg-light">
        <div class="container">
            <div class="row justify-content-center">
                <div class="col-lg-8">
                    <h2 class="display-6 fw-bold text-gradient mb-4">محدودیت جغرافیایی: فقط ایران</h2>
                    <div class="alert alert-warning mb-0">
                        <strong>توجه:</strong> این سرویس فقط برای نقاط واقع در محدوده ایران فعال است. اگر هر یک از نقاط مبدأ یا مقصد خارج از مرز ایران باشد، پاسخ با وضعیت <code>400</code> و پیام خطای فارسی برگردانده می‌شود.
                    </div>
                </div>
            </div>
        </div>
    </section>

    <!-- Endpoint -->
    <section id="endpoint" class="py-5">
        <div class="container">
            <div class="row justify-content-center">
                <div class="col-lg-8">
                    <h2 class="display-6 fw-bold text-gradient mb-4">نقطه پایانی (Endpoint)</h2>
                    <div class="card border-0 shadow-sm">
                        <div class="card-body p-4">
                            <p class="mb-2"><strong>مسیر:</strong></p>
                            <p class="mb-2"><code class="text-primary">POST https://memaps.ir/api/matrix</code></p>
                            <p class="mb-0 text-muted"><strong>Content-Type:</strong> <code>application/json</code></p>
                        </div>
                    </div>
                    <p class="mt-3 text-muted">حداکثر ۲۵ مبدأ، ۲۵ مقصد و حداکثر ۱۰۰۰ جفت (origins × destinations) در هر درخواست.</p>
                </div>
            </div>
        </div>
    </section>

    <!-- Request -->
    <section id="request" class="py-5 bg-light">
        <div class="container">
            <div class="row justify-content-center">
                <div class="col-lg-8">
                    <h2 class="display-6 fw-bold text-gradient mb-4">ورودی (Request Body)</h2>
                    <div class="table-responsive mb-4">
                        <table class="table table-bordered">
                            <thead><tr><th>فیلد</th><th>نوع</th><th>توضیح</th></tr></thead>
                            <tbody>
                                <tr><td><code>origins</code></td><td>آرایه</td><td>نقاط مبدأ؛ هر عضو <code>[longitude, latitude]</code> (WGS84). حداکثر ۲۵.</td></tr>
                                <tr><td><code>destinations</code></td><td>آرایه</td><td>نقاط مقصد؛ همان فرمت. حداکثر ۲۵.</td></tr>
                                <tr><td><code>options.metrics</code></td><td>آرایه</td><td>اختیاری. <code>["distance"]</code> و/یا <code>["duration"]</code>. پیش‌فرض: هر دو.</td></tr>
                                <tr><td><code>options.max_snap_distance_m</code></td><td>عدد</td><td>اختیاری. حداکثر فاصله (متر) برای snap نقطه به شبکه جاده. پیش‌فرض: ۵۰۰.</td></tr>
                            </tbody>
                        </table>
                    </div>
                    <h3 class="h5 fw-bold mb-3">نمونه بدنه درخواست</h3>
                    <pre class="bg-dark text-light p-3 rounded text-end" dir="ltr" style="font-size: 0.85rem;"><code>{
  "origins": [[51.42, 35.69], [51.38, 35.72]],
  "destinations": [[51.43, 35.70], [51.39, 35.71]],
  "options": {
    "metrics": ["distance", "duration"],
    "max_snap_distance_m": 500
  }
}</code></pre>
                </div>
            </div>
        </div>
    </section>

    <!-- Response -->
    <section id="response" class="py-5">
        <div class="container">
            <div class="row justify-content-center">
                <div class="col-lg-8">
                    <h2 class="display-6 fw-bold text-gradient mb-4">خروجی (Response)</h2>
                    <p class="text-muted mb-3"><strong>distances</strong>: ماتریس N×M فاصله به متر (یا <code>null</code>). <strong>durations</strong>: ماتریس N×M زمان به ثانیه (تقریب بر اساس سرعت ~۵۰ km/h). <strong>origins</strong> و <strong>destinations</strong>: برای هر نقطه، <code>index</code>، <code>snapped</code> (مختصات snapped به شبکه)، <code>valid</code>.</p>
                    <pre class="bg-dark text-light p-3 rounded text-end" dir="ltr" style="font-size: 0.8rem;"><code>{
  "origins": [
    { "index": 0, "snapped": [51.4201, 35.6902], "valid": true },
    { "index": 1, "snapped": [51.3802, 35.7201], "valid": true }
  ],
  "destinations": [
    { "index": 0, "snapped": [51.4300, 35.7001], "valid": true },
    { "index": 1, "snapped": [51.3901, 35.7100], "valid": true }
  ],
  "distances": [[1200.5, 3500.2], [4100.0, 800.3]],
  "durations": [[86.4, 252.0], [295.2, 57.6]]
}</code></pre>
                </div>
            </div>
        </div>
    </section>

    <!-- Errors -->
    <section id="errors" class="py-5 bg-light">
        <div class="container">
            <div class="row justify-content-center">
                <div class="col-lg-8">
                    <h2 class="display-6 fw-bold text-gradient mb-4">خطاها</h2>
                    <div class="table-responsive">
                        <table class="table table-bordered">
                            <thead><tr><th>وضعیت HTTP</th><th>معنی</th></tr></thead>
                            <tbody>
                                <tr><td><code>400</code></td><td>ورودی نامعتبر (نقطه خارج از ایران، تعداد نقاط بیش از حد، JSON نامعتبر).</td></tr>
                                <tr><td><code>503</code></td><td>سرویس مسیریابی موقتاً در دسترس نیست (گراف مسیریابی یافت نشد).</td></tr>
                                <tr><td><code>500</code></td><td>خطای داخلی سرور یا دیتابیس.</td></tr>
                            </tbody>
                        </table>
                    </div>
                    <p class="text-muted mb-0">بدنه خطا JSON با فیلد <code>error</code> (رشتهٔ فارسی) است.</p>
                </div>
            </div>
        </div>
    </section>

    <!-- Examples -->
    <section id="examples" class="py-5">
        <div class="container">
            <div class="row justify-content-center">
                <div class="col-lg-8">
                    <h2 class="display-6 fw-bold text-gradient mb-4">مثال‌های عملی</h2>

                    <h3 class="h5 fw-bold mb-3">با cURL</h3>
                    <pre class="bg-dark text-light p-3 rounded text-end" dir="ltr" style="font-size: 0.85rem;"><code>curl -X POST https://memaps.ir/api/matrix \
  -H "Content-Type: application/json" \
  -d '{"origins":[[51.42,35.69]],"destinations":[[51.43,35.70]]}'</code></pre>

                    <h3 class="h5 fw-bold mb-3 mt-4">با JavaScript (fetch)</h3>
                    <pre class="bg-dark text-light p-3 rounded text-end" dir="ltr" style="font-size: 0.85rem;"><code>const body = {
  origins: [[51.42, 35.69], [51.38, 35.72]],
  destinations: [[51.43, 35.70], [51.39, 35.71]],
  options: { metrics: ['distance', 'duration'] }
};

const res = await fetch('https://memaps.ir/api/matrix', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(body)
});
const data = await res.json();
console.log('Distances (m):', data.distances);
console.log('Durations (s):', data.durations);</code></pre>

                    <h3 class="h5 fw-bold mb-3 mt-4">با PHP</h3>
                    <pre class="bg-dark text-light p-3 rounded text-end" dir="ltr" style="font-size: 0.85rem;"><code>$body = [
  'origins' => [[51.42, 35.69], [51.38, 35.72]],
  'destinations' => [[51.43, 35.70], [51.39, 35.71]],
  'options' => ['metrics' => ['distance', 'duration']]
];

$ch = curl_init('https://memaps.ir/api/matrix');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$data = json_decode($response, true);</code></pre>
                </div>
            </div>
        </div>
    </section>
{% endblock %}