Đang tải dữ liệu…
Đang tải dữ liệu…
API Preview / Integration Architecture
Địa chỉ gốc https://api.<domain>/v1 – minh họa, chưa vận hành
Backend chưa được triển khai. Không có endpoint nào đang hoạt động; các lệnh cURL và JavaScript dưới đây dùng địa chỉ giữ chỗ và sẽ không trả về dữ liệu nếu chạy thử.
Năm lớp
Nguồn dữ liệu, lớp thu nhận, nền tảng, cổng API và lớp ứng dụng – mỗi lớp tách biệt, cùng một chuẩn metadata và quyền sử dụng.
01
Nguồn dữ liệu
02
Thu thập · số hóa · chuẩn hóa
03
Nền tảng dữ liệu văn hóa
04
Preview – chưa vận hành
Kiến trúc dữ liệu · dự kiến
Kho quản lý thực thể văn hóa – có danh tính, quan hệ, không gian, thời gian, nguồn gốc và điều kiện khai thác – chứ không chỉ các tệp. Các trường đều tùy chọn và tương thích ngược với bản ghi hiện có.
EntityThực thể · định danh
Có dữ liệu demo8 bản ghi có tên và mã ngoài có nguồn · nhân vật, sự kiện: có thể liên kết khi được bổ sung
RelationQuan hệ có nguồn gốc
Có dữ liệu demoquan hệ đọc từ trường bản ghi, biên tập và suy ra
SpatialKhông gian
Có dữ liệu demoTọa độ điểm của bản ghi · ranh giới cấp tỉnh có nguồn: 34 đơn vị (từ 01/07/2025) và 63 đơn vị (2008–2025)
TemporalThời gian
Có dữ liệu demoBa trục tách biệt: thời kỳ văn hóa của bản ghi · thời điểm địa giới hành chính (2 snapshot có nguồn) · thời điểm của một thực thể (17 bằng chứng có nguồn cho 6 công trình Hà Nội) · chưa có lớp bản đồ lịch sử đã định vị
AccessMức tiếp cận
Chỉ kiến trúcbản ghi mẫu chưa được gán mức tiếp cận
ProvenanceNguồn gốc
Có dữ liệu demoMỗi trường và quan hệ ghi rõ được biết từ đâu
Sẵn sàng cho AI · hướng kiến trúc
Một thực thể chuẩn, định danh hợp nhất và quan hệ có nguồn là điều kiện để truy xuất theo ngữ cảnh có trích dẫn. Chưa có ứng dụng AI nào vận hành trên lớp dữ liệu này.
Khối nền tảng: Search index
Tìm kiếm toàn văn không dấu, lọc đa chiều theo lĩnh vực, loại dữ liệu, thời kỳ, địa phương, bộ sưu tập, đơn vị cung cấp và quyền; trả về facet để dựng bộ lọc.
GET/assetsminh họa
qstringsector · type · period · provincestring[]sortrelevance | newest | az | periodfacetsobjectcurl -X GET "https://api.<domain>/v1/assets?q=tr%E1%BB%91ng%20%C4%91%E1%BB%93ng&type=3d&limit=3" \
-H "Authorization: Bearer $CULTURAL_DATA_API_KEY" \
-H "Accept: application/json"Phản hồi mẫu · 200 · application/json · dựng từ dữ liệu demo
{
"query": {
"q": "trống đồng",
"type": [
"3d"
]
},
"total": 5,
"page": 1,
"items": [
{
"id": "a001",
"slug": "trong-dong-ngoc-lu",
"code": "KDL-ART-010277",
"title": "Trống đồng Ngọc Lũ",
"sector": "fine-arts",
"province": "ha-noi",
"period": "prehistory",
"mediaTypes": [
"image",
"3d",
"document",
"video"
],
"thumbnail": "/images/media/ngoclu-drum.webp"
},
{
"id": "a003",
"slug": "trong-dong-hoang-ha",
"code": "KDL-ART-010351",
"title": "Trống đồng Hoàng Hạ",
"sector": "fine-arts",
"province": "ha-noi",
"period": "prehistory",
"mediaTypes": [
"image",
"3d"
],
"thumbnail": "/images/media/hoangha-drum.webp"
},
{
"id": "a006",
"slug": "trong-dong-dong-son-loai-i",
"code": "KDL-ART-010462",
"title": "Trống đồng Đông Sơn loại I",
"sector": "fine-arts",
"province": "ha-noi",
"period": "prehistory",
"mediaTypes": [
"image",
"3d"
],
"thumbnail": "/images/media/dongson-drum-1.webp"
}
],
"facets": {
"sector": [
{
"value": "fine-arts",
"count": 3
},
{
"value": "performing-arts",
"count": 2
},
{
"value": "games-software",
"count": 2
},
{
"value": "tourism",
"count": 3
},
{
"value": "design",
"count": 1
}
],
"period": [
{
"value": "prehistory",
"count": 3
},
{
"value": "contemporary",
"count": 2
}
]
}
}Khối nền tảng: Knowledge graph
Trả về hồ sơ metadata đầy đủ của một bản ghi: định danh, phân loại theo 10 lĩnh vực CNVH, niên đại, chất liệu, nơi lưu giữ, quyền và liên kết.
GET/assets/trong-dong-ngoc-luminh họa
codestringsector · period{ id, label }rights{ id, label }relatedAssetsstring[]curl -X GET "https://api.<domain>/v1/assets/trong-dong-ngoc-lu" \
-H "Authorization: Bearer $CULTURAL_DATA_API_KEY" \
-H "Accept: application/json"Phản hồi mẫu · 200 · application/json · dựng từ dữ liệu demo
{
"id": "a001",
"slug": "trong-dong-ngoc-lu",
"code": "KDL-ART-010277",
"title": "Trống đồng Ngọc Lũ",
"titleEn": "Ngoc Lu Bronze Drum",
"objectType": "Hiện vật khảo cổ",
"sector": {
"id": "fine-arts",
"label": "Mỹ thuật, Nhiếp ảnh & Triển lãm"
},
"secondarySectors": [
"tourism",
"games-software",
"design"
],
"period": {
"id": "prehistory",
"label": "Tiền sử – sơ sử"
},
"year": "Khoảng 2.500 – 2.000 năm trước",
"creator": "Cư dân văn hóa Đông Sơn",
"institution": "Bảo tàng Lịch sử Quốc gia",
"materials": "Hợp kim đồng",
"dimensions": "Cao 63 cm · Đường kính mặt 79,3 cm",
"location": {
"province": "ha-noi",
"provinceName": "Hà Nội",
"coordinates": {
"lat": 21.0245,
"lng": 105.8599
}
},
"tags": [
"Đông Sơn",
"Bảo vật quốc gia",
"Trống đồng",
"Hoa văn",
"Khảo cổ"
],
"rights": {
"id": "public-domain",
"label": "Phạm vi công cộng"
},
"provider": {
"id": "museums",
"label": "Bảo tàng"
},
"relatedAssets": [
"hoa-van-mat-trong-ngoc-lu",
"trong-dong-hoang-ha",
"nap-thap-dong-ngoc-lu",
"phong-trung-bay-trong-dong"
],
"updatedAt": "2026-08-20"
}Khối nền tảng: Media store
Danh sách tệp ảnh, video, audio và tài liệu của bản ghi, kèm kích thước, trạng thái số hóa và thông tin ghi nguồn cho từng tệp.
GET/assets/trong-dong-ngoc-lu/mediaminh họa
images[].credit{ author, license, source }width · heightnumberstatusavailable | digitisingcurl -X GET "https://api.<domain>/v1/assets/trong-dong-ngoc-lu/media" \
-H "Authorization: Bearer $CULTURAL_DATA_API_KEY" \
-H "Accept: application/json"Phản hồi mẫu · 200 · application/json · dựng từ dữ liệu demo
{
"asset": "trong-dong-ngoc-lu",
"images": [
{
"id": "ngoclu-drum",
"url": "/images/media/ngoclu-drum.webp",
"alt": "Thân trống đồng Ngọc Lũ với quai trống",
"width": 1280,
"height": 1194,
"credit": {
"author": "VuThiAnh",
"license": "Public domain",
"source": "https://commons.wikimedia.org/wiki/File:Ngoc_Lu.jpg"
}
},
{
"id": "ngoclu-tympanum",
"url": "/images/media/ngoclu-tympanum.webp",
"alt": "Bản vẽ hoa văn mặt trống đồng Ngọc Lũ",
"width": 1400,
"height": 1400,
"credit": {
"author": "Ebaychatter0",
"license": "CC BY-SA 3.0",
"source": "https://commons.wikimedia.org/wiki/File:Trong_Dong_Ngoc_Lu.svg"
}
},
{
"id": "drum-showcase",
"url": "/images/media/drum-showcase.webp",
"alt": "Trống đồng trong tủ kính trưng bày",
"width": 1280,
"height": 960,
"credit": {
"author": "Gryffindor",
"license": "CC BY-SA 3.0",
"source": "https://commons.wikimedia.org/wiki/File:National_Museum_Vietnamese_History_24.jpg"
}
},
{
"id": "bronze-drums-hall",
"url": "/images/media/bronze-drums-hall.webp",
"alt": "Phòng trưng bày trống đồng",
"width": 1280,
"height": 853,
"credit": {
"author": "Daderot",
"license": "CC0",
"source": "https://commons.wikimedia.org/wiki/File:Bronze_drums_-_National_Museum_of_Vietnamese_History_-_Hanoi,_Vietnam_-_DSC05557.JPG"
}
}
],
"video": {
"title": "Ghi hình không gian trưng bày trống đồng",
"status": "digitising",
"poster": "/images/media/bronze-drums-hall.webp"
},
"documents": [
{
"title": "Hồ sơ hiện vật (bản mô tả)",
"format": "PDF",
"pages": 12,
"status": "digitising"
},
{
"title": "Bản vẽ hoa văn mặt trống",
"format": "TIFF",
"pages": 1,
"status": "digitising"
}
]
}Khối nền tảng: 3D repository
Thông tin mô hình 3D: trạng thái số hóa, định dạng GLB/USDZ, mức chi tiết (LOD), phương pháp thu nhận. Bản ghi chưa có bản quét trả về trạng thái minh họa, không giả tệp.
GET/assets/trong-dong-ngoc-lu/modelminh họa
statuspublished | processing | placeholderformatsstring[]lodnumber[]curl -X GET "https://api.<domain>/v1/assets/trong-dong-ngoc-lu/model" \
-H "Authorization: Bearer $CULTURAL_DATA_API_KEY" \
-H "Accept: application/json"Phản hồi mẫu · 200 · application/json · dựng từ dữ liệu demo
{
"asset": "trong-dong-ngoc-lu",
"status": "placeholder",
"formats": [],
"src": null,
"preview": {
"kind": "procedural-placeholder",
"shape": "drum"
},
"captureMethod": "Photogrammetry (dự kiến)",
"polygons": "Chờ bản quét",
"lod": [],
"note": "Chưa có bản quét; trình xem hiển thị hình khối minh họa."
}Khối nền tảng: GIS
Địa điểm văn hóa dạng GeoJSON theo tỉnh/thành (34 đơn vị hành chính từ 01/7/2025) và danh mục, liên kết tới bản ghi – nền cho bản đồ số và digital twin.
GET/places?province=ha-noi&category=museumminh họa
geometry.coordinates[lng, lat]categoryheritage | museum | …assetsstring[]curl -X GET "https://api.<domain>/v1/places?province=ha-noi&category=museum" \
-H "Authorization: Bearer $CULTURAL_DATA_API_KEY" \
-H "Accept: application/json"Phản hồi mẫu · 200 · application/json · dựng từ dữ liệu demo
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"id": "bao-tang-lich-su",
"geometry": {
"type": "Point",
"coordinates": [
105.8599,
21.0245
]
},
"properties": {
"name": "Bảo tàng Lịch sử Quốc gia",
"category": "museum",
"province": "ha-noi",
"assets": [
"trong-dong-ngoc-lu",
"trong-dong-hoang-ha",
"phong-trung-bay-trong-dong",
"bao-tang-lich-su-quoc-gia"
]
}
},
{
"type": "Feature",
"id": "bao-tang-my-thuat",
"geometry": {
"type": "Point",
"coordinates": [
105.8373,
21.0307
]
},
"properties": {
"name": "Bảo tàng Mỹ thuật Việt Nam",
"category": "museum",
"province": "ha-noi",
"assets": [
"bao-tang-my-thuat",
"nap-thap-dong-ngoc-lu",
"tranh-dong-ho-dam-cuoi-chuot",
"tranh-dong-ho-ga-trong"
]
}
},
{
"type": "Feature",
"id": "bao-tang-phu-nu",
"geometry": {
"type": "Point",
"coordinates": [
105.8493,
21.0247
]
},
"properties": {
"name": "Bảo tàng Phụ nữ Việt Nam",
"category": "museum",
"province": "ha-noi",
"assets": [
"ao-dai-lua-ha-noi"
]
}
},
{
"type": "Feature",
"id": "bao-tang-dan-toc-hoc",
"geometry": {
"type": "Point",
"coordinates": [
105.7985,
21.0405
]
},
"properties": {
"name": "Bảo tàng Dân tộc học Việt Nam",
"category": "museum",
"province": "ha-noi",
"assets": [
"nha-rong-bao-tang-dan-toc-hoc",
"trang-phuc-hmong-hoa",
"hoa-van-theu-hmong",
"khung-cui-thai-den"
]
}
}
]
}Khối nền tảng: Ingest
Nhập lô dữ liệu từ đơn vị nguồn: ánh xạ metadata, kiểm tra quyền, báo cáo trường thiếu trước khi biên tập viên duyệt và xuất bản.
POST/datasets/importsminh họa
sourcestringrecords[]object[]validation[]object[]curl -X POST "https://api.<domain>/v1/datasets/imports" \
-H "Authorization: Bearer $CULTURAL_DATA_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"source":"museums","format":"json","records":[{"externalId":"INV-0001","title":"Trống đồng Ngọc Lũ","objectType":"Hiện vật khảo cổ","institution":"Bảo tàng Lịch sử Quốc gia","rights":"public-domain","images":["ngoclu-drum"]}]}'Phản hồi mẫu · 200 · application/json · dựng từ dữ liệu demo
{
"importId": "imp_preview_0001",
"status": "preview_only",
"source": {
"id": "museums",
"label": "Bảo tàng"
},
"received": 1,
"validation": [
{
"field": "title",
"ok": true
},
{
"field": "rights",
"ok": true,
"mappedTo": "Phạm vi công cộng"
},
{
"field": "sector",
"ok": false,
"message": "Thiếu lĩnh vực CNVH – sẽ được gợi ý khi chuẩn hóa"
},
{
"field": "coordinates",
"ok": false,
"message": "Thiếu tọa độ – cần bổ sung cho Spatial API"
}
],
"next": "Biên tập viên duyệt ánh xạ metadata trước khi xuất bản."
}Khi lớp kết nối API được triển khai, quyền truy cập được quản lý theo tổ chức, mục đích sử dụng và trạng thái của từng bản ghi. Mỗi dữ liệu trả về vẫn giữ đầy đủ nguồn gốc, metadata và điều kiện khai thác.