سرویس‌های شبکه راه: خط مسیر، محدوده دسترسی زمانی، ماتریس، پوشش مراکز و مکان‌یابی مرکز جدید

فاصله و زمان بین دو نقطه فقط شروع کار است. سازمانی که شعبه، انبار یا نمایندگی دارد سوال‌های بزرگ‌تری می‌پرسد: «پایگاه‌های من در ۳۰ دقیقه به چند نفر می‌رسند؟»، «کدام روستاها بیرون از پوشش‌اند؟»، «پایگاه بعدی را کجا بسازم؟»، «اگر این محور بسته شود چه می‌شود؟». این هشت سرویس با شبکه واقعی راه‌های کشور (نه فاصله مستقیم) و نقشه جمعیت به همین سوال‌ها جواب می‌دهند.

برای دریافت توکن، با خرید بسته ژئوکوین کیف پول را شارژ کنید و در توکن‌های API توکن بسازید. هزینه هر درخواست موفق از اعتبار همان توکن کم می‌شود (قیمت هر سرویس در صفحه سرویس‌ها).

نقاط به شکل [lat, lon] یا {"lat": …, "lon": …, "name": …} فرستاده می‌شوند. وسیله (profile): auto (خودرو)، pedestrian، bicycle، truck، bus، motorcycle. زمان‌ها بر اساس سرعت مجاز جاده‌هاست و ترافیک لحظه‌ای ندارد.

۱. مسیر با خط مسیر

curl -X POST "https://cloud.geotajak.ir/api/geo/route/path" \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"locations": [[35.6997, 51.3380], [35.7448, 51.3753]], "alternatives": 1}'

{
  "summary": "مسیر خودرو: 10.46 کیلومتر، حدود 13 دقیقه؛ 1 مسیر جایگزین.",
  "distance_km": 10.46, "duration_min": 12.7,
  "geometry": {"type": "LineString", "coordinates": [[51.338179, 35.698735], [51.3382, 35.6991]]},
  "alternatives": [{"distance_km": 12.26, "duration_min": 15.1, "geometry": {"type": "LineString", "coordinates": []}}]
}

• locations: ۲ تا ۲۰ نقطه به ترتیب حرکت. alternatives: تا ۲ مسیر جایگزین (فقط برای دو نقطه).
• avoid_polygons: محدوده‌هایی که مسیر نباید از آن‌ها بگذرد، [[[lat, lon], …], …]. فقط خودِ بخش بسته جاده را بکشید؛ مجموع محیط چندضلعی‌ها حداکثر ۱۰ کیلومتر است.
• سرویس قدیمی GET /api/geo/route هم با geometry=true خط مسیر را برمی‌گرداند.

۲. محدوده دسترسی زمانی (ایزوکرون)

curl -G "https://cloud.geotajak.ir/api/geo/isochrone" \
  --data-urlencode "lat=35.6997" \
  --data-urlencode "lon=51.3380" \
  --data-urlencode "minutes=10,20" \
  --data-urlencode "profile=auto" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "summary": "این نقطه (خودرو): تا 10 دقیقه 52 کیلومتر مربع و حدود 870,000 نفر؛ تا 20 دقیقه 214 کیلومتر مربع و حدود 3,100,000 نفر.",
  "contours": [{"minutes": 10, "area_km2": 52.3, "population": 870412}, {"minutes": 20, "area_km2": 214.0, "population": 3100250}],
  "geojson": {"type": "FeatureCollection", "features": []}
}

minutes تا ۴ مقدار، هرکدام بین ۱ تا ۱۲۰ دقیقه. geojson چندضلعی هر بازه را برای رسم روی نقشه دارد.

۳. ماتریس زمان و فاصله

curl -X POST "https://cloud.geotajak.ir/api/geo/matrix" \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"sources": [[35.6997, 51.3380], [35.72, 51.42]], "targets": [[35.7448, 51.3753], [35.60, 51.43]]}'

durations_min و distances_km جدول مبدأ در مقصد هستند (تا ۲۵ در ۲۵). null یعنی مسیر جاده‌ای وجود ندارد. nearest_target نزدیک‌ترین مقصد هر مبدأ را می‌دهد.

۴. پروفیل ارتفاعی

curl -X POST "https://cloud.geotajak.ir/api/geo/elevation/profile" \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"line": [[35.70, 51.38], [35.80, 51.42]], "samples": 60}'

{
  "summary": "طول 11.7 کیلومتر؛ ارتفاع از 1,215 تا 1,608 متر؛ مجموع صعود 400 و نزول 7 متر؛ بیشترین شیب حدود 8.7٪.",
  "length_km": 11.7, "min_elevation_m": 1215, "max_elevation_m": 1608, "ascent_m": 400, "descent_m": 7, "max_slope_pct": 8.7,
  "profile": [{"distance_km": 0.0, "elevation_m": 1215, "lat": 35.7, "lon": 51.38}]
}

