gmapKhóa API
Mọi yêu cầu cần khóa trong header x-api-key hoặc tham số x-api-key. Để thử, dùng khóa demo công khai bên dưới; khóa này có giới hạn lưu lượng. Khi đưa vào vận hành, GMap cấp khóa riêng cho ứng dụng của bạn.
public-gmap-cloud-x-api-key-demoGọi API đầu tiên
Tìm một địa điểm theo tên. Kết quả là GeoJSON FeatureCollection.
curl --get 'https://cloud.gmap.vn/api/idunn/v1/search' \
--header 'x-api-key: public-gmap-cloud-x-api-key-demo' \
--data-urlencode 'q=Chợ Hàn Đà Nẵng' \
--data 'lang=vi'const KEY = 'public-gmap-cloud-x-api-key-demo';
const url = new URL('https://cloud.gmap.vn/api/idunn/v1/search');
url.search = new URLSearchParams({ q: 'Chợ Hàn Đà Nẵng', lang: 'vi', 'x-api-key': KEY });
const { features } = await fetch(url).then((response) => response.json());
const [lon, lat] = features[0].geometry.coordinates;
console.log(features[0].properties.geocoding.label, lat, lon);
// Chợ Hàn Đà Nẵng, Phường Hải Châu, Thành phố Đà Nẵng, Việt Nam 16.0682606 108.224093GeoJSON đặt kinh độ trước vĩ độ: coordinates = [kinh độ, vĩ độ]. Đây là lỗi hay gặp nhất khi mới tích hợp.
Hiện địa điểm trên bản đồ
Bản đồ nền của GMap là style MapLibre có sẵn font, sprite và lớp địa điểm. Dán đoạn mã sau vào một tệp HTML rồi mở bằng trình duyệt.
<link rel="stylesheet" href="https://unpkg.com/maplibre-gl@4.7.1/dist/maplibre-gl.css">
<script src="https://unpkg.com/maplibre-gl@4.7.1/dist/maplibre-gl.js"></script>
<div id="map" style="height: 420px"></div>
<script>
const KEY = 'public-gmap-cloud-x-api-key-demo';
const map = new maplibregl.Map({
container: 'map',
style: `https://cloud.gmap.vn/api/tiles/style/basemap?x-api-key=${KEY}`,
center: [108.224093, 16.0682606],
zoom: 15,
});
new maplibregl.Marker()
.setLngLat([108.224093, 16.0682606])
.setPopup(new maplibregl.Popup().setText('Chợ Hàn Đà Nẵng'))
.addTo(map);
</script>Lỗi thường gặp
| Dấu hiệu | Nguyên nhân | Cách xử lý |
|---|---|---|
| HTTP 401, "No API key found in request" | Thiếu hoặc sai khóa API | Thêm header x-api-key hoặc tham số x-api-key |
| HTTP 429 | Vượt giới hạn lưu lượng của khóa | Chờ theo header RateLimit-Reset rồi thử lại; dùng khóa riêng khi vận hành |
| Điểm hiện sai chỗ (thường ở biển) | Đảo vĩ độ và kinh độ | GeoJSON là [kinh độ, vĩ độ]; MapLibre setLngLat cũng vậy |
| Không có kết quả | Nội dung tìm quá ngắn hoặc thiếu ngữ cảnh | Thêm tên phường, tỉnh; hoặc tra cứu ngược bằng tọa độ |
Mỗi phản hồi có các header X-RateLimit-Remaining-Second, -Minute, -Hour cho biết số lượt còn lại. Xử lý 401 và 429 ngay từ đầu:
const response = await fetch(url);
if (response.status === 401) throw new Error('Missing or invalid API key');
if (response.status === 429) {
const wait = Number(response.headers.get('RateLimit-Reset') ?? 1);
// Retry after the reset window instead of hammering the API.
await new Promise((resolve) => setTimeout(resolve, wait * 1000));
}
const data = await response.json();Tiếp theo
- Làm ô nhập địa chỉ có gợi ý cho trang đặt hàng.
- Đối chiếu địa chỉ cũ và mới sau sáp nhập.
- Chọn kho gần nhất hoặc vẽ vùng giao hàng bằng API tuyến đường.
