جستجو، تکمیل خودکار و نقطه به آدرس — مستندات

جستجو

GET https://api.uttamap.ir/v1/search

پارامتر	توضیح
`q`	متن جستجو، حداکثر ۲۵۰ نویسه (الزامی)
`city`	محدود کردن به یک شهر، مثل `تبریز`
`near`	`lat,lng` برای اولویت دادن به نتایج نزدیک
`limit`	۱ تا ۱۰، پیش‌فرض ۵

curl -G https://api.uttamap.ir/v1/search -H "X-Api-Key: um_sk_..." \
  --data-urlencode "q=خیابان توانیر جنوبی" --data-urlencode "city=تبریز"

واژه‌هایی مثل «خیابان» و «بلوار»، پیشوندهایی مثل «شهید»، «ي» و «ی» عربی و نیم‌فاصله یکسان‌سازی می‌شوند. هر نتیجه:

فیلد	معنی
`label`	عنوان خوانا برای نمایش
`location`	`lat` و `lng`
`components`	استان، شهر، محله، خیابان (هر کدام که معلوم باشد)
`precision`	`street`، `landmark`، `district`، `city`، ...
`bbox`	`[minLng, minLat, maxLng, maxLat]`
`id`	شناسهٔ OSM، مثل `osm:w123456`

در OpenStreetMap ایران پلاک ساختمان‌ها تقریباً ثبت نشده. دقت واقعی جستجوی آدرس «سطح خیابان» است و precision همیشه همین را صادقانه می‌گوید.

تکمیل خودکار

GET https://api.uttamap.ir/v1/autocomplete?q=میدان آز&near=35.7,51.4&limit=5

برای کادر جستجوی هم‌زمان با تایپ: حداقل ۲ نویسه و پاسخ معمولاً زیر ۱۵۰ میلی‌ثانیه. با کلید عمومی از مرورگر صدا بزنید و بین کلیدها ۲۰۰ میلی‌ثانیه صبر (debounce) بگذارید تا درخواست اضافه شمرده نشود.

نقطه به آدرس (reverse)

GET https://api.uttamap.ir/v1/reverse?lat=35.6997&lng=51.3380

{
  "results": [
    {
      "label": "برج آزادی، میدان آزادی، تهران",
      "components": {
        "province": "استان تهران",
        "city": "تهران",
        "district": "منطقه ۹ شهر تهران",
        "street": "میدان آزادی"
      },
      "precision": "landmark"
    }
  ]
}

کاربرد رایج: پر کردن خودکار فرم آدرس از روی لوکیشن گوشی مشتری.