{"openapi":"3.1.0","info":{"title":"Giá đất TP.HCM API","version":"1.0.0","description":"Tra cứu và tính giá đất TP.HCM theo Bảng giá đất ban hành kèm Nghị quyết 87/2025/NQ-HĐND, áp dụng từ 01/01/2026. Kết quả chỉ để tham khảo theo bảng giá nhà nước, không phải giá thị trường. Mỗi tài khoản được gọi 60 lượt mỗi phút và 5000 lượt mỗi ngày (cộng dồn mọi khóa). Giá tính bằng đồng/m², tiền bằng đồng."},"servers":[{"url":"https://giadat.wyattos.cyou/api/v1"}],"security":[{"bearerAuth":[]}],"paths":{"/wards":{"get":{"operationId":"listWards","summary":"Danh sách 168 phường, xã, đặc khu","responses":{"200":{"description":"Danh sách theo mã đơn vị.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Ward"}}}}}}},"201":{"$ref":"#/components/responses/Unauthenticated"},"202":{"$ref":"#/components/responses/TooManyRequests"}}}},"/streets":{"get":{"operationId":"searchStreets","summary":"Tìm tuyến đường theo tên","description":"Gõ không dấu, viết tắt hay mã đường đều được (le loi, CMT8, QL 13). Không có kết quả khớp thì trả kết quả gần đúng, meta.approximate = true.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","maxLength":100},"example":"tran hung dao"},{"name":"ward","in":"query","description":"Tên phường, xã để giới hạn (Sài Gòn, P. Sài Gòn, Phường Sài Gòn).","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":60,"default":20}}],"responses":{"200":{"description":"Các đoạn đường khớp, khớp nhất trước.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Segment"}},"meta":{"type":"object","properties":{"query":{"type":"string"},"count":{"type":"integer"},"limit":{"type":"integer"},"approximate":{"type":"boolean"}}}}}}}},"422":{"$ref":"#/components/responses/ValidationError"},"423":{"$ref":"#/components/responses/Unauthenticated"},"424":{"$ref":"#/components/responses/TooManyRequests"}}}},"/segments/{ward}/{segment}":{"get":{"operationId":"showSegment","summary":"Một đoạn đường với giá từng vị trí","parameters":[{"name":"ward","in":"path","required":true,"description":"Slug phường, xã (xem /wards).","schema":{"type":"string"},"example":"phuong-dong-hoa"},{"name":"segment","in":"path","required":true,"description":"Slug đoạn đường trong phường, xã.","schema":{"type":"string"},"example":"duong-tran-hung-dao"}],"responses":{"200":{"description":"Đoạn đường.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Segment"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/Unauthenticated"},"406":{"$ref":"#/components/responses/TooManyRequests"}}}},"/segments/{ward}/{segment}/valuation":{"get":{"operationId":"valueLand","summary":"Tính giá trị lô đất trên đoạn đường","description":"Như form trên trang đoạn đường: đơn giá theo vị trí và các điều chỉnh của Phụ lục I, tổng giá trị, phí công chứng, diễn giải từng bước. Số thập phân dùng dấu chấm.","parameters":[{"name":"ward","in":"path","required":true,"description":"Slug phường, xã (xem /wards).","schema":{"type":"string"},"example":"phuong-dong-hoa"},{"name":"segment","in":"path","required":true,"description":"Slug đoạn đường trong phường, xã.","schema":{"type":"string"},"example":"duong-tran-hung-dao"},{"name":"land_use","in":"query","required":true,"description":"Loại đất; segment.land_uses liệt kê loại tính được trên đoạn này.","schema":{"type":"string","enum":["residential","commercial","production","commercial_special","production_special","religious_cemetery"]},"example":"residential"},{"name":"position","in":"query","required":true,"description":"1 mặt tiền; 2 hẻm từ 5 m; 3 hẻm 3 m đến dưới 5 m; 4 còn lại.","schema":{"type":"integer","minimum":1,"maximum":4},"example":3},{"name":"area","in":"query","required":true,"description":"Diện tích loại đất này, m².","schema":{"type":"number","exclusiveMinimum":0},"example":72.4},{"name":"deeper_than_100m","in":"query","description":"Cách mép trong lề đường mặt tiền từ 100 m trở lên (giảm 10%).","schema":{"type":"boolean"}},{"name":"dirt_alley","in":"query","description":"Hẻm đất (bằng 80%).","schema":{"type":"boolean"}},{"name":"multiple_frontages","in":"query","description":"Tiếp giáp từ 2 mặt tiền đường (110%; dùng đoạn có giá cao nhất).","schema":{"type":"boolean"}},{"name":"reduction_case","in":"query","description":"Trường hợp tính 70% (mục 6.7–6.11 Phụ lục I).","schema":{"type":"string","enum":["bridge_side_road","overpass","power_line_corridor","overpass_ramp","separated_by_canal"]}},{"name":"frontage_width","in":"query","description":"Thửa dài (mục 6.1.b): chiều rộng mặt tiếp giáp, m; cần kèm plot_depth.","schema":{"type":"number","exclusiveMinimum":0}},{"name":"plot_depth","in":"query","description":"Thửa dài: chiều dài thửa, m; cần kèm frontage_width.","schema":{"type":"number","exclusiveMinimum":0}},{"name":"hidden_areas[]","in":"query","description":"Diện tích từng phần khuất của thửa hình L, T, đa giác (mục 6.1.a), tối đa 3 phần.","schema":{"type":"array","maxItems":3,"items":{"type":"number","exclusiveMinimum":0}}}],"responses":{"200":{"description":"Kết quả tính.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Valuation"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"423":{"$ref":"#/components/responses/Unauthenticated"},"424":{"$ref":"#/components/responses/TooManyRequests"}}}},"/openapi":{"get":{"operationId":"openApi","summary":"Đặc tả OpenAPI này","security":[],"responses":{"200":{"description":"Đặc tả OpenAPI 3.1.","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Khóa API tạo ở https://giadat.wyattos.cyou/tai-khoan/khoa-api (cần đăng nhập). Gửi kèm header Authorization: Bearer <khóa>."}},"schemas":{"Ward":{"type":"object","properties":{"code":{"type":"integer"},"name":{"type":"string","example":"Phường Đông Hòa"},"slug":{"type":"string","example":"phuong-dong-hoa"},"annex":{"type":"object","properties":{"code":{"type":"string","example":"III"},"label":{"type":"string"}}},"region":{"type":["string","null"],"description":"Khu vực I–IV (đất nông nghiệp, loại hình đặc thù)."},"url":{"type":"string","format":"uri"}}},"PositionPrices":{"type":["object","null"],"description":"Giá vị trí 1–4, đồng/m²; null khi văn bản không quy định.","properties":{"1":{"type":"integer"},"2":{"type":"integer"},"3":{"type":"integer"},"4":{"type":"integer"}}},"Segment":{"type":"object","properties":{"ward":{"$ref":"#/components/schemas/Ward"},"street_name":{"type":"string","example":"Đường Trần Hưng Đạo"},"slug":{"type":"string"},"stt":{"type":["string","null"],"description":"Số thứ tự trong văn bản."},"stretch":{"type":"string","example":"Trọn đường"},"from":{"type":["string","null"]},"to":{"type":["string","null"]},"group_name":{"type":["string","null"]},"flag":{"type":["object","null"],"description":"Cảnh báo dữ liệu gốc (nghi sai sót, cần đối chiếu, không có giá).","properties":{"code":{"type":"string"},"label":{"type":"string"},"note":{"type":["string","null"]}}},"prices":{"type":"object","properties":{"residential":{"$ref":"#/components/schemas/PositionPrices"},"commercial":{"$ref":"#/components/schemas/PositionPrices"},"production":{"$ref":"#/components/schemas/PositionPrices"}}},"land_uses":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"}}}},"links":{"type":"object","properties":{"page":{"type":"string","format":"uri"},"self":{"type":"string","format":"uri"},"valuation":{"type":"string","format":"uri"}}}}},"Valuation":{"type":"object","properties":{"segment":{"$ref":"#/components/schemas/Segment"},"input":{"type":"object","description":"Các tham số đã dùng."},"unit_price":{"type":"integer","description":"Đơn giá sau hệ số vị trí và điều chỉnh, đồng/m².","example":14680000},"total_value":{"type":"integer","description":"Đồng.","example":1062832000},"total_in_words":{"type":"string"},"notary_fee":{"type":"integer","description":"Phí công chứng theo TT 257/2016/TT-BTC, đồng.","example":1037699},"parts":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"area":{"type":"number"},"rate":{"type":"number"},"value":{"type":"integer"}}}},"steps":{"type":"array","items":{"type":"string"}},"page_url":{"type":"string","format":"uri","description":"Cùng phép tính trên trang web."},"pdf_url":{"type":"string","format":"uri","description":"Phiếu tính PDF của phép tính này (không cần khóa API)."}}},"Error":{"type":"object","properties":{"message":{"type":"string"}}}},"responses":{"Unauthenticated":{"description":"Thiếu khóa API, khóa sai hoặc hết hạn.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Không có phường, xã hoặc đoạn đường này.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ValidationError":{"description":"Tham số không hợp lệ; errors liệt kê theo từng tham số.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}},"TooManyRequests":{"description":"Vượt 60 lượt mỗi phút hoặc 5000 lượt mỗi ngày.","headers":{"Retry-After":{"description":"Số giây cần chờ.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}