Tài liệu
/
Hướng dẫn sử dụng API

Tài liệu API Wayfindy

Hướng dẫn chi tiết cách sử dụng API để kiểm tra phạt nguội, tra cứu luật giao thông Việt Nam, tìm kiếm địa điểm và các tuyến đường giữa hai địa điểm.

Bắt đầu

API Wayfindy cung cấp giao diện RESTful để truy vấn thông tin về phạt nguội, luật giao thông Việt Nam, thông tin địa điểm và các tuyến đường giữa hai nơi (có các điểm thú vị trên tuyến đường). API sử dụng các phương thức HTTP tiêu chuẩn và trả về dữ liệu dưới dạng JSON.

https://api.giaothongviet.io.vn/api/public

Xác thực

Tất cả các yêu cầu API đều yêu cầu xác thực bằng cặp khóa Client-IdClient-Secret. Các khóa này phải được gửi trong header của mỗi yêu cầu.

Client-Id: YOUR_CLIENT_ID
Client-Secret: YOUR_CLIENT_SECRET

Bạn sẽ nhận được Client-Id (một GUID) và Client-Secret sau khi đăng ký tài khoản. Hãy bảo mật thông tin này và không chia sẻ với người khác.

Gửi yêu cầu API

API Wayfindy sử dụng một endpoint duy nhất cho cả hai chức năng: kiểm tra phạt nguội và tra cứu luật giao thông. Cách sử dụng phụ thuộc vào nội dung của tham số question trong yêu cầu của bạn.

POST https://api.giaothongviet.io.vn/api/public/PublicTrafficViolation/submit-question

Cấu trúc yêu cầu:

{
  "question": "Nội dung câu hỏi hoặc biển số xe"
}

Khi sử dụng chức năng tìm kiếm địa điểm, bạn cần truyền tham số query trên endpoint khi gửi yêu cầu.

GET https://api.giaothongviet.io.vn/api/public/PublicLocation/search-location?query

Đối với chức năng tìm kiếm tuyến đường giữa hai địa điểm, trên route của endpoint bạn cần truyền một chuỗi start_lng,start_lat;end_lng,end_lat của hai địa điểm

POST https://api.giaothongviet.io.vn/api/public/PublicLocation/search-routes/start_lng,start_lat;end_lng,end_lat

Cấu trúc tùy chọn (optional)

{
  "memberSuggest": "Tiêu chí của người dùng với các điểm thú vị giữa hai địa điểm"
}

Kiểm tra phạt nguội

Để kiểm tra thông tin phạt nguội, hãy gửi biển số xe trong tham số question. Hệ thống sẽ tự động nhận diện đây là yêu cầu kiểm tra phạt nguội.

curl -X POST "https://api.giaothongviet.io.vn/api/public/PublicTrafficViolation/submit-question" \
  -H "Client-Id: YOUR_CLIENT_ID" \
  -H "Client-Secret: YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"question": "30A12345"}'

Phản hồi mẫu

{
  "trafficViolations": [
    {
      "description": "16824.6.9.b.01.Không chấp hành hiệu lệnh của đèn tín hiệu giao thông",
      "location": "Ngã tư Gia Lễ, TP Thái Bình, Thái Bình, Xã Đông Mỹ, Thành phố Thái Bình, Tỉnh Thái Bình",
      "violationTime": "2025-02-23T10:19:00",
      "violationStatus": "Chưa xử phạt",
      "enforcementAgency": "1. ĐỘI TT, ĐTGQTN VÀ XLVPGT - PHÒNG CSGT THÁI BÌNH, Địa chỉ: Tỉnh Thái Bình, Số điện thoại liên hệ: 0692.760281, 2. Đội Cảnh sát giao thông, Trật tự - Công an quận 7 - Thành phố Hồ Chí Minh, Địa chỉ: 1366 Huỳnh Tấn Phát, Số điện thoại liên hệ: 02837851477",
      "detectionAgency": "ĐỘI TT, ĐTGQTN VÀ XLVPGT - PHÒNG CSGT THÁI BÌNH"
    }
  ],
  "vehicleCertificate": {
    "brand": null,
    "trafficType": null,
    "registerDate": null,
    "registerAgency": null,
    "gcnStampNumber": null,
    "gcnExpiredDate": null,
    "roadPaymentDate": null,
    "feeCollectionAgency": null,
    "billNumber": null,
    "roadPaymentExpiredDate": null
  },
  "message": "Detected traffic violation!",
  "isSuccess": true
}

Giải thích phản hồi

