جست‌وجو و پیشنهاد خودکار
پیشنهاد خودکار هنگام تایپ و جست‌وجوی کامل مکان‌ها، با یکدست‌سازی فارسی، محدوده، کشور و نوع نتیجه.
پیشنهاد خودکار یا جست‌وجو
GET /v1/autocompleteبرای هنگام تایپ: سریع، از کش، حداکثر ۱۰ نتیجه. سرویسmaps.autocomplete.GET /v1/searchبرای وقتی کاربر Enter را زد: دو موتور با هم جست‌وجو و نتیجه‌ها ادغام می‌شوند، تا ۲۰ نتیجه. سرویسmaps.search.
هر دو دسترسی maps:search می‌خواهند و هر پاسخ موفق یک واحد دارد (حتی بی نتیجه). پرسشی که پس از یکدست‌سازی از حداقل نویسه کوتاه‌تر است بی‌هزینه و بی تماس با موتور پاسخ خالی می‌گیرد.
درخواست
curl -sS "https://maps.namayek.com/v1/autocomplete?q=%D9%88%D9%86%DA%A9&lat=35.757&lng=51.41&limit=5" \ -H "X-Namayek-Key: $NAMAYEK_SECRET_KEY"curl -sS "https://maps.namayek.com/v1/search?q=%D8%A8%DB%8C%D9%85%D8%A7%D8%B1%D8%B3%D8%AA%D8%A7%D9%86&types=poi&countries=ir&limit=10" \ -H "X-Namayek-Key: $NAMAYEK_SECRET_KEY"map.addControl( new NamayekMaps.SearchControl({ placeholder: "جستجوی مکان", countries: ["ir"], onSelect(item) { console.log(item.title, item.lat, item.lng); }, }),);پارامترها
| پارامتر | نوع | لزوم | پیش‌فرض | توضیح |
|---|---|---|---|---|
q | string | لازم | — | متن جست‌وجو تا ۲۰۰ نویسه. اگر پس از یکدست‌سازی از حداقل پروژه کوتاه‌تر باشد، پاسخ خالی و بی‌هزینه است. |
lat | number | همراه lng | مرکز محدوده پروژه | عرض نقطه‌ای که نتیجه‌های نزدیک آن جلوتر می‌آیند؛ بین -90 و ۹۰. |
lng | number | همراه lat | مرکز محدوده پروژه | طول همان نقطه؛ بین -180 و ۱۸۰. |
limit | integer | اختیاری | تنظیم پروژه (۸) | تعداد نتیجه؛ autocomplete از ۱ تا ۱۰، search از ۱ تا سقف (۲۰). |
lang | fa | en | fa-en | اختیاری | زبان پیش‌فرض پروژه | زبان متن نتیجه‌ها؛ fa-en برای متن همان fa است. |
bbox | w,s,e,n | اختیاری | محدوده پروژه | نتیجه‌ها را به این مستطیل محدود می‌کند (w<e و s<n). |
countries | csv | اختیاری | تنظیم پروژه | ir یا فهرست کد دوحرفی کشورها، حداکثر ۲۰ کد. |
types | csv | اختیاری | همه | زیرمجموعه‌ای از poi، street، address، place، region، country. |
key | string | یا سرآیند | — | فقط کلید عمومی nmk_pk_ در نشانی؛ روی سرور کلید را در سرآیند X-Namayek-Key بفرستید. |
هر پارامتر فقط یک بار می‌آید (تکرار ⇒ INVALID_PARAM) و پارامتر ناشناخته نادیده گرفته می‌شود. عددها بی توان، بی رقم فارسی و حداکثر ۱۰ رقم اعشار.
پاسخ
{ "available": true, "degraded": false, "query": "میدان آزادی", "items": [ { "id": "osm:R123", "title": "میدان آزادی", "subtitle": "میدان", "address": "تهران، منطقه 9", "lat": 35.699722, "lng": 51.338056, "type": "place", "category": null, "kind": "place:square", "distance": 1250.4, "bbox": [51.33, 35.69, 51.35, 35.71], "source": "photon" } ], "attribution": "© مشارکت کنندگان OpenStreetMap"}| فیلد | نوع / مقدار | توضیح |
|---|---|---|
available | true | در پاسخ موفق همیشه true است؛ خطای ۵۰۳ available:false و items خالی دارد. |
degraded | boolean | true یعنی موتور پشتیبان پاسخ داد (کیفیت ممکن است کمتر باشد). |
query | string | متن یکدست‌شده‌ای که جست‌وجو شد. |
items | SearchItem[] | نتیجه‌ها به ترتیب مرتبط بودن. |
attribution | string | متن انتساب داده که باید کنار نتیجه‌ها نشان دهید. |
| فیلد | نوع / مقدار | توضیح |
|---|---|---|
id | string | شناسه پایدار؛ osm: با N/W/R و شماره، یا @lat,lng برای نتیجه بی شناسه. |
title | string | عنوان نتیجه، حداکثر ۱۲۰ نویسه. |
subtitle | string | null | دسته فارسی مکان («بیمارستان») یا نوع خیابان («خیابان»). |
address | string | نشانی خوانا با جداکننده «، »؛ ممکن است خالی باشد. |
lat / lng | number | مختصات با ۶ رقم اعشار. |
type | poi | street | address | place | region | country | نوع نتیجه. |
category | PoiCategory | null | یکی از ۱۲ دسته مکان، فقط برای poi. |
kind | string | null | برچسب منبع به شکل key:value (مثلا amenity:hospital). |
distance | number | null | فاصله به متر از lat,lng درخواست، اگر داده شده باشد. |
bbox | [w, s, e, n] | null | محدوده مکان‌های بزرگ (شهر، استان). |
source | photon | nominatim | موتوری که نتیجه را یافت. |
یکدست‌سازی فارسی
سرور پیش از جست‌وجو متن را یکدست می‌کند، پس لازم نیست شما این کار را بکنید:
- ی و ک عربی به فارسی، ة و ۀ به ه، أ و إ و ٱ به ا؛ حروف چسبیده متن کپی‌شده از PDF به حروف عادی.
- اعراب و کشیده حذف و رقم‌های فارسی و عربی لاتین می‌شوند.
- نیم‌فاصله فاصله می‌شود و نویسه‌های کنترلی و جهت‌دهی حذف می‌شوند.
- کوتاه‌نوشت‌ها باز می‌شوند: «خ.» خیابان، «ک.» کوچه، «م.» میدان.
تاخیر و لغو
حدود ۲۵۰ میلی‌ثانیه پس از آخرین نویسه درخواست بفرستید و درخواست قبلی را لغو کنید؛ هم سریع‌تر است و هم واحد کمتری مصرف می‌کند. SearchControl همه این‌ها را آماده دارد.
let controller;let timer;input.addEventListener("input", () => { clearTimeout(timer); timer = setTimeout(async () => { controller?.abort(); // لغو درخواست قبلی controller = new AbortController(); try { const res = await NamayekMaps.autocomplete(input.value, { key: "nmk_pk_YOUR_PUBLISHABLE_KEY", near: map.getCenter(), limit: 6, signal: controller.signal, }); render(res.items); // با textContent، نه innerHTML } catch (e) { if (e.name !== "AbortError") showError(e.message); } }, 250);});سرویس در دسترس نیست
اگر موتور جست‌وجو موقتا در دسترس نباشد، پاسخ ۵۰۳ با UPSTREAM_UNAVAILABLE و Retry-After: 30 می‌آید و بدنه آن available: false و items: [] هم دارد تا رابط ساده شما نشکند. در این حالت پیام «جست‌وجو در حال آماده‌سازی است» نشان دهید؛ هزینه‌ای ثبت نمی‌شود.
آخرین به‌روزرسانی: