{"openapi":"3.1.0","info":{"title":"Addy Geo — National Administrative Geo Master API","description":"Vietnam's administrative geography (post-2025 reform: province → ward) as shared\nmaster data. Codes are level-prefixed (P<code>/W<code>). Read-only; the admin\nsite maintains the data.","contact":{"name":"Minh Vo Cong","email":"minh.vo@idsolutions.com.vn"},"license":{"name":"Proprietary — IDS"},"version":"1.0.0"},"servers":[{"url":"https://geo.addy.vn","description":"Generated server url"}],"tags":[{"name":"Regions","description":"Vietnam administrative geography (provinces & wards)"}],"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/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)"}}},"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"}}}}}}}