Cách xây dựng store locator tìm cửa hàng gần nhất bằng Maps API

Store locator là tính năng nhỏ mà mọi doanh nghiệp nhiều chi nhánh rồi cũng cần tới: cái ô "tìm cửa hàng gần nhất" biến một mã bưu chính thành danh sách cửa hàng ngắn gọn, đã xếp hạng, trên bản đồ. Nhìn từ ngoài thì có vẻ tầm thường, và happy path đúng là đơn giản thật, nhưng một locator tốt lặng lẽ làm tốt ba việc: nó hiểu được input vị trí lộn xộn, nó xếp hạng chi nhánh theo độ gần thực sự, và nó render kết quả lên một bản đồ mà con người có thể hành động dựa vào.

Bài viết này đi qua cách một store locator thực sự hoạt động, bốn bước để xây dựng nó bằng maps API, và những chi tiết phân biệt một bản demo với thứ bạn dám đưa lên production. Mọi bản đồ trong bài đều được render bằng chính MapAtlas API.

Store Locator Thực Sự Làm Gì

Bỏ phần styling đi thì store locator là một pipeline gồm ba giai đoạn:

1. Geocode input của khách. "1012 Amsterdam", "SW1A 1AA", hay một vị trí GPS được chia sẻ, tất cả đều phải trở thành một cặp latitude và longitude duy nhất.
2. Xếp hạng cửa hàng gần. Với tọa độ đó và danh sách địa điểm chi nhánh của bạn, tìm những cái gần nhất trong một bán kính hợp lý.
3. Render kết quả. Đặt các cửa hàng đã xếp hạng lên bản đồ dưới dạng marker, mỗi cái kèm địa chỉ, giờ mở cửa và link chỉ đường.

Bản đồ bên dưới chính là giai đoạn thứ ba đó, render bằng tiles MapAtlas: sáu chi nhánh ở trung tâm Amsterdam được ghim theo khoảng cách từ khách. Ở đây chúng là siêu thị, nhưng bản đồ vẫn y hệt dù marker đến từ một dataset POI hay từ danh sách cửa hàng của riêng bạn.

Thứ tự màu chính là thứ hạng. Khách tìm từ tâm bản đồ, và các marker là những chi nhánh gần nhất theo thứ tự, gần nhất trước.

Bước 1: Geocode Input của Khách

Khách gõ một mã bưu chính, một thành phố, hoặc một địa chỉ đầy đủ, và bạn cần một tọa độ. Đó là forward geocoding.

// Turn what the visitor types into a coordinate (autocomplete geocoding)
const res = await fetch(
  `https://gateway.mapmetrics-atlas.net/autocomplete/` +
  `?token=${API_TOKEN}&text=${encodeURIComponent(query)}` +
  `&focus.point.lat=52.37&focus.point.lon=4.89` // bias toward your service area
);
const { features } = await res.json();
const [lon, lat] = features[0].geometry.coordinates; // [lon, lat]
const label = features[0].properties.label;          // "Damrak, Amsterdam, North Holland, Netherlands"

Có hai chi tiết quan trọng ở đây. Hãy truyền một focus.point gần khu vực phục vụ của bạn để "Cambridge" resolve ra đúng cái cần, và xử lý trường hợp khách chia sẻ GPS thiết bị thay vì gõ: khi đó bạn đã có sẵn tọa độ và bỏ qua hẳn bước này.

Bước 2: Xếp Hạng Cửa Hàng Theo Khoảng Cách

Giờ bạn đã có tọa độ của khách. Bản thân các cửa hàng là dữ liệu của bạn: một danh sách chi nhánh, mỗi cái có latitude và longitude, nằm trong database của bạn. Xếp hạng chúng chỉ là một phép tính khoảng cách đường thẳng (haversine), không cần API call nào:

// Your branches, each with a lat/lon. Rank by distance from the visitor.
const ranked = stores
  .map(s => ({ ...s, distance_m: haversine(lat, lon, s.lat, s.lon) }))
  .sort((a, b) => a.distance_m - b.distance_m)
  .slice(0, 6);

Một locator cơ bản chỉ cần chừng đó. Với mạng lưới lớn, trước tiên bạn sẽ lọc theo một bounding box quanh khách để khỏi phải đo khoảng cách tới từng chi nhánh trên mỗi request, rồi mới sắp xếp phần còn lại. Đầu ra là danh sách ngắn các chi nhánh gần nhất, mỗi cái kèm một distance_m.

Bước 3: Xếp Theo Khoảng Cách, Rồi Tinh Chỉnh Theo Thời Gian Di Chuyển

Khoảng cách đường thẳng là mặc định hợp lý. Nó nhanh, không cần call thêm, và với mạng lưới dày đặc thì thường là đúng. Nhưng cửa hàng gần nhất theo đường chim bay không phải lúc nào cũng nhanh tới nhất: một cửa hàng cách 400 mét bên kia sông có thể là một vòng đi mười phút tới cây cầu gần nhất.

