{"openapi":"3.1.0","info":{"title":"TurkiyeAPI","version":"2.0.0","description":"REST API for Turkish administrative divisions: provinces, districts, municipalities, neighborhoods, and villages.","license":{"name":"MIT"}},"servers":[{"url":"https://api.turkiyeapi.dev","description":"Production"},{"url":"http://localhost:3000","description":"Local development"}],"tags":[{"name":"System","description":"Health and metadata endpoints."},{"name":"Datasets","description":"Static dataset downloads with cache headers."},{"name":"Provinces","description":"Province resources and province-scoped collections."},{"name":"Districts","description":"District resources and district-scoped collections."},{"name":"Municipalities","description":"Municipality resources and municipality-scoped collections."},{"name":"Neighborhoods","description":"Neighborhood resources."},{"name":"Villages","description":"Village resources."}],"paths":{"/health":{"get":{"tags":["System"],"summary":"Health check","parameters":[],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","const":"ok"}},"additionalProperties":false}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v2/meta":{"get":{"tags":["System"],"summary":"Get API and dataset metadata","parameters":[],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["apiVersion","datasetVersion","lastUpdated","sources","counts"],"properties":{"apiVersion":{"type":"string","minLength":1},"datasetVersion":{"type":"string","minLength":1},"lastUpdated":{"type":"string","minLength":1},"sources":{"type":"array","items":{"type":"object","required":["name","url","description"],"properties":{"name":{"type":"string","minLength":1},"url":{"type":"string","minLength":1},"description":{"type":"object","required":["tr","en"],"properties":{"tr":{"type":"string","minLength":1},"en":{"type":"string","minLength":1}}}},"additionalProperties":false}},"counts":{"type":"object","required":["provinces","districts","municipalities","neighborhoods","villages"],"properties":{"provinces":{"type":"integer","minimum":0},"districts":{"type":"integer","minimum":0},"municipalities":{"type":"integer","minimum":0},"neighborhoods":{"type":"integer","minimum":0},"villages":{"type":"integer","minimum":0}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v2/openapi.json":{"get":{"tags":["System"],"summary":"Get OpenAPI document","parameters":[],"responses":{"200":{"description":"Successful response."},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v2/datasets/{datasetFile}":{"get":{"tags":["Datasets"],"summary":"Download latest static dataset file","description":"Valid dataset files: provinces.json, districts.json, municipalities.json, neighborhoods.json, villages.json.","parameters":[{"name":"datasetFile","in":"path","required":true,"schema":{"anyOf":[{"type":"string","const":"provinces.json"},{"type":"string","const":"districts.json"},{"type":"string","const":"municipalities.json"},{"type":"string","const":"neighborhoods.json"},{"type":"string","const":"villages.json"}]}}],"responses":{"200":{"description":"Static dataset JSON file.","content":{"application/json":{"schema":{"type":"array","items":{}}}}},"304":{"description":"The cached dataset is still fresh."},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Dataset not found.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v2/datasets/{datasetVersion}/{datasetFile}":{"get":{"tags":["Datasets"],"summary":"Download versioned static dataset file","description":"Currently supported dataset version: 2025.","parameters":[{"name":"datasetVersion","in":"path","required":true,"schema":{"type":"string","const":"2025"}},{"name":"datasetFile","in":"path","required":true,"schema":{"anyOf":[{"type":"string","const":"provinces.json"},{"type":"string","const":"districts.json"},{"type":"string","const":"municipalities.json"},{"type":"string","const":"neighborhoods.json"},{"type":"string","const":"villages.json"}]}}],"responses":{"200":{"description":"Static dataset JSON file.","content":{"application/json":{"schema":{"type":"array","items":{}}}}},"304":{"description":"The cached dataset is still fresh."},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Dataset not found.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v2/provinces":{"get":{"tags":["Provinces"],"summary":"List provinces","parameters":[{"name":"search","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Case-insensitive normalized text search by name."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Comma-separated field names to include in each response item."},{"name":"sort","in":"query","required":false,"schema":{"anyOf":[{"type":"string","const":"id"},{"type":"string","const":"-id"},{"type":"string","const":"name"},{"type":"string","const":"-name"},{"type":"string","const":"population"},{"type":"string","const":"-population"}]},"description":"Sort order for list responses."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":100},"description":"Maximum number of items to return."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0},"description":"Zero-based item offset."},{"name":"minPopulation","in":"query","required":false,"schema":{"type":"integer","minimum":0},"description":"Minimum population. Must be less than or equal to maxPopulation when both are provided."},{"name":"maxPopulation","in":"query","required":false,"schema":{"type":"integer","minimum":0},"description":"Maximum population. Must be greater than or equal to minPopulation when both are provided."},{"name":"minArea","in":"query","required":false,"schema":{"type":"number","minimum":0},"description":"Minimum area in km2. Must be less than or equal to maxArea when both are provided."},{"name":"maxArea","in":"query","required":false,"schema":{"type":"number","minimum":0},"description":"Maximum area in km2. Must be greater than or equal to minArea when both are provided."},{"name":"minAltitude","in":"query","required":false,"schema":{"type":"number"},"description":"Minimum altitude in meters. Must be less than or equal to maxAltitude when both are provided."},{"name":"maxAltitude","in":"query","required":false,"schema":{"type":"number"},"description":"Maximum altitude in meters. Must be greater than or equal to minAltitude when both are provided."},{"name":"isCoastal","in":"query","required":false,"schema":{"anyOf":[{"type":"string","const":"true"},{"type":"string","const":"false"}]},"description":"Filter provinces by coastal status."},{"name":"isMetropolitan","in":"query","required":false,"schema":{"anyOf":[{"type":"string","const":"true"},{"type":"string","const":"false"}]},"description":"Filter provinces by metropolitan municipality status."}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string","minLength":1},"slug":{"type":"string","minLength":1},"population":{"type":"integer","minimum":0},"area":{"type":"object","required":["value","unit"],"properties":{"value":{"type":"number","minimum":0},"unit":{"type":"string","const":"km2"}},"additionalProperties":false},"altitude":{"type":"object","required":["value","unit"],"properties":{"value":{"type":"number"},"unit":{"type":"string","const":"m"}},"additionalProperties":false},"phoneAreaCodes":{"type":"array","items":{"type":"integer","minimum":1},"minItems":1},"isCoastal":{"type":"boolean"},"isMetropolitan":{"type":"boolean"},"region":{"type":"object","required":["tr","en"],"properties":{"tr":{"type":"string","minLength":1},"en":{"type":"string","minLength":1}},"additionalProperties":false},"coordinates":{"type":"object","required":["latitude","longitude"],"properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"additionalProperties":false},"stats":{"type":"object","required":["districtCount","municipalityCount","neighborhoodCount","villageCount"],"properties":{"districtCount":{"type":"integer","minimum":0},"municipalityCount":{"type":"integer","minimum":0},"neighborhoodCount":{"type":"integer","minimum":0},"villageCount":{"type":"integer","minimum":0}},"additionalProperties":false}}}},"meta":{"type":"object","required":["count","total","limit","offset","datasetVersion","lastUpdated"],"properties":{"count":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1},"offset":{"type":"integer","minimum":0},"datasetVersion":{"type":"string","minLength":1},"lastUpdated":{"type":"string","minLength":1}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Invalid request. Contradictory range filters return INVALID_RANGE_FILTER.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v2/provinces/{provinceId}":{"get":{"tags":["Provinces"],"summary":"Get province by id","parameters":[{"name":"provinceId","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"Filter by province id. Must match districtId and municipalityId hierarchy filters when provided."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Comma-separated field names to include in each response item."},{"name":"include","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Comma-separated related resources to embed in a detail response."}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string","minLength":1},"slug":{"type":"string","minLength":1},"population":{"type":"integer","minimum":0},"area":{"type":"object","required":["value","unit"],"properties":{"value":{"type":"number","minimum":0},"unit":{"type":"string","const":"km2"}},"additionalProperties":false},"altitude":{"type":"object","required":["value","unit"],"properties":{"value":{"type":"number"},"unit":{"type":"string","const":"m"}},"additionalProperties":false},"phoneAreaCodes":{"type":"array","items":{"type":"integer","minimum":1},"minItems":1},"isCoastal":{"type":"boolean"},"isMetropolitan":{"type":"boolean"},"region":{"type":"object","required":["tr","en"],"properties":{"tr":{"type":"string","minLength":1},"en":{"type":"string","minLength":1}},"additionalProperties":false},"coordinates":{"type":"object","required":["latitude","longitude"],"properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"additionalProperties":false},"stats":{"type":"object","required":["districtCount","municipalityCount","neighborhoodCount","villageCount"],"properties":{"districtCount":{"type":"integer","minimum":0},"municipalityCount":{"type":"integer","minimum":0},"neighborhoodCount":{"type":"integer","minimum":0},"villageCount":{"type":"integer","minimum":0}},"additionalProperties":false}},"additionalProperties":true},"meta":{"type":"object","required":["datasetVersion","lastUpdated"],"properties":{"datasetVersion":{"type":"string","minLength":1},"lastUpdated":{"type":"string","minLength":1}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v2/provinces/{provinceId}/districts":{"get":{"tags":["Provinces"],"summary":"List districts in a province","parameters":[{"name":"provinceId","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"Filter by province id. Must match districtId and municipalityId hierarchy filters when provided."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Comma-separated field names to include in each response item."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":100},"description":"Maximum number of items to return."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0},"description":"Zero-based item offset."}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string","minLength":1},"slug":{"type":"string","minLength":1},"provinceId":{"type":"integer","minimum":1},"population":{"type":"integer","minimum":0},"area":{"type":"object","required":["value","unit"],"properties":{"value":{"type":"number","minimum":0},"unit":{"type":"string","const":"km2"}},"additionalProperties":false},"stats":{"type":"object","required":["municipalityCount","neighborhoodCount","villageCount"],"properties":{"municipalityCount":{"type":"integer","minimum":0},"neighborhoodCount":{"type":"integer","minimum":0},"villageCount":{"type":"integer","minimum":0}},"additionalProperties":false}}}},"meta":{"type":"object","required":["count","total","limit","offset","datasetVersion","lastUpdated"],"properties":{"count":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1},"offset":{"type":"integer","minimum":0},"datasetVersion":{"type":"string","minLength":1},"lastUpdated":{"type":"string","minLength":1}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v2/provinces/{provinceId}/municipalities":{"get":{"tags":["Provinces"],"summary":"List municipalities in a province","parameters":[{"name":"provinceId","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"Filter by province id. Must match districtId and municipalityId hierarchy filters when provided."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Comma-separated field names to include in each response item."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":100},"description":"Maximum number of items to return."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0},"description":"Zero-based item offset."}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string","minLength":1},"slug":{"type":"string","minLength":1},"type":{"anyOf":[{"type":"string","const":"province_center"},{"type":"string","const":"district_center"},{"type":"string","const":"town"}]},"provinceId":{"type":"integer","minimum":1},"districtId":{"type":"integer","minimum":1},"population":{"type":"integer","minimum":0},"stats":{"type":"object","required":["neighborhoodCount"],"properties":{"neighborhoodCount":{"type":"integer","minimum":0}},"additionalProperties":false}}}},"meta":{"type":"object","required":["count","total","limit","offset","datasetVersion","lastUpdated"],"properties":{"count":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1},"offset":{"type":"integer","minimum":0},"datasetVersion":{"type":"string","minLength":1},"lastUpdated":{"type":"string","minLength":1}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v2/provinces/{provinceId}/neighborhoods":{"get":{"tags":["Provinces"],"summary":"List neighborhoods in a province","parameters":[{"name":"provinceId","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"Filter by province id. Must match districtId and municipalityId hierarchy filters when provided."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Comma-separated field names to include in each response item."},{"name":"postalCode","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9]{5}$"},"description":"Filter by exact five-digit postal code."},{"name":"postalCodePrefix","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9]{1,5}$"},"description":"Filter by one-to-five digit postal code prefix."},{"name":"postalCodeStatus","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Comma-separated postal code status filter."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":100},"description":"Maximum number of items to return."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0},"description":"Zero-based item offset."}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string","minLength":1},"slug":{"type":"string","minLength":1},"provinceId":{"type":"integer","minimum":1},"districtId":{"type":"integer","minimum":1},"municipalityId":{"type":"integer","minimum":1},"population":{"type":"integer","minimum":0},"postalCode":{"type":"string","pattern":"^[0-9]{5}$"},"postalCodeStatus":{"anyOf":[{"type":"string","const":"official"},{"type":"string","const":"derived"},{"type":"string","const":"estimated"}]}}}},"meta":{"type":"object","required":["count","total","limit","offset","datasetVersion","lastUpdated"],"properties":{"count":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1},"offset":{"type":"integer","minimum":0},"datasetVersion":{"type":"string","minLength":1},"lastUpdated":{"type":"string","minLength":1}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v2/provinces/{provinceId}/villages":{"get":{"tags":["Provinces"],"summary":"List villages in a province","parameters":[{"name":"provinceId","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"Filter by province id. Must match districtId and municipalityId hierarchy filters when provided."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Comma-separated field names to include in each response item."},{"name":"postalCode","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9]{5}$"},"description":"Filter by exact five-digit postal code."},{"name":"postalCodePrefix","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9]{1,5}$"},"description":"Filter by one-to-five digit postal code prefix."},{"name":"postalCodeStatus","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Comma-separated postal code status filter."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":100},"description":"Maximum number of items to return."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0},"description":"Zero-based item offset."}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string","minLength":1},"slug":{"type":"string","minLength":1},"provinceId":{"type":"integer","minimum":1},"districtId":{"type":"integer","minimum":1},"population":{"type":"integer","minimum":0},"postalCode":{"type":"string","pattern":"^[0-9]{5}$"},"postalCodeStatus":{"anyOf":[{"type":"string","const":"official"},{"type":"string","const":"estimated"}]}}}},"meta":{"type":"object","required":["count","total","limit","offset","datasetVersion","lastUpdated"],"properties":{"count":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1},"offset":{"type":"integer","minimum":0},"datasetVersion":{"type":"string","minLength":1},"lastUpdated":{"type":"string","minLength":1}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v2/districts":{"get":{"tags":["Districts"],"summary":"List districts","parameters":[{"name":"search","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Case-insensitive normalized text search by name."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Comma-separated field names to include in each response item."},{"name":"sort","in":"query","required":false,"schema":{"anyOf":[{"type":"string","const":"id"},{"type":"string","const":"-id"},{"type":"string","const":"name"},{"type":"string","const":"-name"},{"type":"string","const":"population"},{"type":"string","const":"-population"}]},"description":"Sort order for list responses."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":100},"description":"Maximum number of items to return."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0},"description":"Zero-based item offset."},{"name":"minPopulation","in":"query","required":false,"schema":{"type":"integer","minimum":0},"description":"Minimum population. Must be less than or equal to maxPopulation when both are provided."},{"name":"maxPopulation","in":"query","required":false,"schema":{"type":"integer","minimum":0},"description":"Maximum population. Must be greater than or equal to minPopulation when both are provided."},{"name":"minArea","in":"query","required":false,"schema":{"type":"number","minimum":0},"description":"Minimum area in km2. Must be less than or equal to maxArea when both are provided."},{"name":"maxArea","in":"query","required":false,"schema":{"type":"number","minimum":0},"description":"Maximum area in km2. Must be greater than or equal to minArea when both are provided."},{"name":"provinceId","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Filter by province id. Must match districtId and municipalityId hierarchy filters when provided."}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string","minLength":1},"slug":{"type":"string","minLength":1},"provinceId":{"type":"integer","minimum":1},"population":{"type":"integer","minimum":0},"area":{"type":"object","required":["value","unit"],"properties":{"value":{"type":"number","minimum":0},"unit":{"type":"string","const":"km2"}},"additionalProperties":false},"stats":{"type":"object","required":["municipalityCount","neighborhoodCount","villageCount"],"properties":{"municipalityCount":{"type":"integer","minimum":0},"neighborhoodCount":{"type":"integer","minimum":0},"villageCount":{"type":"integer","minimum":0}},"additionalProperties":false}}}},"meta":{"type":"object","required":["count","total","limit","offset","datasetVersion","lastUpdated"],"properties":{"count":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1},"offset":{"type":"integer","minimum":0},"datasetVersion":{"type":"string","minLength":1},"lastUpdated":{"type":"string","minLength":1}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Invalid request. Contradictory range filters return INVALID_RANGE_FILTER.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v2/districts/{districtId}":{"get":{"tags":["Districts"],"summary":"Get district by id","parameters":[{"name":"districtId","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"Filter by district id. Must match provinceId and municipalityId hierarchy filters when provided."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Comma-separated field names to include in each response item."},{"name":"include","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Comma-separated related resources to embed in a detail response."}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string","minLength":1},"slug":{"type":"string","minLength":1},"provinceId":{"type":"integer","minimum":1},"population":{"type":"integer","minimum":0},"area":{"type":"object","required":["value","unit"],"properties":{"value":{"type":"number","minimum":0},"unit":{"type":"string","const":"km2"}},"additionalProperties":false},"stats":{"type":"object","required":["municipalityCount","neighborhoodCount","villageCount"],"properties":{"municipalityCount":{"type":"integer","minimum":0},"neighborhoodCount":{"type":"integer","minimum":0},"villageCount":{"type":"integer","minimum":0}},"additionalProperties":false}},"additionalProperties":true},"meta":{"type":"object","required":["datasetVersion","lastUpdated"],"properties":{"datasetVersion":{"type":"string","minLength":1},"lastUpdated":{"type":"string","minLength":1}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v2/districts/{districtId}/municipalities":{"get":{"tags":["Districts"],"summary":"List municipalities in a district","parameters":[{"name":"districtId","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"Filter by district id. Must match provinceId and municipalityId hierarchy filters when provided."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Comma-separated field names to include in each response item."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":100},"description":"Maximum number of items to return."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0},"description":"Zero-based item offset."}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string","minLength":1},"slug":{"type":"string","minLength":1},"type":{"anyOf":[{"type":"string","const":"province_center"},{"type":"string","const":"district_center"},{"type":"string","const":"town"}]},"provinceId":{"type":"integer","minimum":1},"districtId":{"type":"integer","minimum":1},"population":{"type":"integer","minimum":0},"stats":{"type":"object","required":["neighborhoodCount"],"properties":{"neighborhoodCount":{"type":"integer","minimum":0}},"additionalProperties":false}}}},"meta":{"type":"object","required":["count","total","limit","offset","datasetVersion","lastUpdated"],"properties":{"count":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1},"offset":{"type":"integer","minimum":0},"datasetVersion":{"type":"string","minLength":1},"lastUpdated":{"type":"string","minLength":1}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v2/districts/{districtId}/neighborhoods":{"get":{"tags":["Districts"],"summary":"List neighborhoods in a district","parameters":[{"name":"districtId","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"Filter by district id. Must match provinceId and municipalityId hierarchy filters when provided."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Comma-separated field names to include in each response item."},{"name":"postalCode","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9]{5}$"},"description":"Filter by exact five-digit postal code."},{"name":"postalCodePrefix","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9]{1,5}$"},"description":"Filter by one-to-five digit postal code prefix."},{"name":"postalCodeStatus","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Comma-separated postal code status filter."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":100},"description":"Maximum number of items to return."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0},"description":"Zero-based item offset."}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string","minLength":1},"slug":{"type":"string","minLength":1},"provinceId":{"type":"integer","minimum":1},"districtId":{"type":"integer","minimum":1},"municipalityId":{"type":"integer","minimum":1},"population":{"type":"integer","minimum":0},"postalCode":{"type":"string","pattern":"^[0-9]{5}$"},"postalCodeStatus":{"anyOf":[{"type":"string","const":"official"},{"type":"string","const":"derived"},{"type":"string","const":"estimated"}]}}}},"meta":{"type":"object","required":["count","total","limit","offset","datasetVersion","lastUpdated"],"properties":{"count":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1},"offset":{"type":"integer","minimum":0},"datasetVersion":{"type":"string","minLength":1},"lastUpdated":{"type":"string","minLength":1}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v2/districts/{districtId}/villages":{"get":{"tags":["Districts"],"summary":"List villages in a district","parameters":[{"name":"districtId","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"Filter by district id. Must match provinceId and municipalityId hierarchy filters when provided."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Comma-separated field names to include in each response item."},{"name":"postalCode","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9]{5}$"},"description":"Filter by exact five-digit postal code."},{"name":"postalCodePrefix","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9]{1,5}$"},"description":"Filter by one-to-five digit postal code prefix."},{"name":"postalCodeStatus","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Comma-separated postal code status filter."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":100},"description":"Maximum number of items to return."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0},"description":"Zero-based item offset."}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string","minLength":1},"slug":{"type":"string","minLength":1},"provinceId":{"type":"integer","minimum":1},"districtId":{"type":"integer","minimum":1},"population":{"type":"integer","minimum":0},"postalCode":{"type":"string","pattern":"^[0-9]{5}$"},"postalCodeStatus":{"anyOf":[{"type":"string","const":"official"},{"type":"string","const":"estimated"}]}}}},"meta":{"type":"object","required":["count","total","limit","offset","datasetVersion","lastUpdated"],"properties":{"count":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1},"offset":{"type":"integer","minimum":0},"datasetVersion":{"type":"string","minLength":1},"lastUpdated":{"type":"string","minLength":1}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v2/municipalities":{"get":{"tags":["Municipalities"],"summary":"List municipalities","parameters":[{"name":"search","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Case-insensitive normalized text search by name."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Comma-separated field names to include in each response item."},{"name":"sort","in":"query","required":false,"schema":{"anyOf":[{"type":"string","const":"id"},{"type":"string","const":"-id"},{"type":"string","const":"name"},{"type":"string","const":"-name"},{"type":"string","const":"population"},{"type":"string","const":"-population"}]},"description":"Sort order for list responses."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":100},"description":"Maximum number of items to return."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0},"description":"Zero-based item offset."},{"name":"minPopulation","in":"query","required":false,"schema":{"type":"integer","minimum":0},"description":"Minimum population. Must be less than or equal to maxPopulation when both are provided."},{"name":"maxPopulation","in":"query","required":false,"schema":{"type":"integer","minimum":0},"description":"Maximum population. Must be greater than or equal to minPopulation when both are provided."},{"name":"provinceId","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Filter by province id. Must match districtId and municipalityId hierarchy filters when provided."},{"name":"districtId","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Filter by district id. Must match provinceId and municipalityId hierarchy filters when provided."},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"type":"string","const":"province_center"},{"type":"string","const":"district_center"},{"type":"string","const":"town"}]},"description":"Filter municipalities by municipality type."}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string","minLength":1},"slug":{"type":"string","minLength":1},"type":{"anyOf":[{"type":"string","const":"province_center"},{"type":"string","const":"district_center"},{"type":"string","const":"town"}]},"provinceId":{"type":"integer","minimum":1},"districtId":{"type":"integer","minimum":1},"population":{"type":"integer","minimum":0},"stats":{"type":"object","required":["neighborhoodCount"],"properties":{"neighborhoodCount":{"type":"integer","minimum":0}},"additionalProperties":false}}}},"meta":{"type":"object","required":["count","total","limit","offset","datasetVersion","lastUpdated"],"properties":{"count":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1},"offset":{"type":"integer","minimum":0},"datasetVersion":{"type":"string","minLength":1},"lastUpdated":{"type":"string","minLength":1}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Invalid request. Contradictory range filters return INVALID_RANGE_FILTER; contradictory hierarchy filters return INVALID_HIERARCHY_FILTER.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v2/municipalities/{municipalityId}":{"get":{"tags":["Municipalities"],"summary":"Get municipality by id","parameters":[{"name":"municipalityId","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"Filter by municipality id. Must match provinceId and districtId hierarchy filters when provided."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Comma-separated field names to include in each response item."},{"name":"include","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Comma-separated related resources to embed in a detail response."}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string","minLength":1},"slug":{"type":"string","minLength":1},"type":{"anyOf":[{"type":"string","const":"province_center"},{"type":"string","const":"district_center"},{"type":"string","const":"town"}]},"provinceId":{"type":"integer","minimum":1},"districtId":{"type":"integer","minimum":1},"population":{"type":"integer","minimum":0},"stats":{"type":"object","required":["neighborhoodCount"],"properties":{"neighborhoodCount":{"type":"integer","minimum":0}},"additionalProperties":false}},"additionalProperties":true},"meta":{"type":"object","required":["datasetVersion","lastUpdated"],"properties":{"datasetVersion":{"type":"string","minLength":1},"lastUpdated":{"type":"string","minLength":1}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v2/municipalities/{municipalityId}/neighborhoods":{"get":{"tags":["Municipalities"],"summary":"List neighborhoods in a municipality","parameters":[{"name":"municipalityId","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"Filter by municipality id. Must match provinceId and districtId hierarchy filters when provided."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Comma-separated field names to include in each response item."},{"name":"postalCode","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9]{5}$"},"description":"Filter by exact five-digit postal code."},{"name":"postalCodePrefix","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9]{1,5}$"},"description":"Filter by one-to-five digit postal code prefix."},{"name":"postalCodeStatus","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Comma-separated postal code status filter."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":100},"description":"Maximum number of items to return."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0},"description":"Zero-based item offset."}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string","minLength":1},"slug":{"type":"string","minLength":1},"provinceId":{"type":"integer","minimum":1},"districtId":{"type":"integer","minimum":1},"municipalityId":{"type":"integer","minimum":1},"population":{"type":"integer","minimum":0},"postalCode":{"type":"string","pattern":"^[0-9]{5}$"},"postalCodeStatus":{"anyOf":[{"type":"string","const":"official"},{"type":"string","const":"derived"},{"type":"string","const":"estimated"}]}}}},"meta":{"type":"object","required":["count","total","limit","offset","datasetVersion","lastUpdated"],"properties":{"count":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1},"offset":{"type":"integer","minimum":0},"datasetVersion":{"type":"string","minLength":1},"lastUpdated":{"type":"string","minLength":1}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v2/neighborhoods":{"get":{"tags":["Neighborhoods"],"summary":"List neighborhoods","parameters":[{"name":"search","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Case-insensitive normalized text search by name."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Comma-separated field names to include in each response item."},{"name":"sort","in":"query","required":false,"schema":{"anyOf":[{"type":"string","const":"id"},{"type":"string","const":"-id"},{"type":"string","const":"name"},{"type":"string","const":"-name"},{"type":"string","const":"population"},{"type":"string","const":"-population"}]},"description":"Sort order for list responses."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":100},"description":"Maximum number of items to return."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0},"description":"Zero-based item offset."},{"name":"minPopulation","in":"query","required":false,"schema":{"type":"integer","minimum":0},"description":"Minimum population. Must be less than or equal to maxPopulation when both are provided."},{"name":"maxPopulation","in":"query","required":false,"schema":{"type":"integer","minimum":0},"description":"Maximum population. Must be greater than or equal to minPopulation when both are provided."},{"name":"provinceId","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Filter by province id. Must match districtId and municipalityId hierarchy filters when provided."},{"name":"districtId","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Filter by district id. Must match provinceId and municipalityId hierarchy filters when provided."},{"name":"municipalityId","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Filter by municipality id. Must match provinceId and districtId hierarchy filters when provided."},{"name":"postalCode","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9]{5}$"},"description":"Filter by exact five-digit postal code."},{"name":"postalCodePrefix","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9]{1,5}$"},"description":"Filter by one-to-five digit postal code prefix."},{"name":"postalCodeStatus","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Comma-separated postal code status filter."}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string","minLength":1},"slug":{"type":"string","minLength":1},"provinceId":{"type":"integer","minimum":1},"districtId":{"type":"integer","minimum":1},"municipalityId":{"type":"integer","minimum":1},"population":{"type":"integer","minimum":0},"postalCode":{"type":"string","pattern":"^[0-9]{5}$"},"postalCodeStatus":{"anyOf":[{"type":"string","const":"official"},{"type":"string","const":"derived"},{"type":"string","const":"estimated"}]}}}},"meta":{"type":"object","required":["count","total","limit","offset","datasetVersion","lastUpdated"],"properties":{"count":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1},"offset":{"type":"integer","minimum":0},"datasetVersion":{"type":"string","minLength":1},"lastUpdated":{"type":"string","minLength":1}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Invalid request. Contradictory range filters return INVALID_RANGE_FILTER; contradictory hierarchy filters return INVALID_HIERARCHY_FILTER.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v2/neighborhoods/{neighborhoodId}":{"get":{"tags":["Neighborhoods"],"summary":"Get neighborhood by id","parameters":[{"name":"neighborhoodId","in":"path","required":true,"schema":{"type":"integer","minimum":1}},{"name":"fields","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Comma-separated field names to include in each response item."},{"name":"include","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Comma-separated related resources to embed in a detail response."}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string","minLength":1},"slug":{"type":"string","minLength":1},"provinceId":{"type":"integer","minimum":1},"districtId":{"type":"integer","minimum":1},"municipalityId":{"type":"integer","minimum":1},"population":{"type":"integer","minimum":0},"postalCode":{"type":"string","pattern":"^[0-9]{5}$"},"postalCodeStatus":{"anyOf":[{"type":"string","const":"official"},{"type":"string","const":"derived"},{"type":"string","const":"estimated"}]}},"additionalProperties":true},"meta":{"type":"object","required":["datasetVersion","lastUpdated"],"properties":{"datasetVersion":{"type":"string","minLength":1},"lastUpdated":{"type":"string","minLength":1}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v2/villages":{"get":{"tags":["Villages"],"summary":"List villages","parameters":[{"name":"search","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Case-insensitive normalized text search by name."},{"name":"fields","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Comma-separated field names to include in each response item."},{"name":"sort","in":"query","required":false,"schema":{"anyOf":[{"type":"string","const":"id"},{"type":"string","const":"-id"},{"type":"string","const":"name"},{"type":"string","const":"-name"},{"type":"string","const":"population"},{"type":"string","const":"-population"}]},"description":"Sort order for list responses."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":100},"description":"Maximum number of items to return."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0},"description":"Zero-based item offset."},{"name":"minPopulation","in":"query","required":false,"schema":{"type":"integer","minimum":0},"description":"Minimum population. Must be less than or equal to maxPopulation when both are provided."},{"name":"maxPopulation","in":"query","required":false,"schema":{"type":"integer","minimum":0},"description":"Maximum population. Must be greater than or equal to minPopulation when both are provided."},{"name":"provinceId","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Filter by province id. Must match districtId and municipalityId hierarchy filters when provided."},{"name":"districtId","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Filter by district id. Must match provinceId and municipalityId hierarchy filters when provided."},{"name":"postalCode","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9]{5}$"},"description":"Filter by exact five-digit postal code."},{"name":"postalCodePrefix","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9]{1,5}$"},"description":"Filter by one-to-five digit postal code prefix."},{"name":"postalCodeStatus","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Comma-separated postal code status filter."}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string","minLength":1},"slug":{"type":"string","minLength":1},"provinceId":{"type":"integer","minimum":1},"districtId":{"type":"integer","minimum":1},"population":{"type":"integer","minimum":0},"postalCode":{"type":"string","pattern":"^[0-9]{5}$"},"postalCodeStatus":{"anyOf":[{"type":"string","const":"official"},{"type":"string","const":"estimated"}]}}}},"meta":{"type":"object","required":["count","total","limit","offset","datasetVersion","lastUpdated"],"properties":{"count":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1},"offset":{"type":"integer","minimum":0},"datasetVersion":{"type":"string","minLength":1},"lastUpdated":{"type":"string","minLength":1}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Invalid request. Contradictory range filters return INVALID_RANGE_FILTER; contradictory hierarchy filters return INVALID_HIERARCHY_FILTER.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}}}}},"/v2/villages/{villageId}":{"get":{"tags":["Villages"],"summary":"Get village by id","parameters":[{"name":"villageId","in":"path","required":true,"schema":{"type":"integer","minimum":1}},{"name":"fields","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Comma-separated field names to include in each response item."},{"name":"include","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Comma-separated related resources to embed in a detail response."}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string","minLength":1},"slug":{"type":"string","minLength":1},"provinceId":{"type":"integer","minimum":1},"districtId":{"type":"integer","minimum":1},"population":{"type":"integer","minimum":0},"postalCode":{"type":"string","pattern":"^[0-9]{5}$"},"postalCodeStatus":{"anyOf":[{"type":"string","const":"official"},{"type":"string","const":"estimated"}]}},"additionalProperties":true},"meta":{"type":"object","required":["datasetVersion","lastUpdated"],"properties":{"datasetVersion":{"type":"string","minLength":1},"lastUpdated":{"type":"string","minLength":1}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false}}}}}}}},"components":{"schemas":{"Province":{"type":"object","required":["id","name","slug","population","area","altitude","phoneAreaCodes","isCoastal","isMetropolitan","region","coordinates","stats"],"properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string","minLength":1},"slug":{"type":"string","minLength":1},"population":{"type":"integer","minimum":0},"area":{"type":"object","required":["value","unit"],"properties":{"value":{"type":"number","minimum":0},"unit":{"type":"string","const":"km2"}},"additionalProperties":false},"altitude":{"type":"object","required":["value","unit"],"properties":{"value":{"type":"number"},"unit":{"type":"string","const":"m"}},"additionalProperties":false},"phoneAreaCodes":{"type":"array","items":{"type":"integer","minimum":1},"minItems":1},"isCoastal":{"type":"boolean"},"isMetropolitan":{"type":"boolean"},"region":{"type":"object","required":["tr","en"],"properties":{"tr":{"type":"string","minLength":1},"en":{"type":"string","minLength":1}},"additionalProperties":false},"coordinates":{"type":"object","required":["latitude","longitude"],"properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"additionalProperties":false},"stats":{"type":"object","required":["districtCount","municipalityCount","neighborhoodCount","villageCount"],"properties":{"districtCount":{"type":"integer","minimum":0},"municipalityCount":{"type":"integer","minimum":0},"neighborhoodCount":{"type":"integer","minimum":0},"villageCount":{"type":"integer","minimum":0}},"additionalProperties":false}},"additionalProperties":false},"District":{"type":"object","required":["id","name","slug","provinceId","population","area","stats"],"properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string","minLength":1},"slug":{"type":"string","minLength":1},"provinceId":{"type":"integer","minimum":1},"population":{"type":"integer","minimum":0},"area":{"type":"object","required":["value","unit"],"properties":{"value":{"type":"number","minimum":0},"unit":{"type":"string","const":"km2"}},"additionalProperties":false},"stats":{"type":"object","required":["municipalityCount","neighborhoodCount","villageCount"],"properties":{"municipalityCount":{"type":"integer","minimum":0},"neighborhoodCount":{"type":"integer","minimum":0},"villageCount":{"type":"integer","minimum":0}},"additionalProperties":false}},"additionalProperties":false},"Municipality":{"type":"object","required":["id","name","slug","type","provinceId","districtId","population","stats"],"properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string","minLength":1},"slug":{"type":"string","minLength":1},"type":{"anyOf":[{"type":"string","const":"province_center"},{"type":"string","const":"district_center"},{"type":"string","const":"town"}]},"provinceId":{"type":"integer","minimum":1},"districtId":{"type":"integer","minimum":1},"population":{"type":"integer","minimum":0},"stats":{"type":"object","required":["neighborhoodCount"],"properties":{"neighborhoodCount":{"type":"integer","minimum":0}},"additionalProperties":false}},"additionalProperties":false},"Neighborhood":{"type":"object","required":["id","name","slug","provinceId","districtId","municipalityId","population","postalCode","postalCodeStatus"],"properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string","minLength":1},"slug":{"type":"string","minLength":1},"provinceId":{"type":"integer","minimum":1},"districtId":{"type":"integer","minimum":1},"municipalityId":{"type":"integer","minimum":1},"population":{"type":"integer","minimum":0},"postalCode":{"type":"string","pattern":"^[0-9]{5}$"},"postalCodeStatus":{"anyOf":[{"type":"string","const":"official"},{"type":"string","const":"derived"},{"type":"string","const":"estimated"}]}},"additionalProperties":false},"Village":{"type":"object","required":["id","name","slug","provinceId","districtId","population","postalCode","postalCodeStatus"],"properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string","minLength":1},"slug":{"type":"string","minLength":1},"provinceId":{"type":"integer","minimum":1},"districtId":{"type":"integer","minimum":1},"population":{"type":"integer","minimum":0},"postalCode":{"type":"string","pattern":"^[0-9]{5}$"},"postalCodeStatus":{"anyOf":[{"type":"string","const":"official"},{"type":"string","const":"estimated"}]}},"additionalProperties":false},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599}},"additionalProperties":false}},"additionalProperties":false},"Meta":{"type":"object","required":["apiVersion","datasetVersion","lastUpdated","sources","counts"],"properties":{"apiVersion":{"type":"string","minLength":1},"datasetVersion":{"type":"string","minLength":1},"lastUpdated":{"type":"string","minLength":1},"sources":{"type":"array","items":{"type":"object","required":["name","url","description"],"properties":{"name":{"type":"string","minLength":1},"url":{"type":"string","minLength":1},"description":{"type":"object","required":["tr","en"],"properties":{"tr":{"type":"string","minLength":1},"en":{"type":"string","minLength":1}}}},"additionalProperties":false}},"counts":{"type":"object","required":["provinces","districts","municipalities","neighborhoods","villages"],"properties":{"provinces":{"type":"integer","minimum":0},"districts":{"type":"integer","minimum":0},"municipalities":{"type":"integer","minimum":0},"neighborhoods":{"type":"integer","minimum":0},"villages":{"type":"integer","minimum":0}},"additionalProperties":false}},"additionalProperties":false}}}}