Tích hợp tìm kiếm địa điểm Việt Nam vào sản phẩm của bạn.

Các yêu cầu AutoComplete, Detail và kiểm tra hạn mức cần gửi API key trong header X-API-Key. Endpoint /healthz không yêu cầu xác thực.

X-API-Key: YOUR_API_KEY

Đặt địa chỉ API, API key và định danh người dùng vào các biến môi trường GOFA_PLACES_BASE_URL, GOFA_PLACES_API_KEY và GOFA_PLACES_USER_ID. Đoạn lệnh dưới đây tạo một session tìm kiếm, gọi AutoComplete rồi dùng ngay place_id đã chọn để gọi Detail. Máy chạy ví dụ cần có jq và uuidgen.

: "${GOFA_PLACES_BASE_URL:?Chưa đặt GOFA_PLACES_BASE_URL}"
: "${GOFA_PLACES_API_KEY:?Chưa đặt GOFA_PLACES_API_KEY}"
: "${GOFA_PLACES_USER_ID:?Chưa đặt GOFA_PLACES_USER_ID}"

session_id=$(uuidgen)

autocomplete_response=$(curl --silent --show-error --fail-with-body --get \
  "${GOFA_PLACES_BASE_URL}/v5/Place/AutoComplete" \
  --header "X-API-Key: ${GOFA_PLACES_API_KEY}" \
  --header "X-id: ${GOFA_PLACES_USER_ID}" \
  --data-urlencode 'input=Số 1 đường giáp hải phường bắc giang' \
  --data-urlencode "session_id=${session_id}" \
  --data-urlencode 'limit=8')

printf '%s\n' "$autocomplete_response" | jq .
place_id=$(printf '%s\n' "$autocomplete_response" | jq -er '.predictions[0].place_id')

curl --silent --show-error --fail-with-body --get \
  "${GOFA_PLACES_BASE_URL}/v5/Place/Detail" \
  --header "X-API-Key: ${GOFA_PLACES_API_KEY}" \
  --data-urlencode "place_id=${place_id}" | jq .

Trả về danh sách địa điểm phù hợp với nội dung người dùng đang nhập. Khi truyền cả lat và lng, kết quả có thể kèm khoảng cách tới vị trí ưu tiên.

Tham số yêu cầu

Phản hồi 200 OK

{
  "predictions": [
    {
      "description": "số 1 Giáp Hải, Phường Xương Giang, Thành Phố Bắc Giang, Tỉnh Bắc Giang",
      "matched_substrings": [
        { "length": 1, "offset": 3 },
        { "length": 5, "offset": 28 },
        { "length": 5, "offset": 49 },
        { "length": 5, "offset": 65 }
      ],
      "place_id": "gofa_example_place_id_001",
      "reference": "gofa_example_place_id_001",
      "structured_formatting": {
        "main_text": "số 1 Giáp Hải",
        "main_text_matched_substrings": [
          { "length": 1, "offset": 3 }
        ],
        "secondary_text": "Phường Xương Giang, Thành Phố Bắc Giang, Tỉnh Bắc Giang",
        "secondary_text_matched_substrings": [
          { "length": 5, "offset": 13 },
          { "length": 5, "offset": 34 },
          { "length": 5, "offset": 50 }
        ]
      },
      "has_children": false,
      "plus_code": {
        "compound_code": "+CEOWFP Phường Xương Giang, Thành Phố Bắc Giang, Tỉnh Bắc Giang",
        "global_code": "1BDC1+CEOWFP"
      },
      "compound": {
        "district": "Bắc Giang",
        "commune": "Xương Giang",
        "province": "Bắc Giang"
      },
      "terms": [
        { "offset": 0, "value": "số 1 Giáp Hải" },
        { "offset": 19, "value": "Phường Xương Giang" },
        { "offset": 44, "value": "Thành Phố Bắc Giang" },
        { "offset": 70, "value": "Tỉnh Bắc Giang" }
      ],
      "types": ["street_address", "subpremise"],
      "distance_meters": null
    }
  ],
  "execution_time": "",
  "status": "OK"
}

Lưu ý: distance_meters là null khi không có vị trí để tính khoảng cách. Hãy chuyển nguyên vẹn place_id sang yêu cầu Detail.

Trường dữ liệu của prediction

Lấy địa chỉ chuẩn hóa và tọa độ của kết quả đã chọn. Hãy chuyển tiếp nguyên vẹn place_id nhận từ AutoComplete.

Tham số yêu cầu

curl --get "${GOFA_PLACES_BASE_URL}/v5/Place/Detail" \
  --header "X-API-Key: ${GOFA_PLACES_API_KEY}" \
  --data-urlencode "place_id=${place_id}"

Phản hồi 200 OK

{
  "result": {
    "place_id": "gofa_example_place_id_001",
    "formatted_address": "1 Đường Giáp Hải 1, Phường Xương Giang, Thành Phố Bắc Giang, Tỉnh Bắc Giang",
    "geometry": {
      "location": { "lat": 21.288803, "lng": 106.213579 }
    },
    "plus_code": {
      "compound_code": "+CEOWFP Phường Xương Giang, Thành Phố Bắc Giang, Tỉnh Bắc Giang",
      "global_code": "1BDC1+CEOWFP"
    },
    "compound": {
      "district": "Bắc Giang",
      "commune": "Xương Giang",
      "province": "Bắc Giang"
    },
    "name": "1 Đường Giáp Hải 1",
    "url": "",
    "types": ["street_address", "subpremise"]
  },
  "status": "OK"
}

Lưu ý: Các chuỗi trong plus_code, compound và url có thể rỗng khi thông tin không có sẵn.

Trường dữ liệu của result

Tra cứu hạn mức tháng, số yêu cầu đã sử dụng và số còn lại cho từng endpoint. Yêu cầu này không trừ hạn mức.

curl --silent --show-error --fail-with-body \
  "${GOFA_PLACES_BASE_URL}/Account/Quota" \
  --header "X-API-Key: ${GOFA_PLACES_API_KEY}" | jq .

Phản hồi 200 OK

{
  "status": "ok",
  "period": {
    "starts_at": "2026-09-01T00:00:00+00:00",
    "resets_at": "2026-10-01T00:00:00+00:00"
  },
  "quota": {
    "limit": 2000,
    "used": 37,
    "remaining": 1963,
    "endpoints": [
      { "code": "autocomplete", "name": "Place AutoComplete", "limit": 1500, "used": 30, "remaining": 1470 },
      { "code": "detail", "name": "Place Detail", "limit": 500, "used": 7, "remaining": 493 }
    ]
  }
}

Kiểm tra trạng thái hoạt động của dịch vụ.

curl --silent --show-error "${GOFA_PLACES_BASE_URL}/healthz"

Hoạt động bình thường 200 OK

{ "status": "ok" }

Dịch vụ chưa sẵn sàng 503 Service Unavailable

{ "status": "degraded" }

Mỗi API key có giới hạn tốc độ dùng chung và quota tháng riêng cho từng endpoint theo gói đã được cấp. Các header sau giúp ứng dụng theo dõi phần quota còn lại:

Phản hồi lỗi từ Places API

AutoComplete, HTTP 400:

{
  "predictions": [],
  "execution_time": "0.21ms",
  "status": "INVALID_REQUEST"
}

Detail, HTTP 400:

{
  "result": null,
  "status": "INVALID_REQUEST"
}

Detail, HTTP 404:

{
  "result": null,
  "status": "NOT_FOUND"
}

Lỗi xác thực và giới hạn sử dụng

{ "error": "invalid_api_key" }