راهنمای API سرویس‌های مکانی

شروع سریع

1. ثبت‌نام کنید و شماره موبایل را تایید کنید؛ ۲۰۰ هزار ژئوکوین هدیه به کیف پول شما اضافه می‌شود.
2. در توکن‌های API یک توکن بسازید و بخشی از موجودی کیف پول را به آن بدهید.
3. کلید توکن را در هدر Authorization بفرستید:

curl -G "https://cloud.geotajak.ir/api/geo/geocode" \
  --data-urlencode "q=میدان آزادی تهران" \
  --data-urlencode "limit=1" \
  -H "Authorization: Bearer $GEOTAJAK_API_KEY"

احراز هویت

کلید توکن (با پیشوند gk_) را به یکی از این سه روش بفرستید؛ روش اول توصیه می‌شود:

کلید را در کد عمومی (مثلا اپلیکیشن یا صفحه وب) قرار ندهید مگر اینکه برای آن توکن دامنه مجاز، سقف مصرف و سقف درخواست ساعتی تعیین کرده باشید. برای سرور، آی‌پی سرور را در توکن محدود کنید. اگر کلید لو رفت، در صفحه توکن‌ها «کلید جدید» بزنید.

کیف پول و هزینه

هر سرویس قیمت مشخصی برای هر درخواست دارد. هزینه هر درخواست موفق از اعتبار توکنی که با آن فراخوانی می‌کنید کم می‌شود؛ اشتراک یا خرید جداگانه لازم نیست. اعتبار توکن را از کیف پول اضافه می‌کنید و هر وقت خواستید اعتبار باقی‌مانده را به کیف پول برمی‌گردانید (با حذف توکن هم برمی‌گردد). واحد همه قیمت‌ها «ژئوکوین» است: کیف پول با خرید بسته ژئوکوین از درگاه بانکی شارژ می‌شود و فاکتور هر خرید در داشبورد ثبت می‌شود.

توکن‌ها و محدودیت‌ها

به تعداد دلخواه توکن بسازید (مثلا یکی برای هر برنامه یا محیط). هر توکن این تنظیمات را دارد:

وقتی اعتبار توکن کمتر از ۱۰٪ شود یا تمام شود، یا تاریخ انقضا نزدیک باشد یا بگذرد، پیامک و اعلان داشبورد دریافت می‌کنید.

هدرهای پاسخ

خطاها

خطاهای مربوط به توکن و هزینه با بدنه {"error": "...", "message": "..."} برمی‌گردند؛ خطاهای ورودی هر سرویس با {"detail": "..."}.

نمونه کد

Python

import os, requests

API = "https://cloud.geotajak.ir/api/geo"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['GEOTAJAK_API_KEY']}"

resp = session.post(f"{API}/reverse", json={"lat": 35.6892, "lon": 51.3890}, timeout=60)
if resp.status_code == 402:
    print("اعتبار توکن تمام شده است")
resp.raise_for_status()
print(resp.json(), resp.headers["X-Credit-Remaining"])

JavaScript

const API = "https://cloud.geotajak.ir/api/geo";
const headers = { Authorization: `Bearer ${process.env.GEOTAJAK_API_KEY}` };

const res = await fetch(`${API}/route?from_lat=35.6892&from_lon=51.3890&to_lat=32.6539&to_lon=51.6660`, { headers });
if (!res.ok) throw new Error((await res.json()).message);
console.log(await res.json(), res.headers.get("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>

رنگ‌ها، فونت و گردی گوشه‌ها را یک بار در «قالب رنگ ویجت‌ها»ی توکن (صفحه توکن‌های API) تنظیم کنید تا همه ویجت‌های آن توکن با سایت شما هماهنگ باشند؛ نتیجه را قبل از استفاده در «آزمایشگاه سرویس» صفحه هر سرویس ببینید. چون کلید در کد صفحه دیده می‌شود، برای سایت یک توکن جدا با «دامنه مجاز» و «سقف مصرف» بسازید.

اتصال با MCP (برای دستیارهای هوش مصنوعی)

اگر دستیار یا ایجنت هوش مصنوعی می‌سازید، به‌جای نوشتن کد برای هر API می‌توانید همه سرویس‌ها را با پروتکل MCP به مدل بدهید. آدرس سرور https://cloud.geotajak.ir/mcp است و با همان توکن API کار می‌کند؛ هر فراخوانی ابزار برابر یک درخواست همان سرویس حساب می‌شود.

Claude Code

claude mcp add --transport http geotajak https://cloud.geotajak.ir/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Cursor، VS Code و برنامه‌های مشابه

{
  "mcpServers": {
    "geotajak": {
      "url": "https://cloud.geotajak.ir/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

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

سرویس‌ها

فهرست کامل سرویس‌ها با قیمت، میزان استفاده، نمونه کد و امکان امتحان مستقیم در صفحه سرویس‌ها است. سوالی دارید؟ از بخش تیکت‌ها بپرسید یا از دستیار هوشمند کمک بگیرید.