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

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

کاربردها

• جستجوی آدرس در فرم‌ها و اپلیکیشن‌های نقشه
• تبدیل فهرست آدرس مشتریان به نقطه روی نقشه
• پیدا کردن مختصات شهرها و روستاها برای تحلیل مکانی

دریافت توکن

1. وارد داشبورد ژئوتاژک کلود شوید و با خرید بسته ژئوکوین کیف پول خود را شارژ کنید (با تایید شماره موبایل، ۲۰۰ هزار ژئوکوین هدیه می‌گیرید).
2. در بخش توکن‌های API یک توکن بسازید، دسترسی «جستجوی آدرس و مکان (Geocoding)» را به آن بدهید و بخشی از موجودی کیف پول را به آن اختصاص دهید.
3. کلید توکن را کپی کنید و در هدر Authorization بفرستید.

هزینه هر درخواست در صفحه سرویس‌ها درج شده و از اعتبار همان توکن کم می‌شود؛ خرید جداگانه برای هر سرویس لازم نیست.

آدرس سرویس

GET https://cloud.geotajak.ir/api/geo/geocode

توکن را در هدر Authorization بفرستید:

Authorization: Bearer YOUR_TOKEN

(هدر X-API-Key: YOUR_TOKEN یا پارامتر ?api_key=YOUR_TOKEN هم پذیرفته می‌شود.)

پارامترها

نمونه درخواست

cURL

curl "https://cloud.geotajak.ir/api/geo/geocode?q=%D9%85%DB%8C%D8%AF%D8%A7%D9%86+%D8%A2%D8%B2%D8%A7%D8%AF%DB%8C+%D8%AA%D9%87%D8%B1%D8%A7%D9%86&limit=3" \
  -H "Authorization: Bearer YOUR_TOKEN"

Python

import requests

TOKEN = "YOUR_TOKEN"
resp = requests.get(
    "https://cloud.geotajak.ir/api/geo/geocode",
    params={"q": "میدان آزادی تهران", "limit": 3},
    headers={"Authorization": f"Bearer {TOKEN}"},
    timeout=60,
)
resp.raise_for_status()
print(resp.json())
print("اعتبار باقی‌مانده توکن:", resp.headers.get("X-Credit-Remaining"))

JavaScript

const TOKEN = "YOUR_TOKEN";
const res = await fetch(`https://cloud.geotajak.ir/api/geo/geocode?q=${encodeURIComponent("میدان آزادی تهران")}&limit=${encodeURIComponent("3")}`, {
  headers: { Authorization: `Bearer ${TOKEN}` },
});
const data = await res.json();
console.log(data, res.headers.get("X-Credit-Remaining"));

نمونه پاسخ

[
  {
    "lat": 35.6997,
    "lon": 51.3380,
    "display_name": "ایران، استان تهران، تهران، میدان آزادی",
    "address": {
      "city": "تهران",
      "state": "استان تهران",
      "country": "ایران",
      "country_code": "ir"
    },
    "osm_type": "way",
    "importance": 0.52
  }
]

هزینه و هدرهای پاسخ

هزینه هر درخواست موفق از اعتبار توکن کم می‌شود. در هر پاسخ این هدرها برگردانده می‌شوند:

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

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

خطاها

پاسخ خطا به این شکل است:

{"error": "insufficient_credit", "message": "اعتبار این توکن تمام شده است؛ از کیف پول خود به آن اعتبار اضافه کنید"}

نکته‌ها

• عبارت کوتاه‌تر و مشخص‌تر نتیجه دقیق‌تری می‌دهد؛ مثلا نام شهر را هم بیاورید.
• اگر فقط اولین نتیجه را لازم دارید limit=1 بفرستید.

---

سوالی دارید؟ از بخش تیکت‌ها در داشبورد با ما در ارتباط باشید.