{"openapi":"3.1.0","info":{"title":"Addy Geo — National Administrative Geo Master API","description":"Vietnam's administrative geography (post-2025 reform: province → ward)\nas shared, **read-only** master data. Resolve per level —\n`/api/v1/provinces/{n}` and `/api/v1/wards/{n}` — where `n` is the plain\n`national_code` (unique per level, immutable, never the internal `id`).\nName search is diacritic-insensitive (\"ha noi\" matches \"Hà Nội\"), and the\nlegacy endpoints map pre-2025 wards to their current ward. Responses are\ncached (`ETag` / `Cache-Control`) and CORS-enabled; the admin site owns writes.","contact":{"name":"Minh Vo Cong — IDS","url":"/","email":"minh.vo@idsolutions.com.vn"},"license":{"name":"Proprietary — IDS"},"version":"1.0.1"},"externalDocs":{"description":"Developer portal & online guides (Script / React / Next.js / Java)","url":"/guides.html"},"servers":[{"url":"https://geo.addy.vn","description":"Generated server url"}],"tags":[{"name":"Regions","description":"Provinces & wards: list, resolve-by-code, province tree, diacritic-insensitive search, bulk export (JSON / CSV), and legacy (pre-2025) ward mapping."}],"paths":{"/api/v1/wards/{code}":{"get":{"tags":["Regions"],"summary":"Resolve one ward by its number, including its parent province","operationId":"ward","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponseRegionDto"}}}}}}},"/api/v1/wards/{code}/legacies":{"get":{"tags":["Regions"],"summary":"The pre-2025 wards that were merged to form this current ward","operationId":"legacies","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponseListLegacyWardDto"}}}}}}},"/api/v1/wards/from-legacy":{"get":{"tags":["Regions"],"summary":"Migrate an old address: pre-2025 ward code/name → current ward(s)","operationId":"fromLegacy","parameters":[{"name":"code","in":"query","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"name","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponseListLegacyLookupDto"}}}}}}},"/api/v1/regions/search":{"get":{"tags":["Regions"],"summary":"Search regions by name, optionally filtered by level and parent province","operationId":"search","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"}},{"name":"level","in":"query","required":false,"schema":{"type":"string","enum":["PROVINCE","LOCAL"]}},{"name":"parent","in":"query","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":0}},{"name":"size","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":20}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponsePageResponseRegionDto"}}}}}}},"/api/v1/provinces":{"get":{"tags":["Regions"],"summary":"List all provinces","operationId":"provinces","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponseListRegionDto"}}}}}}},"/api/v1/provinces/{code}":{"get":{"tags":["Regions"],"summary":"Resolve one province by its number","operationId":"province","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponseRegionDto"}}}}}}},"/api/v1/provinces/{code}/wards":{"get":{"tags":["Regions"],"summary":"List the wards (LOCALs) under a province","operationId":"wards","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponseListRegionDto"}}}}}}},"/api/v1/provinces/{code}/tree":{"get":{"tags":["Regions"],"summary":"A province with all its wards nested (single bulk payload)","operationId":"tree","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponseProvinceTreeDto"}}}}}}},"/api/v1/export":{"get":{"tags":["Regions"],"summary":"Full active dataset as JSON (for consumers mirroring the data)","operationId":"exportJson","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponseListRegionDto"}}}}}}},"/api/v1/export.csv":{"get":{"tags":["Regions"],"summary":"Full active dataset as CSV","operationId":"exportCsv","responses":{"200":{"description":"OK","content":{"text/csv":{"schema":{"type":"string"}}}}}}}},"components":{"schemas":{"ApiResponseRegionDto":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/RegionDto"}}},"RegionDto":{"type":"object","description":"An administrative region (province or ward)","properties":{"nationalCode":{"type":"integer","format":"int64","description":"Public number, unique per level","example":1},"name":{"type":"string","example":"Thành phố Hà Nội"},"level":{"type":"string","enum":["PROVINCE","LOCAL"]},"divisionType":{"type":"string","description":"Division type as an enum","enum":["TINH","THANH_PHO_TRUNG_UONG","PHUONG","XA","DAC_KHU"]},"divisionTypeLabel":{"type":"string","description":"Vietnamese label of the division type","example":"thành phố trung ương"},"codename":{"type":"string","example":"ha_noi"},"phoneCode":{"type":"string","description":"Dialable phone/area number; provinces only","example":24},"parentCode":{"type":"integer","format":"int64","description":"Parent province number; null for provinces","example":1},"parentName":{"type":"string","description":"Parent province name; null for provinces"},"active":{"type":"boolean","description":"False if the region has been deactivated (soft-deleted)"}}},"ApiResponseListLegacyWardDto":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/LegacyWardDto"}}}},"LegacyWardDto":{"type":"object","description":"A pre-2025 ward (old 3-level address)","properties":{"legacyCode":{"type":"integer","format":"int64","example":16},"legacyName":{"type":"string","example":"Phường Ngọc Hà"},"legacyDistrict":{"type":"string","example":"Quận Ba Đình (001)"},"legacyProvince":{"type":"string","example":"Thành phố Hà Nội (01)"},"mergeNote":{"type":"string","description":"How it was merged","example":"Nhập một phần"}}},"ApiResponseListLegacyLookupDto":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/LegacyLookupDto"}}}},"LegacyLookupDto":{"type":"object","description":"A pre-2025 ward mapped to its current ward","properties":{"legacy":{"$ref":"#/components/schemas/LegacyWardDto"},"ward":{"$ref":"#/components/schemas/RegionDto","description":"The current (post-2025) ward"}}},"ApiResponsePageResponseRegionDto":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/PageResponseRegionDto"}}},"PageResponseRegionDto":{"type":"object","properties":{"content":{"type":"array","items":{"$ref":"#/components/schemas/RegionDto"}},"page":{"type":"integer","format":"int32"},"size":{"type":"integer","format":"int32"},"totalElements":{"type":"integer","format":"int64"},"totalPages":{"type":"integer","format":"int32"},"hasNext":{"type":"boolean"},"hasPrevious":{"type":"boolean"}}},"ApiResponseListRegionDto":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/RegionDto"}}}},"ApiResponseProvinceTreeDto":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/ProvinceTreeDto"}}},"ProvinceTreeDto":{"type":"object","description":"A province with its wards nested","properties":{"province":{"$ref":"#/components/schemas/RegionDto"},"wards":{"type":"array","items":{"$ref":"#/components/schemas/RegionDto"}}}}}}}