شروع کنید
API

راهنمای API مسیریابی ماتریسی

محاسبه ماتریس فاصله و زمان سفر بین چند مبدأ و مقصد روی شبکه جاده‌های ایران

فهرست مطالب

1
معرفی
2
محدودیت ایران
3
نقطه پایانی
4
ورودی (Request)
5
خروجی (Response)
6
خطاها
7
مثال‌های عملی

معرفی API مسیریابی ماتریسی

با این API می‌توانید برای چند نقطه مبدأ و چند نقطه مقصد، ماتریس فاصله (متر) و زمان سفر (ثانیه) روی شبکه جاده را در یک درخواست دریافت کنید. داده‌های جاده از OpenStreetMap و موتور مسیریابی pgRouting استفاده می‌شود.

کاربردها

  • بهینه‌سازی توزیع و انتخاب نزدیک‌ترین انبار به هر مشتری
  • برآورد هزینه حمل و زمان سفر برای نرم‌افزارهای لجستیک
  • محاسبه ماتریس فاصله/زمان برای الگوریتم‌های مسیریابی (مثلاً VRP)

محدودیت جغرافیایی: فقط ایران

توجه: این سرویس فقط برای نقاط واقع در محدوده ایران فعال است. اگر هر یک از نقاط مبدأ یا مقصد خارج از مرز ایران باشد، پاسخ با وضعیت 400 و پیام خطای فارسی برگردانده می‌شود.

نقطه پایانی (Endpoint)

مسیر:

POST https://memaps.ir/api/matrix

Content-Type: application/json

حداکثر ۲۵ مبدأ، ۲۵ مقصد و حداکثر ۱۰۰۰ جفت (origins × destinations) در هر درخواست.

ورودی (Request Body)

فیلدنوعتوضیح
originsآرایهنقاط مبدأ؛ هر عضو [longitude, latitude] (WGS84). حداکثر ۲۵.
destinationsآرایهنقاط مقصد؛ همان فرمت. حداکثر ۲۵.
options.metricsآرایهاختیاری. ["distance"] و/یا ["duration"]. پیش‌فرض: هر دو.
options.max_snap_distance_mعدداختیاری. حداکثر فاصله (متر) برای snap نقطه به شبکه جاده. پیش‌فرض: ۵۰۰.

نمونه بدنه درخواست

{
  "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
  }
}

خروجی (Response)

distances: ماتریس N×M فاصله به متر (یا null). durations: ماتریس N×M زمان به ثانیه (تقریب بر اساس سرعت ~۵۰ km/h). origins و destinations: برای هر نقطه، index، snapped (مختصات snapped به شبکه)، valid.

{
  "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]]
}

خطاها

وضعیت HTTPمعنی
400ورودی نامعتبر (نقطه خارج از ایران، تعداد نقاط بیش از حد، JSON نامعتبر).
503سرویس مسیریابی موقتاً در دسترس نیست (گراف مسیریابی یافت نشد).
500خطای داخلی سرور یا دیتابیس.

بدنه خطا JSON با فیلد error (رشتهٔ فارسی) است.

مثال‌های عملی

با cURL

curl -X POST https://memaps.ir/api/matrix \
  -H "Content-Type: application/json" \
  -d '{"origins":[[51.42,35.69]],"destinations":[[51.43,35.70]]}'

با JavaScript (fetch)

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);

با PHP

$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);