راهنمای شروع سرویس‌های مکانی ژئوتاژک (API)
۱۴۰۵/۷/۷
تیم ژئوتاژک
سرویس‌های مکانی ژئوتاژک مجموعه‌ای از APIهای آماده برای جستجوی آدرس، مسیریابی، ارتفاع، تحلیل محدوده و هوش مصنوعی مکانی روی داده‌های ایران هستند. همه سرویس‌ها از یک آدرس پایه و یک روش احراز هویت استفاده می‌کنند.
سرویس‌ها
| سرویس | آدرس |
|---|---|
| جستجوی آدرس و مکان (Geocoding) | GET /api/geo/geocode |
| آدرس‌یابی معکوس (Reverse Geocoding) | POST /api/geo/reverse |
| مسیریابی، فاصله و زمان سفر | GET /api/geo/route |
| ارتفاع از سطح دریا | POST /api/geo/elevation |
| اطلاعات جامع مکان | POST /api/geo/location-info |
| توصیف هوشمند مکان با هوش مصنوعی | POST /api/geo/describe |
| محاسبه مساحت و محیط | POST /api/geo/area |
| کاربری غالب اراضی | POST /api/geo/land-use |
| نزدیک‌ترین شهر | POST /api/geo/nearest-city |
| شاخص دسترسی به خدمات | POST /api/geo/service-access |
| تجزیه هوشمند آدرس فارسی | POST /api/geo/parse-address |
| آب و هوای کنونی و پیش‌بینی | GET /api/geo/weather/current |
| تاریخچه آب و هوا | GET /api/geo/weather/history |
| اقلیم و میانگین آب و هوا | GET /api/geo/weather/climate |
| خاک‌شناسی نقطه | GET /api/geo/soil |
| اقلیم کشاورزی | GET /api/geo/agro/climate |
| پایش خشکسالی | GET /api/geo/agro/drought |
| الگوی کشت پیشنهادی (AI) | GET /api/geo/agro/crop-suitability |
| هشدارهای جوی | GET /api/geo/hazard/alerts |
| زمین‌لرزه‌ها | GET /api/geo/hazard/earthquakes |
| ریسک سیلاب | GET /api/geo/hazard/flood |
| آتش‌سوزی‌های فعال | GET /api/geo/hazard/fires |
| زیرساخت‌های حیاتی | GET /api/geo/infrastructure |
| دکل‌ها و سلول‌های مخابراتی | GET /api/geo/telecom |
| تقویم یخبندان | GET /api/geo/agro/frost |
| بیلان آب و نیاز آبی | GET /api/geo/agro/water-balance |
| رطوبت خاک | GET /api/geo/agro/soil-moisture |
| بارش‌های حدی و دوره بازگشت | GET /api/geo/climate/rain-extremes |
| آبراهه‌ها و سدها | GET /api/geo/hydro/waterways |
| پستی‌بلندی زمین | GET /api/geo/terrain/relief |
| نزدیک‌ترین مراکز | GET /api/geo/nearest-facility |
| پوشش شبکه در یک نقطه | GET /api/geo/coverage/point |
| درصد پوشش شبکه یک محدوده | GET /api/geo/coverage/area |
| پوشش شبکه در طول مسیر | GET /api/geo/coverage/route |
| نقشه پوشش شبکه | GET /api/geo/coverage/map |
| جمعیت اطراف یک نقطه | GET /api/geo/population/point |
| جمعیت در حلقه‌های فاصله | GET /api/geo/population/rings |
| ساختار سنی و جنسی جمعیت | GET /api/geo/population/demographics |
| جمعیت شهر، شهرستان یا محدوده | GET /api/geo/population/area |
| جمعیت داخل چندضلعی | POST /api/geo/population/polygon |
| نقشه تراکم جمعیت | GET /api/geo/population/grid |
| مسیر با خط مسیر | POST /api/geo/route/path |
| محدوده دسترسی زمانی (ایزوکرون) | GET /api/geo/isochrone |
| ماتریس زمان و فاصله | POST /api/geo/matrix |
| پروفیل ارتفاعی مسیر | POST /api/geo/elevation/profile |
| نزدیک‌ترین مرکز شما | POST /api/geo/facilities/nearest |
| پوشش زمانی مراکز و خلأ پوشش | POST /api/geo/facilities/coverage |
| پیشنهاد مکان مرکز جدید | POST /api/geo/facilities/suggest |
| اثر انسداد جاده | POST /api/geo/network/closure |
| تقسیمات کشوری یک نقطه | GET /api/geo/admin/lookup |
| جستجوی شهر و روستا | GET /api/geo/places/search |
| سکونتگاه‌های یک محدوده | GET /api/geo/places/in-area |
| تبدیل مختصات | GET /api/geo/convert/coordinates |
| ژئوفنس | POST /api/geo/geofence |
| برآورد اثر در یک محدوده | POST /api/geo/impact/area |
| گزارش اولیه اثر احتمالی (AI) | POST /api/geo/impact/report |
| مکان‌یابی و امتیازدهی سایت (AI) | POST /api/geo/site/suitability |
| پیشنهاد اعزام (AI) | POST /api/geo/dispatch/advice |
| شناسنامه شهرستان و شهر (AI) | GET /api/geo/profile/place |
| خطر لرزه‌ای و گسل‌های فعال | GET /api/geo/hazard/seismic |
| پهنه‌های سیلاب رودخانه‌ای | GET /api/geo/hazard/flood-zones |
| استعداد زمین‌لغزش | GET /api/geo/hazard/landslide |
| شاخص ریسک چندمخاطره‌ای نقطه | GET /api/geo/risk/point |
| ریسک و جمعیت در معرض یک محدوده | POST /api/geo/risk/area |
| شناسنامه خطر (AI) | POST /api/geo/risk/brief |
| پوشش زمین نقطه | GET /api/geo/landcover/point |
| پوشش زمین محدوده | POST /api/geo/landcover/area |
| پتانسیل انرژی خورشیدی | GET /api/geo/energy/solar |
| پتانسیل انرژی بادی | GET /api/geo/energy/wind |
| سابقه بارش سالانه | GET /api/geo/climate/rainfall |
| تغییر اقلیم | GET /api/geo/climate/projection |
| میدان دید | GET /api/geo/terrain/viewshed |
| خط دید بین دو نقطه | GET /api/geo/terrain/line-of-sight |
| آب‌های سطحی و تغییر آن‌ها | POST /api/geo/water/surface |
| مصرف واقعی آب | GET /api/geo/water/evapotranspiration |
| گزارش تنش آبی | POST /api/geo/water/brief |
| رشد سطح ساخته‌شده شهر | POST /api/geo/urban/growth |
| غربال سایت نیروگاه | POST /api/geo/energy/site-screen |
| شکاف پوشش موبایل | POST /api/geo/coverage/gap |
| خوراک هشدارها | GET /api/geo/alerts/feed |
| بولتن روزانه | GET /api/geo/bulletin/daily |
| نیاز آبیاری محصول | GET /api/geo/agri/irrigation-advice |
| سبزینگی و سلامت پوشش گیاهی | GET /api/geo/vegetation/ndvi |
| وضعیت پوشش گیاهی محدوده | POST /api/geo/vegetation/health |
| سابقه آتش‌سوزی و سطح سوخته | POST /api/geo/hazard/burned-area |
| روشنایی شبانه | POST /api/geo/urban/night-lights |
| روند ذخیره آب | GET /api/geo/water/storage |
| گردوغبار و ذرات معلق | GET /api/geo/air/dust |
| حوضه آبریز یک نقطه | GET /api/geo/water/watershed |
| تصاویر اخیر Sentinel-2 | POST /api/geo/imagery/scenes |
| تصویر ماهواره‌ای محدوده | POST /api/geo/imagery/snapshot |
| نقشه سطح سوخته | POST /api/geo/imagery/burn-scar |
| نقشه سیلاب و گستره آب | POST /api/geo/imagery/water-extent |
| فهرست لایه‌های داده | GET /api/geo/layers |
| مقدار لایه‌ها در نقطه | GET /api/geo/layers/point |
| آمار منطقه‌ای | POST /api/geo/layers/zonal |
| نقشه لایه داده | GET /api/geo/layers/map |
| کیفیت هوای کنونی | GET /api/geo/air/current |
| پیش‌بینی کیفیت هوا | GET /api/geo/air/forecast |
| آلودگی هوای یک منطقه | GET /api/geo/air/area |
| نقشه آلودگی هوا | GET /api/geo/air/map |
| رتبه‌بندی آلودگی شهرها | GET /api/geo/air/cities |
برای دستیارها و ایجنت‌های هوش مصنوعی: همه این سرویس‌ها با پروتکل MCP هم در دسترس‌اند (آدرس
https://cloud.geotajak.ir/mcpبا همان توکن). راهنما: اتصال با MCP.
مراحل شروع
- ثبت‌نام: در cloud.geotajak.ir حساب کاربری بسازید و شماره موبایل خود را با کد پیامکی تایید کنید؛ ۲۰۰ هزار ژئوکوین هدیه به کیف پول شما اضافه می‌شود.
- خرید ژئوکوین: واحد همه قیمت‌ها در ژئوتاژک کلود «ژئوکوین» است. هر وقت لازم شد، از بخش کیف پول یک بسته ژئوکوین با درگاه بانکی بخرید (بسته‌های بزرگ‌تر ژئوکوین هدیه دارند). فاکتور هر خرید در بخش فاکتورها ثبت می‌شود.
- ساخت توکن: در بخش توکن‌های API برای هر برنامه یک توکن بسازید و بخشی از موجودی کیف پول را به آن اختصاص دهید (مثلا «این توکن تا ۴۰۰ هزار ژئوکوین مصرف کند»).
- فراخوانی: کلید توکن را در هدر
Authorization: Bearer YOUR_TOKENبفرستید.
curl "https://cloud.geotajak.ir/api/geo/geocode?q=Isfahan&limit=1" \
-H "Authorization: Bearer YOUR_TOKEN"
قیمت‌گذاری
همه قیمت‌ها به ژئوکوین (سکه ژئوتاژک کلود) است، نه تومان؛ ژئوکوین را به‌صورت بسته از کیف پول می‌خرید.
هر سرویس قیمت مشخصی برای هر درخواست دارد (در صفحه سرویس‌ها). هر درخواست موفق، هزینه همان سرویس را از اعتبار توکنی که با آن فراخوانی کرده‌اید کم می‌کند. خرید بسته یا اشتراک جداگانه لازم نیست؛ هر قدر درخواست بزنید، به همان اندازه پرداخت می‌کنید.
در هر پاسخ دو هدر برمی‌گردد: X-Request-Cost (هزینه همین درخواست) و X-Credit-Remaining (اعتبار باقی‌مانده توکن).
نمایش آماده در سایت (ui=true)
برای نمایش نتیجه لازم نیست کد بنویسید. به آدرس هر سرویس ui=true اضافه کنید تا به‌جای JSON یک صفحه آماده (نقشه، نمودار و جدول همان سرویس) برگردد و آن را در <iframe> بگذارید:
<iframe src="https://cloud.geotajak.ir/api/geo/weather/current?place=یزد&ui=true&api_key=YOUR_TOKEN"
width="100%" height="640" style="border:0" loading="lazy"></iframe>
| پارامتر | توضیح |
|---|---|
ui=true | خروجی گرافیکی به‌جای JSON |
api_key | توکن API (در آدرس، چون iframe هدر نمی‌فرستد) |
ui_controls=false | حذف فرم بالای صفحه که بازدیدکننده با آن پارامترها را عوض می‌کند |
body={...} | برای سرویس‌های POST: بدنه JSON در آدرس (یا هر فیلد به‌صورت یک پارامتر جدا) |
ui_primary=2563eb | تغییر یک رنگ فقط برای همین فراخوانی (همین‌طور ui_accent، ui_background، ui_surface، ui_text، ui_muted، ui_border، ui_radius، ui_font، ui_map) |
- هماهنگی با سایت شما: هنگام ساخت یا ویرایش توکن، در بخش «قالب رنگ ویجت‌ها» رنگ‌ها، فونت، گردی گوشه‌ها و نقشه روشن/تیره را انتخاب کنید؛ همه خروجی‌های گرافیکی آن توکن با همین قالب ساخته می‌شوند.
- امتحان قبل از استفاده: در صفحه هر سرویس، «آزمایشگاه سرویس» نتیجه را به‌صورت گرافیکی و JSON نشان می‌دهد و کد
<iframe>آماده را می‌دهد. - هزینه: هر بار نمایش یک درخواست معمولی حساب می‌شود.
- امنیت: کلید در کد صفحه دیده می‌شود؛ برای سایت یک توکن جدا بسازید و «دامنه‌های مجاز» و «سقف مصرف دوره‌ای» آن را تنظیم کنید.
تنظیمات هر توکن
| تنظیم | توضیح |
|---|---|
| نام | برای تشخیص توکن‌ها (مثلا «اپ موبایل»، «سرور تست») |
| اعتبار | سقف مبلغی که این توکن می‌تواند مصرف کند؛ هر زمان از کیف پول اضافه یا به کیف پول برگردانید |
| سقف مصرف دوره‌ای | مثلا «حداکثر ۱۰۰ هزار ژئوکوین در هفته»؛ ریست روزانه (نیمه‌شب تهران)، هفتگی (شنبه) یا ماهانه (اول ماه شمسی) (اختیاری) |
| سرویس‌ها | همه سرویس‌ها یا فقط سرویس‌های انتخابی |
| تاریخ انقضا | بعد از این تاریخ درخواست‌ها رد می‌شوند (اختیاری) |
| آی‌پی‌های مجاز | فقط از این آی‌پی‌ها یا رنج‌ها (مثل 10.0.0.0/24) پذیرفته می‌شود (اختیاری) |
| دامنه‌های مجاز | برای استفاده در مرورگر؛ هدر Origin/Referer باید یکی از این دامنه‌ها باشد، مثل *.example.com (اختیاری) |
| سقف ساعتی | حداکثر درخواست در ساعت برای کل توکن و/یا هر سرویس جداگانه (اختیاری) |
در صفحه توکن‌ها، مصرف هر توکن (تعداد درخواست و هزینه به تفکیک روز و سرویس) را می‌بینید و می‌توانید توکن را ویرایش، غیرفعال یا حذف کنید یا کلید آن را عوض کنید. با حذف توکن، اعتبار باقی‌مانده‌اش به کیف پول برمی‌گردد.
یادآوری‌ها
وقتی اعتبار یک توکن رو به پایان باشد (کمتر از ۱۰٪)، تمام شود، یا تاریخ انقضای آن نزدیک باشد یا بگذرد، پیامک به شماره تایید‌شده شما و اعلان در داشبورد ارسال می‌شود.
نکات مهم
- خطاها هزینه ندارند: اگر درخواستی به دلیل خطای ما (کد 5xx) انجام نشود یا ورودی آن نادرست باشد و رد شود (کد 400 یا 422)، هزینه‌ای کسر نمی‌شود.
- ترتیب مختصات: در سرویس‌های POST مختصات چندضلعی و خط به شکل
[lat, lon]است. - امنیت: برای استفاده از سرور، آی‌پی سرور را در توکن محدود کنید. اگر توکن را در مرورگر استفاده می‌کنید، حتما دامنه مجاز و سقف اعتبار و درخواست ساعتی برایش تعیین کنید.
کدهای خطای عمومی
| کد | خطا | توضیح | هزینه کسر می‌شود؟ |
|---|---|---|---|
| 401 | missing_token / invalid_token | توکن ارسال نشده یا نامعتبر است | خیر |
| 401 | token_disabled | توکن غیرفعال شده است | خیر |
| 402 | insufficient_credit | اعتبار توکن تمام شده است؛ از کیف پول به آن اعتبار اضافه کنید | خیر |
| 403 | service_not_allowed | این توکن به این سرویس دسترسی ندارد | خیر |
| 403 | token_expired | تاریخ انقضای توکن گذشته است | خیر |
| 403 | ip_not_allowed / domain_not_allowed | درخواست از آی‌پی یا دامنه غیرمجاز | خیر |
| 405 | method_not_allowed | متد HTTP اشتباه است | خیر |
| 429 | rate_limited | سقف درخواست ساعتی توکن پر شده است | خیر |
| 429 | spend_limit_reached | سقف مصرف دوره‌ای توکن پر شده است؛ resets_at زمان شروع دوره بعد است | خیر |
| 502 | upstream_unavailable | سرویس موقتا در دسترس نیست | خیر |
| 5xx | — | خطای داخلی سرویس | خیر |
APIراهنماسرویس‌های مکانی