با "along_route": true نیمرخ در طول مسیر جاده‌ای بین نقاط محاسبه می‌شود (برای خط لوله، خط انتقال یا مسیر مستقیم آن را خاموش بگذارید).

سرویس‌هایی که با مراکز خود شما کار می‌کنند (شعبه، انبار، نمایندگی) فهرست نقاط را در facilities می‌گیرند: [{"lat": …, "lon": …, "name": …}, …].

۵. نزدیک‌ترین مرکز شما به یک نقطه

curl -X POST "https://cloud.geotajak.ir/api/geo/facilities/nearest" \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"lat": 31.16, "lon": 53.30, "facilities": [{"lat": 31.13, "lon": 53.28, "name": "شعبه ۱"}, {"lat": 31.02, "lon": 53.36, "name": "شعبه ۲"}]}'

مراکز به ترتیب زمان واقعی جاده‌ای رتبه‌بندی می‌شوند، همراه با فاصله جاده‌ای، فاصله مستقیم و خط مسیر سریع‌ترین مرکز (best_route). تا ۴۹ مرکز.

۶. پوشش زمانی مراکز و خلأ پوشش

curl -X POST "https://cloud.geotajak.ir/api/geo/facilities/coverage" \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"facilities": [{"lat": 31.13, "lon": 53.28, "name": "شعبه ۱"}, {"lat": 31.02, "lon": 53.36, "name": "شعبه ۲"}], "minutes": "15,30,60", "bbox": "53.0,30.9,53.6,31.4"}'

{
  "summary": "2 مرکز (خودرو): تا 30 دقیقه حدود 41,000 نفر در 1,250 کیلومتر مربع (78٪ جمعیت محدوده)؛ 11,600 نفر خارج از پوشش؛ 9 شهر و روستا بیرون از 30 دقیقه.",
  "bands": [{"minutes": 30, "area_km2": 1250.4, "population": 41020, "population_pct": 78.0, "uncovered_population": 11600}],
  "uncovered_settlements": {"count": 9, "items": [{"name": "مهردشت", "type_fa": "شهر کوچک", "nearest_facility_km": 14.2}]}
}

• بدون محدوده مطالعه (bbox یا polygon) فقط جمعیت تحت پوشش گزارش می‌شود؛ با محدوده، سهم پوشش، جمعیت بیرون از پوشش و فهرست شهرها و روستاهای بیرون از بازه هم می‌آید.
• تا ۳۰ مرکز در هر درخواست. برای کل کشور، استان به استان فراخوانی کنید.

۷. پیشنهاد مکان مرکز جدید

curl -X POST "https://cloud.geotajak.ir/api/geo/facilities/suggest" \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"facilities": [{"lat": 31.13, "lon": 53.28, "name": "شعبه ۱"}, {"lat": 31.02, "lon": 53.36, "name": "شعبه ۲"}], "minutes": 30, "count": 3, "bbox": "53.0,30.9,53.6,31.4"}'

پاسخ، مکان‌های پیشنهادی را به ترتیب اولویت با جمعیت تازه تحت پوشش هرکدام و مقایسه before و after می‌دهد. روش: از بین سکونتگاه‌های بدون پوشش محدوده، هر بار نقطه‌ای انتخاب می‌شود که بیشترین جمعیت جدید را پوشش دهد. این یک غربال اولیه است؛ مالکیت زمین و ملاحظات عملیاتی جداگانه بررسی شود.

۸. اثر انسداد جاده

curl -X POST "https://cloud.geotajak.ir/api/geo/network/closure" \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"origins": [{"lat": 31.13, "lon": 53.28, "name": "شعبه ۱"}, {"lat": 31.02, "lon": 53.36, "name": "شعبه ۲"}], "destinations": [{"lat": 31.02, "lon": 53.36, "name": "مهردشت"}], "closed_polygons": [[[31.08, 53.31], [31.08, 53.33], [31.09, 53.33], [31.09, 53.31]]]}'

برای هر زوج مبدأ و مقصد زمان قبل و بعد از انسداد، میزان تاخیر و وضعیت (unchanged، delayed، cut_off) برمی‌گردد و مقصدهایی که از همه مبدأها جدا می‌افتند مشخص می‌شوند.

منبع و دقت داده

راه‌ها از OpenStreetMap، ارتفاع از SRTM و جمعیت از WorldPop 2020 است. جمعیت مدل‌شده است، نه آمار رسمی سرشماری، و زمان‌ها ترافیک لحظه‌ای را در نظر نمی‌گیرند.

نمایش آماده در سایت (بدون کدنویسی)

اگر به آدرس همین سرویس‌ها ui=true اضافه کنید، به‌جای JSON یک صفحه آماده (نقشه، نمودار و جدول نتیجه) برمی‌گردد که در <iframe> سایت شما قرار می‌گیرد و با رنگ‌های توکن شما ساخته می‌شود. جزئیات در راهنمای شروع و نمونه زنده در «آزمایشگاه سرویس» صفحه هر سرویس.