راهنمای API جستجوی مکان سرویس می‌مپس

یاد بگیرید چگونه از API جستجوی مکان می‌مپس در پروژه‌های خود استفاده کنید

معرفی API جستجوی مکان

API جستجوی مکان می‌مپس امکان جستجوی هوشمند مکان‌ها، خیابان‌ها و مناطق را فراهم می‌کند

ویژگی‌های کلیدی

جستجوی هوشمند

جستجوی فازی و تطبیقی مکان‌ها

مختصات دقیق

مختصات جغرافیایی دقیق برای هر مکان

مرتب‌سازی بر اساس فاصله

مرتب‌سازی نتایج بر اساس نزدیکی به موقعیت کاربر

دسته‌بندی مکان‌ها

فیلتر کردن بر اساس نوع مکان

نقطه پایانی API

آدرس و روش استفاده از API جستجوی مکان

نقطه پایانی جستجو
URL:
https://memaps.ir/api/search/places

Method:
GET

Content-Type:
application/json
مثال ساده:
GET https://memaps.ir/api/search/places?q=تهران&limit=10

پارامترهای API

پارامترهای قابل استفاده در API جستجوی مکان

پارامتر نوع اجباری توضیح مثال
q string عبارت جستجو تهران
lat float عرض جغرافیایی برای مرتب‌سازی بر اساس فاصله 35.6892
lng float طول جغرافیایی برای مرتب‌سازی بر اساس فاصله 51.3890
type string نوع مکان (points, streets, areas) points
limit integer تعداد نتایج (پیش‌فرض: 20) 10

مثال‌های عملی

مثال‌های مختلف استفاده از API جستجوی مکان

جستجوی ساده
درخواست:
GET https://memaps.ir/api/search/places?q=تهران&limit=5
پاسخ:
{
  "success": true,
  "count": 5,
  "results": [
    {
      "id": "123456",
      "name": "تهران",
      "type": "city",
      "lat": 35.6892,
      "lng": 51.3890,
      "city": "تهران",
      "details": "پایتخت ایران"
    }
  ]
}
جستجو با موقعیت
درخواست:
GET https://memaps.ir/api/search/places?q=رستوران&lat=35.6892&lng=51.3890&limit=10
پاسخ:
{
  "success": true,
  "count": 10,
  "results": [
    {
      "id": "789012",
      "name": "رستوران شاندیز",
      "type": "restaurant",
      "lat": 35.6895,
      "lng": 51.3895,
      "city": "تهران",
      "distance": 0.5
    }
  ]
}
جستجوی خیابان‌ها
درخواست:
GET https://memaps.ir/api/search/places?q=ولیعصر&type=streets&limit=5
پاسخ:
{
  "success": true,
  "count": 5,
  "results": [
    {
      "id": "345678",
      "name": "خیابان ولیعصر",
      "type": "street",
      "lat": 35.6892,
      "lng": 51.3890,
      "city": "تهران",
      "details": "طولانی‌ترین خیابان خاورمیانه"
    }
  ]
}
جستجوی مناطق
درخواست:
GET https://memaps.ir/api/search/places?q=شمال تهران&type=areas&limit=5
پاسخ:
{
  "success": true,
  "count": 5,
  "results": [
    {
      "id": "901234",
      "name": "شمال تهران",
      "type": "area",
      "lat": 35.7892,
      "lng": 51.3890,
      "city": "تهران",
      "details": "منطقه شمالی تهران"
    }
  ]
}

ساختار پاسخ

توضیح کامل ساختار پاسخ API

ساختار کلی پاسخ

{
  "success": boolean,      // وضعیت موفقیت درخواست
  "count": number,         // تعداد نتایج
  "results": [             // آرایه نتایج
    {
      "id": string,        // شناسه یکتا
      "name": string,      // نام مکان
      "type": string,      // نوع مکان
      "lat": number,       // عرض جغرافیایی
      "lng": number,       // طول جغرافیایی
      "city": string,      // نام شهر (اختیاری)
      "details": string,   // جزئیات اضافی (اختیاری)
      "distance": number   // فاصله از موقعیت کاربر (اختیاری)
    }
  ]
}

کدهای خطا

کد خطا توضیح راه حل
400 پارامترهای نامعتبر پارامتر q را بررسی کنید
404 نتیجه‌ای یافت نشد عبارت جستجو را تغییر دهید
500 خطای سرور دوباره تلاش کنید