Trường Mô tả
trafficViolations Danh sách các vi phạm giao thông của biển số xe
description Mô tả hành vi vi phạm
location Địa điểm xảy ra vi phạm
violationTime Thời gian xảy ra vi phạm
violationStatus Trạng thái xử lý vi phạm
enforcementAgency Cơ quan xử lý vi phạm
detectionAgency Cơ quan phát hiện vi phạm
vehicleCertificate Thông tin giấy tờ xe (nếu có)
message Thông báo kết quả
isSuccess Trạng thái thành công của yêu cầu

Tra cứu luật giao thông

Để tra cứu thông tin về luật giao thông, hãy gửi câu hỏi của bạn trong tham số question. Hệ thống sẽ tự động nhận diện đây là yêu cầu tra cứu luật giao thông.

curl -X POST "https://api.giaothongviet.io.vn/api/public/PublicTrafficViolation/submit-question" \
  -H "Client-Id: YOUR_CLIENT_ID" \
  -H "Client-Secret: YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"question": "Vượt đèn đỏ bị phạt bao nhiêu tiền?"}'

Phản hồi mẫu

{
  "carViolation": {
    "id": 507,
    "violationName": "Không chấp hành hiệu lệnh của đèn tín hiệu giao thông",
    "violationCode": "GT-096",
    "vehicleType": "Ô tô",
    "penalty": "Phạt tiền từ 18.000.000 đồng đến 20.000.000 đồng",
    "minPenalty": 18000000.00,
    "maxPenalty": 20000000.00,
    "avgPenalty": 19000000.00,
    "pointDeduction": 4,
    "repeatOffensePenalty": "Không áp dụng",
    "additionalPenalty": "Không áp dụng",
    "source": "Nghị định 168/2024/NĐ-CP, Điều 6, Khoản 9",
    "lastUpdated": "2025-02-14T03:49:08.6866667",
    "note": "Không",
    "keywords": "vuot den do; vuot den vang"
  },
  "motorBikeViolation": {
    "id": 594,
    "violationName": "Không chấp hành hiệu lệnh của đèn tín hiệu giao thông",
    "violationCode": "GT-183",
    "vehicleType": "Xe gắn máy",
    "penalty": "Phạt tiền từ 4.000.000 đồng đến 6.000.000 đồng",
    "minPenalty": 4000000.00,
    "maxPenalty": 6000000.00,
    "avgPenalty": 5000000.00,
    "pointDeduction": 4,
    "repeatOffensePenalty": "Không áp dụng",
    "additionalPenalty": "Không áp dụng",
    "source": "Nghị định 168/2024/NĐ-CP, Điều 7, Khoản 7",
    "lastUpdated": "2025-02-14T03:49:08.7",
    "note": "Không",
    "keywords": "vuot den do; vuot den vang"
  },
  "nonMotorizedVehicleViolation": {
    "id": 717,
    "violationName": "Không chấp hành hiệu lệnh của đèn tín hiệu giao thông",
    "violationCode": "GT-306",
    "vehicleType": "Xe đạp",
    "penalty": "Phạt tiền từ 150.000 đồng đến 250.000 đồng",
    "minPenalty": 150000.00,
    "maxPenalty": 250000.00,
    "avgPenalty": 200000.00,
    "pointDeduction": 0,
    "repeatOffensePenalty": "Không áp dụng",
    "additionalPenalty": "Không áp dụng",
    "source": "Nghị định 168/2024/NĐ-CP, Điều 9, Khoản 2",
    "lastUpdated": "2025-02-14T03:49:08.7133333",
    "note": "Không",
    "keywords": "vuot den do; vuot den vang"
  },
  "pedestrianViolation": null,
  "generalViolation": null,
  "searchViolationLawResult": null
}

Giải thích phản hồi

Trường Mô tả
carViolation Thông tin vi phạm đối với ô tô
motorBikeViolation Thông tin vi phạm đối với xe máy
nonMotorizedVehicleViolation Thông tin vi phạm đối với xe đạp
pedestrianViolation Thông tin vi phạm đối với người đi bộ (nếu có)
generalViolation Thông tin vi phạm chung (nếu có)
searchViolationLawResult Kết quả tìm kiếm luật vi phạm (nếu có)
violationName Tên vi phạm
violationCode Mã vi phạm
vehicleType Loại phương tiện
penalty Mức phạt
minPenalty Mức phạt tối thiểu (VNĐ)
maxPenalty Mức phạt tối đa (VNĐ)
avgPenalty Mức phạt trung bình (VNĐ)
pointDeduction Số điểm trừ trên giấy phép lái xe
repeatOffensePenalty Hình phạt cho vi phạm lặp lại
additionalPenalty Hình phạt bổ sung
source Nguồn tham chiếu luật
lastUpdated Thời gian cập nhật gần nhất
note Ghi chú bổ sung
keywords Từ khóa liên quan

