API cho lập trình viên

Bắt đầu

1. Đăng ký hoặc đăng nhập.
2. Vào Tài khoản → Khóa API, tạo khóa và chép lại (khóa chỉ hiện một lần).
3. Gửi khóa trong header Authorization: Bearer <khóa>.

curl -H "Authorization: Bearer $GIADAT_KEY" \
  "https://giadat.wyattos.cyou/api/v1/streets?q=tran+hung+dao&ward=Đông+Hòa"

Các đường dẫn

Đều là GET, gốc https://giadat.wyattos.cyou/api/v1. Giá tính bằng đồng/m², tiền bằng đồng.

/wards

Danh sách 168 phường, xã, đặc khu kèm slug, phụ lục, khu vực.

/streets?q={tên đường}&ward={phường}&limit={1–60}

Tìm tuyến đường như ô tìm ở trang chủ: không dấu, viết tắt, mã đường đều được.

/segments/{phường}/{đoạn}

Một đoạn đường: phạm vi, cảnh báo dữ liệu, giá vị trí 1–4 của đất ở, thương mại dịch vụ, sản xuất kinh doanh.

/segments/{phường}/{đoạn}/valuation?land_use=…&position=…&area=…

Tính giá trị lô đất như form trên trang đoạn đường, kèm phí công chứng và diễn giải từng bước.

Ví dụ tính giá

Đường Trần Hưng Đạo, Phường Đông Hòa, đất ở, vị trí 3 (hẻm 3 m đến dưới 5 m), 72,4 m². Số thập phân dùng dấu chấm. Tham số khác: deeper_than_100m, dirt_alley, multiple_frontages (true/false), reduction_case, frontage_width và plot_depth (thửa dài), hidden_areas[] (phần khuất).

curl -H "Authorization: Bearer $GIADAT_KEY" \
  "https://giadat.wyattos.cyou/api/v1/segments/phuong-dong-hoa/duong-tran-hung-dao/valuation?land_use=residential&position=3&area=72.4"

{
  "data": {
    "segment": { "street_name": "Đường Trần Hưng Đạo", "stretch": "…", "prices": { "residential": { "1": 36700000, "2": 18350000, "3": 14680000, "4": 11744000 }, … }, … },
    "input": { "land_use": { "code": "residential", "label": "Đất ở" }, "position": 3, "area": 72.4, … },
    "unit_price": 14680000,
    "total_value": 1062832000,
    "total_in_words": "Một tỷ không trăm sáu mươi hai triệu tám trăm ba mươi hai nghìn đồng",
    "notary_fee": 1037699,
    "steps": ["…"],
    "page_url": "https://giadat.wyattos.cyou/phuong/phuong-dong-hoa/duong-tran-hung-dao?loai=residential&vi_tri=3&dien_tich=72%2C4"
  }
}

Giới hạn và lỗi

• Mỗi tài khoản 60 lượt mỗi phút và 5.000 lượt mỗi ngày, cộng dồn mọi khóa. Header X-RateLimit-Remaining cho biết còn bao nhiêu lượt trong phút này.
• Cần nhiều hơn: gói mở rộng 300 lượt mỗi phút, 50.000 lượt mỗi ngày, 49.000 đ cho 30 ngày, thanh toán qua payOS.
• 401: thiếu khóa, khóa sai, đã thu hồi hoặc hết hạn (khóa dùng được 365 ngày).
• 404: không có phường, xã hoặc đoạn đường này.
• 422: tham số không hợp lệ; errors liệt kê lỗi theo từng tham số, bằng tiếng Việt.
• 429: vượt giới hạn; chờ số giây trong header Retry-After.

Đặc tả đầy đủ: OpenAPI 3.1 (JSON), mở bằng Swagger UI, Postman, Insomnia hay dùng để sinh mã client.