دسته‌بندی‌های مکان

انواع مختلف مکان‌هایی که می‌توانید جستجو کنید

📍 نقاط (Points)

مکان‌های نقطه‌ای مانند:

  • ✅ رستوران‌ها
  • ✅ هتل‌ها
  • ✅ بانک‌ها
  • ✅ داروخانه‌ها
  • ✅ پمپ بنزین
  • ✅ مراکز خرید
  • ✅ دانشگاه‌ها
  • ✅ بیمارستان‌ها
type=points
🛣️ خیابان‌ها (Streets)

مسیرهای ارتباطی مانند:

  • ✅ خیابان‌ها
  • ✅ بزرگراه‌ها
  • ✅ جاده‌ها
  • ✅ کوچه‌ها
  • ✅ پل‌ها
  • ✅ تونل‌ها
  • ✅ میدان‌ها
  • ✅ تقاطع‌ها
type=streets
🏘️ مناطق (Areas)

مناطق و نواحی مانند:

  • ✅ محله‌ها
  • ✅ شهرها
  • ✅ روستاها
  • ✅ پارک‌ها
  • ✅ دانشگاه‌ها
  • ✅ فرودگاه‌ها
  • ✅ مراکز تجاری
  • ✅ مناطق صنعتی
type=areas

مثال‌های JavaScript

نحوه استفاده از API در JavaScript

جستجوی ساده
// جستجوی ساده
async function searchPlaces(query) {
    try {
        const response = await fetch(
            `https://memaps.ir/api/search/places?q=${encodeURIComponent(query)}`
        );
        const data = await response.json();
        
        if (data.success) {
            console.log('نتایج:', data.results);
            return data.results;
        } else {
            console.error('خطا در جستجو');
        }
    } catch (error) {
        console.error('خطای شبکه:', error);
    }
}

// استفاده
searchPlaces('تهران');
جستجو با موقعیت
// جستجو با موقعیت کاربر
async function searchNearby(query, lat, lng) {
    try {
        const response = await fetch(
            `https://memaps.ir/api/search/places?q=${encodeURIComponent(query)}&lat=${lat}&lng=${lng}&limit=10`
        );
        const data = await response.json();
        
        if (data.success) {
            // مرتب‌سازی بر اساس فاصله
            const sortedResults = data.results.sort((a, b) => 
                (a.distance || 0) - (b.distance || 0)
            );
            return sortedResults;
        }
    } catch (error) {
        console.error('خطا:', error);
    }
}

// استفاده
searchNearby('رستوران', 35.6892, 51.3890);
جستجوی فیلتر شده
// جستجو بر اساس نوع
async function searchByType(query, type) {
    try {
        const response = await fetch(
            `https://memaps.ir/api/search/places?q=${encodeURIComponent(query)}&type=${type}&limit=20`
        );
        const data = await response.json();
        
        if (data.success) {
            return data.results;
        }
    } catch (error) {
        console.error('خطا:', error);
    }
}

// جستجوی خیابان‌ها
searchByType('ولیعصر', 'streets');

// جستجوی رستوران‌ها
searchByType('رستوران', 'points');
نمایش روی نقشه
// نمایش نتایج روی نقشه Leaflet
async function searchAndShowOnMap(query, map) {
    try {
        const response = await fetch(
            `https://memaps.ir/api/search/places?q=${encodeURIComponent(query)}&limit=10`
        );
        const data = await response.json();
        
        if (data.success) {
            data.results.forEach(place => {
                const marker = L.marker([place.lat, place.lng])
                    .bindPopup(`
                        <strong>${place.name}</strong><br>
                        ${place.city ? `شهر: ${place.city}<br>` : ''}
                        ${place.details || ''}
                    `)
                    .addTo(map);
            });
        }
    } catch (error) {
        console.error('خطا:', error);
    }
}

// استفاده
searchAndShowOnMap('تهران', map);
پشتیبانی از CORS

API جستجوی مکان می‌مپس از CORS پشتیبانی می‌کند و می‌توانید مستقیماً از مرورگر استفاده کنید:

// درخواست از مرورگر
fetch('https://memaps.ir/api/search/places?q=تهران')
    .then(response => response.json())
    .then(data => {
        console.log('نتایج:', data.results);
    })
    .catch(error => {
        console.error('خطا:', error);
    });