Tài liệu tích hợp cho đối tác

Quy ước chung

• Tất cả API trong tài liệu này được gọi qua GET.
• API key truyền qua query param key.
• Các giá trị tọa độ dùng định dạng lat,lng.
• Khi truyền nhiều điểm trong cùng một tham số, dùng ký tự | để phân tách.
• Khuyến nghị URL encode toàn bộ query string khi tích hợp.

1. Autocomplete

API dùng để gợi ý địa điểm, địa chỉ hoặc POI theo từ khóa tìm kiếm.

Endpoint

GET /place/autocomplete

Request Parameters

Ví dụ Request

curl --location 'https://api.svmap.vn/place/autocomplete?input=31%20Mac%20Thi%20Buoi&location=10.77526%2C106.70565&key=YOUR_API_KEY'

Response thành công

{
  "status": "OK",
  "predictions": [
    {
      "name": "31 Mac Thi Buoi",
      "address": "31 Mac Thi Buoi, Ben Nghe, Quan 1, Ho Chi Minh, Viet Nam",
      "location": {
        "lat": 10.77526,
        "lng": 106.70565
      },
      "place_id": "..."
    }
  ]
}

Response lỗi thường gặp

{
  "result": "0",
  "data": [],
  "message": "Vui lòng nhập lớn hơn 3 ký tự."
}

2. Place Detail

API dùng để lấy thông tin chi tiết của một địa điểm theo place_id.

Endpoint

GET /place/details

Request Parameters

Ví dụ Request

curl --location 'https://api.svmap.vn/place/details?key=YOUR_API_KEY&place_id=db773cb9b803c49374c3be9e720bc13b'

Response thành công

{
  "html_attributions": [],
  "status": "OK",
  "result": {
    "name": "Tên địa điểm",
    "formatted_address": "Địa chỉ đầy đủ",
    "geometry": {
      "location": {
        "lat": 10.123,
        "lng": 106.123
      }
    },
    "place_id": "db773cb9b803c49374c3be9e720bc13b",
    "province_id": 1,
    "address_components": []
  }
}

3. Geocode

API dùng để chuyển đổi địa chỉ văn bản sang tọa độ.

Endpoint

GET /geocoding

Request Parameters

Ví dụ Request

curl --location 'https://api.svmap.vn/geocoding?key=YOUR_API_KEY&address=307%20Nguyen%20Trong%20Tuyen%2C%20Phu%20Nhuan'

Response thành công

{
  "status": "OK",
  "results": [
    {
      "formatted_address": "307 Nguyen Trong Tuyen, Phu Nhuan, Ho Chi Minh, Viet Nam",
      "geometry": {
        "location": {
          "lat": 10.123,
          "lng": 106.123
        }
      },
      "place_id": "...",
      "province_id": 1
    }
  ]
}

4. Reverse Geocode

API dùng để chuyển đổi tọa độ sang địa chỉ gần nhất.

curl --location 'https://api.svmap.vn/geocoding?latlng=16.06111%2C108.217309&key=YOUR_API_KEY'

{
  "status": "OK",
  "results": [
    {
      "formatted_address": "Địa chỉ gần nhất",
      "geometry": {
        "location": {
          "lat": 16.06111,
          "lng": 108.217309
        }
      },
      "place_id": "...",
      "province_id": 1
    }
  ]
}

curl --location 'https://api.svmap.vn/directions?key=YOUR_API_KEY&origin=21.597262%2C105.821485&destination=21.598438%2C105.817684&mode=car'

{
  "geocoded_waypoints": [],
  "status": "OK",
  "routes": [
    {
      "distance": {
        "text": "1.2 km",
        "value": 1200
      },
      "duration": {
        "text": "5 phút",
        "value": 300
      },
      "overview_polyline": {
        "points": "..."
      },
      "legs": []
    }
  ]
}

{
  "status": "No Route",
  "geocoded_waypoints": [],
  "routes": []
}

curl --location 'https://api.svmap.vn/directions?key=YOUR_API_KEY&origin=10.800386546950085%2C106.64433670624179&destination=10.8786159915385%2C106.64537122920565%7C10.932158596993716%2C106.8003108245106&mode=car'

curl --location 'https://api.svmap.vn/distancematrix?key=YOUR_API_KEY&origins=10.74821917%2C106.661378311%7C10.7482432%2C106.6614453%7C10.7483532%2C106.6613751%7C10.7483267%2C106.6614201%7C10.7505855%2C106.6614529&destinations=10.747475765436967%2C106.660299403704810&travelMode=driving&weighting=0'

{
  "status": "OK",
  "origin_addresses": [],
  "destination_addresses": [],
  "rows": [
    {
      "name": "Xe 0",
      "elements": [
        {
          "distance": {
            "text": "250 m",
            "value": 250
          },
          "duration": {
            "text": "2 phút",
            "value": 120
          },
          "status": "OK"
        }
      ]
    }
  ]
}

{
  "result": "0",
  "data": [],
  "message": "Dữ liệu không hợp lệ."
}