Với locator mà "gần nhất" thực sự có nghĩa là "tới nhanh nhất", hãy xếp hạng lại vài ứng viên đầu bảng theo thời gian di chuyển thực bằng một call directions hoặc matrix:

// Re-rank the closest stores by real drive time (MapAtlas Matrix API)
const res = await fetch(`https://gateway.mapmetrics-atlas.net/matrix/?token=${API_TOKEN}`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    sources: [{ lat, lon }],
    targets: top3.map(s => ({ lat: s.lat, lon: s.lon })),
    costing: 'auto', // 'auto' | 'bicycle' | 'pedestrian'
  }),
});
const { sources_to_targets } = await res.json();
const row = sources_to_targets[0]; // one entry per target, each with .time (seconds)
const byTime = top3
  .map((s, i) => ({ ...s, time: row[i].time }))
  .sort((a, b) => a.time - b.time);

Bạn chỉ làm việc này cho một nhúm ứng viên gần nhất, nên nó vẫn là một call rẻ duy nhất, không phải mỗi cửa hàng một call.

Bước 4: Render Cửa Hàng Lên Bản Đồ

Bước cuối là chính bản đồ. Thả một marker cho mỗi cửa hàng đã xếp hạng, thêm popup kèm địa chỉ và giờ mở cửa, và căn khung nhìn sao cho mọi kết quả đều thấy được. Với một maps API phục vụ tiles, geocoding và search từ cùng một provider, toàn bộ locator chạy trên một vendor và một hệ tọa độ từ đầu tới cuối, và đó chính là nền của bản đồ ở đầu bài này.

Cho mỗi marker một popup chứa những thứ thiết yếu để khách hành động: tên, địa chỉ, khoảng cách, giờ mở cửa, và một link "Chỉ đường" đưa tọa độ sang routing engine.

Những Chi Tiết Phân Biệt Demo với Production

Kết quả rỗng. Có người tìm từ một vùng bạn không có chi nhánh nào. Hãy quyết định trước: tự động nới bán kính, hiển thị đúng một cửa hàng gần nhất dù xa tới đâu, hay nói thật rằng "không có cửa hàng nào trong vòng 50 km".

Giờ mở cửa. Một locator chỉ ra cửa hàng gần nhất trong khi nó đang đóng thì thật khó chịu. Hãy lọc hoặc gắn cờ theo giờ mở cửa để "đang mở" trở thành một lựa chọn hạng nhất.

Input mơ hồ. "Cambridge" tồn tại ở Anh và ở Massachusetts; "Springfield" tồn tại hàng chục lần. Country biasing ở bước geocode loại bỏ phần lớn chuyện này, và cung cấp autocomplete khi khách đang gõ sẽ loại nốt phần còn lại.

GPS di động và consent. Trên mobile, trải nghiệm mạnh nhất là nút "dùng vị trí của tôi", nhưng đọc GPS thiết bị là dữ liệu vị trí và cần consent. Hãy hỏi trước, và fallback về nhập text nếu khách từ chối.

Quyền riêng tư. Vị trí của khách trở thành dữ liệu cá nhân ngay khi nó gắn với họ. Hãy geocode theo yêu cầu, tránh lưu tọa độ thô, và dùng API đặt tại EU để vị trí không bao giờ rời khỏi EEA. Xem hướng dẫn về bản đồ tuân thủ GDPR của chúng tôi để có bức tranh đầy đủ.

Xây dựng Store Locator với MapAtlas

MapAtlas cho bạn toàn bộ pipeline từ một API và một hệ tọa độ. Geocoding API biến mã bưu chính và thành phố thành tọa độ kèm country biasing; bạn xếp hạng danh sách chi nhánh của mình theo tọa độ đó; các API Directions và Matrix xếp hạng lại các ứng viên đầu bảng theo thời gian di chuyển thực; và tiles Dynamic Maps render kết quả, đúng như đã thấy trong bài này. Vì tất cả chạy bên trong EU theo mặc định, vị trí của khách ở lại trong EEA, giữ cho locator tuân thủ GDPR mà không cần làm gì thêm.

Định dạng request và response đầy đủ cho mọi endpoint có trong tài liệu API MapAtlas. Search API cũng đáng xem nếu bạn muốn locator khám phá các points of interest quanh khách, chứ không chỉ chi nhánh của riêng bạn.

Store locator là một tính năng nhỏ chứa rất nhiều phán đoán thầm lặng bên trong: hiểu input mơ hồ, xếp hạng theo độ gần thực sự, và tôn trọng việc vị trí là dữ liệu cá nhân. Làm đúng ba điều đó và cái ô "tìm cửa hàng gần nhất" thôi làm một thứ nghĩ sau cùng, để trở thành một trong những thứ được dùng nhiều nhất trên site của bạn.