انتخاب آدرس روی نقشه در تسویه‌حساب

کاربر نقطه‌ای را روی نقشه انتخاب می‌کند و برنامه، آدرس آن را برای تأیید نشان می‌دهد. درخواست تبدیل نقطه به آدرس از سرور برنامه فرستاده می‌شود تا کلید خصوصی در مرورگر قرار نگیرد.

پیش‌نیازها

• یک نقشهٔ MapLibre با کلید عمومی؛ نمایش اولین نقشه را ببینید.
• یک سرور Express و یک کلید خصوصی با دسترسی «تبدیل نقطه به آدرس» در متغیر محیطی BALAD_API_KEY.
• یک فرم با ورودی آدرس و محل نمایش خطا؛ شناسه‌های لازم در نمونهٔ مرورگر آمده‌اند.

مراحل

1. نقشه را با یک مرکز اولیه باز کنید و نقطهٔ انتخاب‌شده را به‌صورت نشانگر نمایش دهید.
2. بعد از کلیک روی نقشه، مختصات را به مسیر داخلی /api/reverse-geocode بفرستید.
3. درخواست قبلی را با AbortController لغو کنید تا پاسخ قدیمی، آدرس جدید را بازنویسی نکند.
4. مختصات و متن آدرس را با تأیید کاربر ذخیره کنید؛ تبدیل مختصات به آدرس، جای تأیید انسانی پلاک و واحد را نمی‌گیرد.

تبدیل مختصات به آدرس روی سرور برنامه

app.get("/api/reverse-geocode", async (req, res) => {
  const lng = Number(req.query.lng);
  const lat = Number(req.query.lat);
  if (!Number.isFinite(lng) || lng < -180 || lng > 180 ||
      !Number.isFinite(lat) || lat < -90 || lat > 90) return res.sendStatus(400);

  const url = new URL("https://reverse-geocoding.services.balad.ir/v1/");
  url.searchParams.set("location", lng + "," + lat);
  const response = await fetch(url, {
    headers: { Authorization: "Bearer " + process.env.BALAD_API_KEY }
  });
  if (!response.ok) return res.sendStatus(response.status);

  const data = await response.json();
  res.json({ formattedAddress: data.formatted_address, components: data.components });
});

انتخاب نقطه و دریافت آدرس با MapLibre

// متغیر map نقشهٔ ساخته‌شده با MapLibre و فایل style بلد است.
// در فرم HTML، این دو عنصر را قرار دهید:
// <input id="formatted-address" aria-label="آدرس انتخاب‌شده">
// <p id="address-error" role="status"></p>

const marker = new maplibregl.Marker();
let activeRequest;

async function updateAddress({ lat, lng }) {
  marker.setLngLat([lng, lat]).addTo(map);
  activeRequest?.abort();
  const request = new AbortController();
  activeRequest = request;
  try {
    const response = await fetch(
      "/api/reverse-geocode?lat=" + lat + "&lng=" + lng,
      { signal: request.signal },
    );
    if (request.signal.aborted) return;
    if (!response.ok) {
      document.querySelector("#address-error").textContent = "برای این نقطه آدرسی پیدا نشد.";
      return;
    }
    const data = await response.json();
    if (request.signal.aborted) return;
    document.querySelector("#address-error").textContent = "";
    document.querySelector("#formatted-address").value = data.formattedAddress;
  } catch (error) {
    if (request.signal.aborted) return;
    document.querySelector("#address-error").textContent = "دریافت آدرس ناموفق بود؛ دوباره تلاش کنید.";
  }
}

map.on("click", event => void updateAddress(event.lngLat));

نتیجهٔ مورد انتظار

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

نقشه در این تصویر واقعی است؛ متن آدرس برای نمایش فرم به‌صورت نمونه قرار داده شده است.

نکات

• مسیر /api/reverse-geocode نمونه‌ای از سرور برنامهٔ شماست و بخشی از API بلد نیست؛ نمونهٔ سرور از Express و متغیر محیطی BALAD_API_KEY برای کلید خصوصی استفاده می‌کند.
• خطای شبکه و حالت بدون نتیجه را کنار فیلد آدرس نمایش دهید و امکان ورود دستی را نگه دارید.
• برای درخواست‌های متوالی با فاصلهٔ زمانی کوتاه، اجرای درخواست را تا پایان انتخاب کاربر به تأخیر بیندازید؛ این روش با نام debounce شناخته می‌شود. نمونهٔ بالا درخواست قبلی را نیز لغو می‌کند.

مرجع تبدیل نقطه به آدرس · همهٔ آموزش‌های کاربردی