آب‌های سطحی، مصرف آب، رشد شهر، غربال نیروگاه، شکاف پوشش موبایل، خوراک هشدار و نیاز آبیاری

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

شش سرویس اول آفلاین‌اند (پاسخ "mode": "offline" و منبع، مجوز و تاریخ داده را دارد). خوراک هشدار، بولتن روزانه و نیاز آبیاری از منابع زنده هواشناسی و ماهواره‌ای می‌خوانند ("mode": "online"). در سرویس‌هایی که explain دارند، با explain=true یک متن تحلیلی هم از روی همان عددها نوشته می‌شود.

محدوده را در سرویس‌های POST به یکی از این چهار شکل بدهید: place (نام شهرستان یا استان)، bbox (west,south,east,north)، polygon ([[lat, lon], …]) یا lat و lon و radius_km.

۱. آب‌های سطحی و تغییر آن‌ها

curl -X POST "https://cloud.geotajak.ir/api/geo/water/surface" \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"bbox": "44.9,37.0,46.1,38.4"}'

{
  "summary": "محدوده انتخابی: 2,377.6 کیلومتر مربع آب دائمی و 2,765.4 کیلومتر مربع آب فصلی؛ نسبت به پیش از سال ۲۰۰۰ روند «کاهش» (از دست رفته 3,007.6، افزوده 216.8 کیلومتر مربع).",
  "permanent_water_km2": 2377.59, "seasonal_water_km2": 2765.4, "water_share_pct": 31.43,
  "change": {"lost_km2": 3007.6, "gained_km2": 216.84, "net_km2": -2111.93, "trend": "کاهش", "periods": "1984-1999 → 2000-2021"}
}

این نمونه دریاچه ارومیه است. «دائمی» یعنی دست‌کم ۷۵٪ زمان زیر آب، «فصلی» ۱۰ تا ۷۵٪. داده از تصاویر لندست است؛ آب زیر پوشش گیاهی و نهرهای باریک‌تر از ۳۰ متر دیده نمی‌شود.

۲. مصرف واقعی آب (تبخیر-تعرق)

curl -G "https://cloud.geotajak.ir/api/geo/water/evapotranspiration" \
  --data-urlencode "lat=32.52" \
  --data-urlencode "lon=51.85" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "summary": "این نقطه: تبخیر-تعرق واقعی حدود 522 میلی‌متر در سال در برابر 128 میلی‌متر بارش (نسبت 4.08)؛ مصرف آب خیلی بیشتر از بارش است: آبیاری، آب زیرزمینی کم‌عمق یا پیکره آبی؛ پوشش زمین: زمین کشاورزی.",
  "mean_et_mm": 522, "mean_rain_mm": 128, "et_to_rain_ratio": 4.08, "extra_water_mm": 394, "water_volume_m3_per_hectare": 3940,
  "yearly": [{"year": 2018, "et_mm": 300, "rain_mm": 141, "et_minus_rain_mm": 159}]
}

extra_water_mm آبی است که بیشتر از بارش مصرف شده، یعنی از کانال، چاه یا آب زیرزمینی آمده است. با این سرویس می‌شود زمین آبی را از دیم جدا کرد و مصرف آب یک مزرعه را سال به سال دید. دقت حدود یک کیلومتر است.

۳. گزارش تنش آبی یک محدوده

curl -X POST "https://cloud.geotajak.ir/api/geo/water/brief" \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"lat": 32.65, "lon": 51.67, "radius_km": 30, "explain": true}'

{
  "summary": "شعاع 30 کیلومتری: شاخص تنش آبی 0.90 از ۱ (بسیار زیاد)؛ بارش میانگین 122 میلی‌متر (افزایشی)؛ مصرف آب 308 میلی‌متر (نسبت به بارش 2.53)؛ آب سطحی: افزایش؛ تا میانه قرن +2.8 درجه.",
  "water_stress_index": 0.9, "water_stress_level": "بسیار زیاد",
  "rainfall": {"mean_mm": 122, "trend_pct_per_decade": 4.1},
  "water_use": {"mean_et_mm": 308, "et_to_rain_ratio": 2.53, "extra_water_million_m3": 526.1},
  "climate_2050": {"warming_c": 2.8, "precipitation_change_pct": 2.1}
}

همین درخواست برای اطراف رشت شاخص ۰٫۲۴ (کم) می‌دهد. شاخص یک غربال منطقه‌ای است: برداشت چاه‌ها، حقابه‌ها و انتقال آب در آن نیست. متن گزارش در brief برمی‌گردد.

۴. رشد سطح ساخته‌شده شهر