Tìm kiếm địa điểm

Để tìm kiếm thông tin về địa điểm, hãy gửi tên, từ khóa hoặc địa chỉ trong tham số query.

curl -X GET "https://api.giaothongviet.io.vn/api/public/PublicLocation/search-location?query=landmark quận 1" \
  -H "Client-Id: YOUR_CLIENT_ID" \
  -H "Client-Secret: YOUR_CLIENT_SECRET"
  

Phản hồi mẫu

{
  "locationName": "The Landmark - Công Ty Ld International Burotel",
  "address": "5B Đ. Tôn Đức Thắng, Bến Nghé, Quận 1, Hồ Chí Minh, Việt Nam",
  "latitude": 10.7778473,
  "longitude": 106.7068328,
  "street": null,
  "ward": null,
  "district": null,
  "city": null,
  "region": "Miền Nam",
  "placeType": "lodging, point_of_interest, establishment",
  "country": "Việt Nam",
  "source": "GooglePlaceAPI",
  "createdAt": "2025-04-25T03:15:05.57",
  "overpassId": null,
  "nominationId": null,
  "googlePlaceId": "ChIJdxKYX08vdTERnQeyVjAadZE"
}

Giải thích phản hồi

Trường Mô tả
locationName Tên địa điểm
address Địa chỉ đầy đủ của địa điểm
latitude Vĩ độ của địa điểm
longitude Kinh độ của địa điểm
street Số nhà, đường (nếu có)
ward Số phường (nếu có)
district Quận/Huyện của địa điểm (nếu có)
city Tỉnh/Thành phố (nếu có)
region Vùng miền của địa điểm (nếu có)
placeType Loại của địa điểm (nhà hàng, quán ăn, ...)
country Quốc gia
source Nguồn thông tin địa điểm
overpassId Mã địa điểm trên overpass (nếu có)
nominationId Mã địa điểm trên nomination (nếu có)
googlePlaceId Mã địa điểm trên google places (nếu có)

Tìm kiếm các tuyến đường giữa hai địa điểm

Để tìm kiếm các tuyến đường giữa, hãy gửi vĩ độ, kinh độ (lng,lat) của điểm bắt đầu và kết thúc trong route của endpoint start_lng,start_lat;end_lng,end_lat. Nếu bạn muốn lọc điểm thú vị theo tiêu chí, yêu cầu của người dùng hãy truyền thêm tham số (optional) memberSuggest vào body request.
Nếu không muốn trả về các điểm thú vị trên tuyến đường, bạn có thể truyền tham số (optional) nopois=true vào endpoint

curl -X POST "https://api.giaothongviet.io.vn/api/public/PublicLocation/search-routes/106.7068328,10.7778473;106.4053003,11.0052557?nopois=false" \
  -H "Client-Id: YOUR_CLIENT_ID" \
  -H "Client-Secret: YOUR_CLIENT_SECRET"\
  -H "Content-Type: application/json" \
  -d '{"memberSuggest": "thích đồ ngọt, tiết kiệm"}'
  

Phản hồi mẫu

