ایران نت
زیرساخت، امنیت و رشد دیجیتال کسب‌وکارها میزبانی، دامنه، طراحی، پشتیبانی و اتوماسیون در یک مجموعه
IRANNET GEO / DEVELOPERS

موقعیت را به
محصولتان وصل کنید.

زیرساخت جغرافیایی را دوباره نسازید. جستجو، آدرس و محدودهٔ استاندارد را از یک API بگیرید و روی منطق محصول خود تمرکز کنید.

شروع اتصال درخواست دسترسی آزمایشی
AUTHENTICATION SECRET ON SERVER
01  Your application backend
    Site Credential / Secret
                  ↓
02  POST /v1/token
    Short-lived, scoped JWT
                  ↓
03  Browser / Application
    Search · Reverse · Areas
01 / QUICK START

از درخواست دسترسی تا اولین اتصال

این راهنما معماری و قابلیت‌های عمومی را توضیح می‌دهد. آدرس پایهٔ سرویس و قرارداد دقیق پارامترها و پاسخ‌ها را هنگام دریافت دسترسی از ایران‌نت بگیرید.

  1. برای سایت خود دسترسی بگیرید.از پنل مشتریان، درخواست اتصال یا آزمایش Starter را ثبت کنید.
  2. Credential را روی Backend نگه دارید.Secret دائمی را وارد کد عمومی، فایل JavaScript یا مخزن عمومی نکنید.
  3. توکن کوتاه‌عمر دریافت کنید.Backend از مسیر POST /v1/token توکن با Scope مجاز دریافت می‌کند.
  4. کلاینت را به API متصل کنید.از Search، Reverse و Areas متناسب با تجربهٔ کاربر استفاده کنید و مصرف را پایش کنید.
نمونهٔ جریان اتصال

شبه‌کد زیر معماری را نشان می‌دهد؛ SDK قابل نصب یا نمونهٔ اجرایی قرارداد API نیست.

Integration flow · pseudocode
// SERVER ONLY — use your issued integration contract
credential = read_secret_from_server_environment()
token = issue_short_lived_token(credential, allowed_scopes)

// CLIENT — permanent credentials never reach the browser
location = call_geo_api(token, selected_operation)
store_location_and_canonical_area_ids(location)
02 / AUTHENTICATION

Secret روی سرور. دسترسی محدود روی کلاینت.

هر سایت Credential مستقل دارد. Backend با آن توکن صادر می‌کند و کلاینت فقط JWT کوتاه‌عمر را دریافت می‌کند. توکن می‌تواند به Site، Origin و Scope محدود شود.

geo.search

جستجوی مکان و آدرس

geo.reverse

تبدیل مختصات به آدرس

geo.areas

محدوده‌های اداری

چرخهٔ Credential شامل Active، Retiring و Revoked است. برای تعویض امن، ابتدا Credential جدید را در مصرف‌کننده فعال و بررسی کنید و سپس Credential قبلی را لغو کنید.

03 / API REFERENCE

مسیرهای اصلی، در یک نگاه

APIهای معرفی‌شده در قرارداد محصول
مسیرکاربرددسترسی
POST /v1/tokenدریافت توکن کوتاه‌عمر از BackendCredential سایت
/v1/searchجستجوی مکان، شهر، محله یا آدرسgeo.search
/v1/reverseمختصات به آدرس و اطلاعات محدودهgeo.reverse
/v1/areas/searchجستجوی محدودهٔ اداریgeo.areas
/v1/areas/resolveتشخیص محدودهٔ موقعیتgeo.areas
/v1/areas/{area_id}اطلاعات محدوده با شناسهٔ استانداردgeo.areas
GET /v1/usageپلن، دوره، مصرف، ظرفیت و محدودیت‌هاطبق قرارداد دسترسی سرویس
شناسهٔ محدوده را حفظ کنید.

برای اتصال قوانین و داده‌ها، area_id استاندارد را ذخیره کنید؛ نام نمایشی شهر یا استان به‌تنهایی کلید مناسبی برای منطق سیستم نیست.

فیلدهای Request و Response، شیوهٔ ارسال Credential و جزئیات هدرها باید از قرارداد رسمی اتصال دریافت شوند؛ این صفحه مقادیر یا امضای حدسی ارائه نمی‌کند.

04 / USAGE

مصرف را بخشی از تجربهٔ محصول کنید.

هر Search، Reverse یا عملیات Areas پذیرفته‌شده با نتیجهٔ معتبر success یا negative، یک location_unit مصرف می‌کند. رد احراز هویت، Scope، اعتبارسنجی، نرخ یا ظرفیت و خطای داخلی Backend مصرف تجاری نیستند.

ظرفیت پایه۵۰٬۰۰۰
+
افزایش ظرفیت۵۰٬۰۰۰
=
ظرفیت مؤثر۱۰۰٬۰۰۰

اگر ۵۰٬۰۰۰ واحد قبلاً مصرف شده باشد، با این افزایش ۵۰٬۰۰۰ واحد باقی می‌ماند. Refresh فقط متعلق به همان دوره است و نرخ دقیقه، ساعت و روز را تغییر نمی‌دهد.

با GET /v1/usage، پلن، آزمایش، وضعیت دوره، مصرف، ظرفیت پایه و افزوده، باقیمانده، درصد مصرف، محدودیت‌ها و زمان بازنشانی را در داشبورد خود نمایش دهید.

05 / ERROR HANDLING

هر محدودیت، پیام و اقدام خودش را دارد.

خطاهای تجاری و واکنش پیشنهادی رابط کاربر
HTTP / کدمعنارفتار پیشنهادی
429 usage_limit_reachedظرفیت دوره تمام شدهاطلاع به مدیر و بررسی افزایش ظرفیت؛ از تکرار بی‌وقفه جلوگیری کنید.
429 rate_limit_reachedعبور از محدودیت سرعتکاهش نرخ درخواست و تلاش مجدد کنترل‌شده مطابق قرارداد.
403 trial_expiredپایان دوره آزمایشینمایش مسیر ادامهٔ اشتراک برای مدیر.
403 commercial_period_requiredدورهٔ مصرف وجود نداردبررسی وضعیت تجاری سرویس در پنل مشتری.

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

06 / INTEGRATION CHECKLIST

اتصالی که برای استفادهٔ واقعی آماده است.

  • Secret دائمی فقط در محیط امن Backend نگهداری شود.
  • Origin و Scopeها با مصرف واقعی سایت هماهنگ باشند.
  • جستجوی کاربر با تأخیر کوتاه و کنترل درخواست‌های تکراری انجام شود.
  • پاسخ بدون نتیجه، خطای شبکه و اتمام ظرفیت، پیام روشن داشته باشند.
  • شناسهٔ محدوده همراه با دادهٔ موقعیت حفظ شود.
  • مصرف و انقضای توکن در چرخهٔ اتصال مدیریت شوند.
  • قرارداد دقیق API پیش از پیاده‌سازی با نسخهٔ سرویس تطبیق داده شود.
روی وردپرس کار می‌کنید؟

برای انتخاب موقعیت، دفترچه آدرس، Checkout و قوانین فروش و ارسال، از IranNet Location شروع کنید. برای رندر و اتصال سفارشی، Shortcode و API PHP نیز دارد.

اولین اتصال را با هم شروع کنیم.

برای دریافت دسترسی و قرارداد اتصال متناسب با پروژه، وارد پنل مشتریان شوید.

درخواست دسترسی توسعه‌دهنده تعرفه‌های سرویس