curl -X POST "https://cloud.geotajak.ir/api/geo/urban/growth" \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"bbox": "51.09,35.56,51.61,35.84"}'

{
  "summary": "محدوده انتخابی: سطح ساخته‌شده از 164.8 کیلومتر مربع در 1980 به 239.0 در 2020 رسیده (+45٪، سالانه 0.9٪)؛ سرانه ساخته‌شده حدود 26 متر مربع برای هر نفر.",
  "epochs": [{"year": 1980, "built_up_km2": 164.79}, {"year": 2000, "built_up_km2": 207.72}, {"year": 2020, "built_up_km2": 239.02}],
  "growth_pct": 45.0, "annual_growth_pct": 0.93, "population_2020": 9258908, "built_up_m2_per_person": 26
}

«سطح ساخته‌شده» سطح بام ساختمان‌هاست، نه کل محدوده شهر با خیابان و حیاط؛ برای همین از عدد نقشه کاربری کمتر است.

۵. غربال سایت نیروگاه خورشیدی و بادی

curl -X POST "https://cloud.geotajak.ir/api/geo/energy/site-screen" \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"candidates": [{"lat": 31.95, "lon": 54.05, "name": "دشت یزد"}, {"lat": 35.70, "lon": 51.40, "name": "مرکز تهران"}], "technology": "solar"}'

{
  "summary": "برای نیروگاه خورشیدی، از 2 گزینه بهترین «دشت یزد» با امتیاز 84 (بسیار مناسب) است.",
  "ranking": [{"rank": 1, "name": "دشت یزد", "score": 84, "rating": "بسیار مناسب", "land_cover": "زمین بایر و کم‌پوشش", "limiting_factors": [], "unknown_factors": ["فاصله تا شبکه برق"]},
              {"rank": 2, "name": "مرکز تهران", "score": 25, "rating": "نامناسب", "excluded_reason": "زمین «ساخته‌شده» است"}]
}

تا ۸ گزینه. عوامل: تولید پنل یا سرعت باد، شیب، فاصله تا پست و خط برق، فاصله تا جاده و بیرون بودن از پهنه سیلاب. زمین ساخته‌شده، آب، تالاب و جنگل حداکثر ۲۵ می‌گیرد. عاملی که داده ندارد در unknown_factors می‌آید و در امتیاز حساب نمی‌شود. مالکیت زمین، مناطق حفاظت‌شده و ظرفیت شبکه بررسی نمی‌شود.

۶. جمعیت و روستاهای بدون پوشش موبایل

curl -X POST "https://cloud.geotajak.ir/api/geo/coverage/gap" \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"place": "شهرستان ابرکوه"}'

برای هر اپراتور و هر نسل (2G تا 5G) سه سهم برمی‌گردد: زیر پوشش، بدون پوشش و نامعلوم. جایی که لایه پوشش اپراتور کامل نیست، مردم «نامعلوم» شمرده می‌شوند نه «بدون پوشش». uncovered_population جمعیتی است که با اطمینان بیرون از پوشش همه اپراتورهاست و uncovered_settlements فهرست شهرها و روستاهای بدون پوشش.

۷. خوراک هشدارهای یک منطقه

curl -G "https://cloud.geotajak.ir/api/geo/alerts/feed" \
  --data-urlencode "lat=35.6892" \
  --data-urlencode "lon=51.3890" \
  --data-urlencode "radius_km=200" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "summary": "این نقطه: مورد فعالی ثبت نشده است.",
  "max_level": 0, "max_level_fa": "عادی", "count": 0, "alerts": [], "aqi": 89, "population_within_5km": 1564272
}

هر مورد kind (هوا، زمین‌لرزه، آتش‌سوزی، کیفیت هوا)، level (۱ زرد، ۲ نارنجی، ۳ قرمز)، عنوان، جزئیات و زمان دارد و فهرست بر اساس شدت مرتب است. اگر یکی از منابع جواب ندهد در unavailable_sources نام برده می‌شود و بقیه پاسخ می‌آید. برای اعلان خودکار، این آدرس را هر چند دقیقه یک بار صدا بزنید. این خوراک جایگزین هشدار رسمی دستگاه‌های مسئول نیست.

دریافت خودکار هشدار با وب‌هوک

اگر نمی‌خواهید خودتان این آدرس را مرتب صدا بزنید، در داشبورد بخش پایش هشدار یک مکان، سطح هشدار، فاصله بررسی (از هر ۱۵ دقیقه تا روزی یک بار) و آدرس وب‌هوک سامانه خود را ثبت کنید. ژئوتاجک خوراک هشدار را برای شما بررسی می‌کند و هر هشدار جدید را یک بار با یک درخواست POST به آدرس شما می‌فرستد:

{
  "event": "alerts",
  "watch": {"id": "…", "name": "تهران", "lat": 35.7, "lon": 51.4, "radius_km": 100, "min_level": 2},
  "checked_at": "2026-10-09T08:30:00+00:00",
  "max_level": 3, "max_level_fa": "قرمز",
  "new_alerts": [{"kind": "earthquake", "kind_fa": "زمین‌لرزه", "level": 3, "title": "زمین‌لرزه 6.1", "detail": "…", "when": "…", "lat": 35.9, "lon": 51.9}],
  "alerts": []
}

• هر بررسی یک درخواست همین سرویس است و هزینه آن از توکنی که برای پایش انتخاب کرده‌اید کم می‌شود؛ هزینه تقریبی روزانه در کارت هر پایش نوشته شده است.
• هر پیام با کلید امضای همان پایش امضا می‌شود: هدر X-GeoTajak-Signature برابر sha256= به‌علاوه HMAC-SHA256 بدنه خام با آن کلید است. قبل از اعتماد به پیام آن را بررسی کنید.
• سامانه شما باید در ۱۰ ثانیه با کد ۲xx پاسخ دهد؛ وگرنه در بررسی بعدی دوباره تلاش می‌شود و پس از ۲۰ بار ناموفق پیاپی پایش متوقف می‌شود.
• با دکمه «پیام آزمایشی» یک نمونه رایگان (هدر X-GeoTajak-Event: test) به وب‌هوک خود بفرستید.
• آدرس وب‌هوک باید یک نشانی عمومی اینترنت باشد.

نمونه بررسی امضا در پایتون:

import hashlib, hmac

def is_from_geotajak(secret: str, raw_body: bytes, signature_header: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)

۸. بولتن روزانه وضعیت منطقه

curl -G "https://cloud.geotajak.ir/api/geo/bulletin/daily" \
  --data-urlencode "lat=35.6892" \
  --data-urlencode "lon=51.3890" \
  --data-urlencode "explain=true" \
  -H "Authorization: Bearer YOUR_TOKEN"

وضعیت هوای اکنون، پیش‌بینی سه روز آینده، هشدارها و شاخص کیفیت هوا در یک پاسخ؛ با explain=true متن آماده بولتن در bulletin برمی‌گردد.

۹. نیاز آبیاری محصول

curl -G "https://cloud.geotajak.ir/api/geo/agri/irrigation-advice" \
  --data-urlencode "lat=32.52" \
  --data-urlencode "lon=51.85" \
  --data-urlencode "crop=wheat" \
  --data-urlencode "method=surface" \
  --data-urlencode "area_hectare=5" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "summary": "این نقطه: گندم در کل فصل حدود 503 میلی‌متر آبیاری خالص لازم دارد؛ با روش سطحی (غرقابی / جوی‌پشته) 914 میلی‌متر (حدود 9,138 متر مکعب در هکتار)؛ اوج نیاز در اردیبهشت با روزانه 5.8 میلی‌متر.",
  "season_net_irrigation_mm": 503, "season_gross_irrigation_mm": 914, "volume_m3_per_hectare": 9138, "total_volume_m3": 45690,
  "peak_month": {"name": "اردیبهشت", "net_irrigation_mm": 175, "daily_mm": 5.8},
  "measured_water_use_mm": 522, "savings_with_drip_m3_per_hectare": 3554
}

محصول‌ها (crop): wheat گندم، barley جو، corn ذرت، rice برنج، alfalfa یونجه، tomato گوجه‌فرنگی، potato سیب‌زمینی، sugar_beet چغندر قند، cotton پنبه، pistachio پسته، grape انگور، saffron زعفران. روش آبیاری (method): surface سطحی، sprinkler بارانی، drip قطره‌ای.

برآورد از میانگین ۲۰ ساله اقلیم و ضرایب گیاهی FAO-56 است؛ تاریخ کشت، رقم، خاک و شوری آب نیاز واقعی را تغییر می‌دهد.

منبع داده

آب سطحی: JRC Global Surface Water (۱۹۸۴ تا ۲۰۲۱)؛ تبخیر-تعرق: FAO WaPOR نسخه ۳؛ سطح ساخته‌شده: GHSL؛ خورشید و باد: Global Solar Atlas و Global Wind Atlas؛ هوا: MET Norway؛ زمین‌لرزه: USGS؛ آتش: NASA FIRMS؛ کیفیت هوا: NASA GEOS-CF؛ اقلیم: NASA POWER. همه با مجوز آزاد. این داده‌ها مدل‌های جهانی‌اند: برای غربال و مقایسه مناسب‌اند و جای مطالعات محلی را نمی‌گیرند.

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

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