{
  "routeName": "The Landmark - Công Ty Ld International Burotel  - Tây Ninh, Suối Sâu 2, Phường An Tịnh, Thị xã Trảng Bàng, Tỉnh Tây Ninh, Việt Nam  - shortest",
  "routeType": 1,
  "startLocationId": 9686,
  "endLocationId": 9387,
  "durationMinutes": 45,
  "distanceKm": 46.53,
  "searchCount": 0,
  "createdAt": "2025-04-25T03:44:38.86",
  "startLocation": {
    ...
  },
  "endLocation": {
    ...
  },
  "geometry": {
    "coordinates": [
        [
            106.706968,
            10.777811
        ],
        [
            106.706924,
            10.77765
        ],
        [
            106.706923,
            10.777614
        ],
        ...
        [
            106.405364,
            11.005441
        ]
    ],
    "type": "LineString"
  },
  "pois": [
    {
        "locationName": "Starbucks",
        "address": "Đường Ngô Ðức Kế, Phường Bến Nghé, Quận 1, Thành phố Hồ Chí Minh, Việt Nam",
        "latitude": 10.7746116,
        "longitude": 106.706044,
        "street": "Đường Ngô Ðức Kế",
        "ward": "Phường Bến Nghé",
        "district": "Quận 1",
        "city": "Thành phố Hồ Chí Minh",
        "placeType": "cafe",
        "country": "Việt Nam",
        "reason": "Starbucks is a popular coffee chain that offers a variety of sweet treats and drinks, making it a great fit for someone who likes desserts.",
        "markerUrl": "https://mybakerystorage.blob.core.windows.net/gtvicons/cafe.png",
        "interestingPoint": {
            "interestingPointName": "Starbucks",
            "description": "Chuỗi quán cà phê có trụ sở tại Seattle, nổi tiếng với các loại cà phê rang xay đặc trưng, đồ ăn nhẹ và có Wi-Fi.",
            "type": "cafe",
            "locationId": 8538,
            "createdAt": "2025-04-24T09:42:23.95",
            "createdByMemberId": null,
            "isActive": false,
            "viewCount": 0,
            "rating": 4.30,
            "phoneNumber": "028 3842 2171",
            "websiteUrl": "http://www.starbucks.vn/",
            "openTime": null,
            "member": null,
            "location": {
                ...
            },
            "interestingPointReview": [
                {
                    "reviewerName": "Hoàng Lê",
                    "language": "vi",
                    "reviewerAvt": "https://lh3.googleusercontent.com/a-/ALV-UjVrlUwUi_e_zICHyW4QAiFPEIpYVdRBAdgWcL5Rmm1Bs8j0qRJF=s128-c0x00000000-cc-rp-mo-ba5",
                    "rating": 5,
                    "reviewTime": "một tháng trước",
                    "reviewText": "Starbucks Nguyễn Văn Trỗi – Góc Cà Phê Sang Trọng Giữa Lòng Thành Phố ☕✨\n🌟 Đánh giá tổng thể: 9.5/10 – Không gian đẹp, cà phê ngon, đường dễ kẹt xe nhưng vẫn đáng ghé!\n📍 Địa chỉ: 141 Nguyễn Văn Trỗi, P.11, Q. Phú Nhuận, TP.HCM\n\nNếu bạn là tín đồ của Starbucks và đang tìm một nơi vừa sang, chill, và thuận tiện để làm việc, thì Starbucks Nguyễn Văn Trỗi chính là điểm đến lý tưởng. Nằm ngay trên trục đường huyết mạch nối liền sân bay Tân Sơn Nhất với trung tâm Sài Gòn, quán lúc nào cũng đông đúc, nhưng vẫn giữ được vibe đẳng cấp và thư thái đúng chuẩn Starbucks.\n\n1. Không gian – Rộng rãi, sang trọng, view đẹp (9.5/10) 🏡\nQuán có nhiều tầng, thoải mái lựa chọn chỗ ngồi từ tầng trệt đến tầng trên.\n\nCửa kính lớn đón ánh sáng tự nhiên, ngồi làm việc hay đọc sách đều rất thích.\n\nKhông gian yên tĩnh, không quá ồn ào như một số chi nhánh khác, phù hợp cho dân công sở, freelancer.\n\nVibe hiện đại, sang trọng, đúng chất của một Starbucks đặt tại khu phố sầm uất.\n\n💡 Tip nhỏ: Nếu bạn thích ngồi ngắm phố phường, chọn bàn gần cửa kính là lý tưởng nhất!\n\n2. Cà phê – Chất lượng ổn định, luôn thơm ngon (9.5/10) ☕\nDù là chi nhánh nào thì Starbucks vẫn giữ được công thức pha chế đồng đều, và Nguyễn Văn Trỗi cũng không ngoại lệ.\n\nCold Brew: Cực kỳ hợp với những ai thích cà phê mạnh, vị đậm đà nhưng vẫn thanh thoát.\n\nCaramel Macchiato: Ngọt ngào, béo thơm, món best-seller dành cho team hảo ngọt.\n\nMatcha Latte: Vị trà xanh dịu nhẹ, thơm nhưng không quá đắng, uống vào thấy thư giãn ngay.\n\nBánh ngọt ăn kèm cũng rất ngon, nhất là Croissant bơ và Muffin việt quất.\n\n💡 Tip nhỏ: Nếu bạn thích thử nghiệm hương vị mới, hãy thử hỏi barista về các món \"hidden menu\" – đôi khi có bất ngờ thú vị!\n\n3. Trải nghiệm – Phục vụ chuyên nghiệp, chỗ ngồi lý tưởng để làm việc (9.5/10) 💻\nNhân viên thân thiện, chuyên nghiệp, luôn sẵn sàng hỗ trợ.\n\nWi-Fi mạnh, ổ cắm điện đầy đủ, cực kỳ thích hợp cho dân văn phòng, freelancer cần một không gian làm việc thoải mái.\n\nGiữ xe ngay trước quán, khá tiện lợi dù đường Nguyễn Văn Trỗi thường xuyên đông đúc.\n\n💡 Tip nhỏ: Nếu bạn cần một buổi sáng làm việc hiệu quả, hãy đến Starbucks Nguyễn Văn Trỗi vào khung giờ 8h – 11h, lúc này quán chưa quá đông và không gian rất yên tĩnh.\n\n4. Tổng kết – Một Starbucks xứng đáng để ghé (9.5/10) 🌟\n👉 Điểm cộng: Không gian đẹp, đồ uống ngon, phục vụ tốt, phù hợp để làm việc hoặc thư giãn.\n👉 Điểm trừ: Đường Nguyễn Văn Trỗi hay kẹt xe vào giờ cao điểm, nên đi sớm hoặc gửi xe ở chỗ dễ quay đầu.\n\n💖 Dành cho ai đang tìm một góc Starbucks yên tĩnh nhưng vẫn sang trọng, Starbucks Nguyễn Văn Trỗi chắc chắn là một lựa chọn không thể bỏ qua!",
                    "interestingPoint": null
                },
                {
                    "reviewerName": "Pozaa Danghongtruong",
                    "language": "vi",
                    "reviewerAvt": "https://lh3.googleusercontent.com/a/ACg8ocJIpRTpVYgp7nc-zYJQJSObtHaqjeJd4PO8IFif1fSfOVQ8=s128-c0x00000000-cc-rp-mo-ba2",
                    "rating": 5,
                    "reviewTime": "một tuần trước",
                    "reviewText": "Mình cực kì ấn tượng cách phục vụ của nhân viên ở đây.... Mình có lỡ tay làm đổ ly matcha mới nhận .. Thì có ra quầy nhờ c nv có thể dọn đc k.. Thì c đã hỗ trợ và làm lại 1 ly mới cho mình luôn và rất vui vẻ... Phục vụ rất tốt luôn",
                    "interestingPoint": null
                },
                ...
            ]
        }
    },
    ...
  ]
},
{
    ...
}
    

Giải thích phản hồi

Trường Mô tả
routeName Tên mô tả tuyến đường
routeType Loại của tuyến đường (1, 2, 3 - shortest, fastest, comfortable)
startLocationId Mã của điểm bắt đầu
endLocationId Mã của điểm kết thúc
durationMinutes Ước tính thời gian di chuyển (phút)
distanceKm Khoảng cách (km) tuyến đường
searchCount Số lần người dùng tìm kiếm tuyến đường này
startLocation Thông tin của địa điểm bắt đầu (giống mảng kết quả của chức năng tìm kiếm địa điểm)
endLocation Thông tin của địa điểm kết thúc (giống mảng kết quả của chức năng tìm kiếm địa điểm)
geometry Danh sách tọa độ các điểm trên tuyến đường
pois Danh sách các điểm thú vị trên tuyến đường (nopois = false, nếu true thì trả về []) (nếu có)
reason Lí do chọn điểm thú vị này
interestingPoint Thông tin chi tiết của điểm thú vị (nếu có)
interestingPointReview Thông tin các đánh giá trên google map của điểm thú vị (nếu có)

Giới hạn tốc độ

API có giới hạn tốc độ khác nhau tùy thuộc vào gói dịch vụ của bạn:

  • Gói Free: 10 yêu cầu mỗi ngày
  • Gói Business: Không giới hạn số lượng yêu cầu

Khi bạn vượt quá giới hạn, API sẽ trả về mã lỗi 429 (Too Many Requests).

Mã lỗi

API sử dụng mã trạng thái HTTP tiêu chuẩn để chỉ ra thành công hoặc thất bại của yêu cầu.

Mã trạng thái Mô tả
200 - OK Yêu cầu thành công
400 - Bad Request Yêu cầu không hợp lệ
401 - Unauthorized Client-Id hoặc Client-Secret không hợp lệ hoặc thiếu
404 - Not Found Không tìm thấy tài nguyên
429 - Too Many Requests Vượt quá giới hạn tốc độ
500 - Internal Server Error Lỗi máy chủ