{"openapi":"3.1.0","info":{"title":"Peta Kuesus API","version":"1.0.0","description":"Public API for Indonesian administrative region data, search, boundaries, and spatial queries."},"servers":[{"url":"https://peta.kues.us/api/v1","description":"Region data endpoints"},{"url":"https://api.peta.kues.us","description":"Search, boundary, and spatial endpoints"}],"tags":[{"name":"Metadata"},{"name":"Region Data"},{"name":"Autocomplete"},{"name":"Search"},{"name":"Region Details"},{"name":"Boundaries"},{"name":"Spatial Queries"}],"paths":{"/meta.json":{"get":{"tags":["Metadata"],"servers":[{"url":"https://peta.kues.us/api/v1","description":"Region data endpoints"}],"summary":"Get dataset metadata","responses":{"200":{"description":"Dataset metadata","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/provinces.json":{"get":{"tags":["Region Data"],"servers":[{"url":"https://peta.kues.us/api/v1","description":"Region data endpoints"}],"summary":"List provinces","responses":{"200":{"description":"All provinces","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["code","name","latitude","longitude","boundary"],"properties":{"code":{"type":"string"},"name":{"type":"string"},"province_code":{"type":"string"},"regency_code":{"type":"string"},"district_code":{"type":"string"},"postal_code":{"type":["string","null"]},"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]},"boundary":{"type":"object","required":["available"],"properties":{"available":{"type":"boolean"},"source":{"type":"string","enum":["cahyadsn/wilayah_boundaries"]},"reason":{"type":"string"}}}}}}}}}}}},"/regencies/by-province/{province_code}.json":{"get":{"tags":["Region Data"],"servers":[{"url":"https://peta.kues.us/api/v1","description":"Region data endpoints"}],"summary":"List regencies by province","parameters":[{"name":"province_code","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Regencies in a province","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["code","name","latitude","longitude","boundary"],"properties":{"code":{"type":"string"},"name":{"type":"string"},"province_code":{"type":"string"},"regency_code":{"type":"string"},"district_code":{"type":"string"},"postal_code":{"type":["string","null"]},"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]},"boundary":{"type":"object","required":["available"],"properties":{"available":{"type":"boolean"},"source":{"type":"string","enum":["cahyadsn/wilayah_boundaries"]},"reason":{"type":"string"}}}}}}}}}}}},"/districts/by-regency/{regency_code}.json":{"get":{"tags":["Region Data"],"servers":[{"url":"https://peta.kues.us/api/v1","description":"Region data endpoints"}],"summary":"List districts by regency","parameters":[{"name":"regency_code","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Districts in a regency","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["code","name","latitude","longitude","boundary"],"properties":{"code":{"type":"string"},"name":{"type":"string"},"province_code":{"type":"string"},"regency_code":{"type":"string"},"district_code":{"type":"string"},"postal_code":{"type":["string","null"]},"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]},"boundary":{"type":"object","required":["available"],"properties":{"available":{"type":"boolean"},"source":{"type":"string","enum":["cahyadsn/wilayah_boundaries"]},"reason":{"type":"string"}}}}}}}}}}}},"/villages/by-district/{district_code}.json":{"get":{"tags":["Region Data"],"servers":[{"url":"https://peta.kues.us/api/v1","description":"Region data endpoints"}],"summary":"List villages by district","parameters":[{"name":"district_code","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Villages in a district","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["code","name","latitude","longitude","boundary"],"properties":{"code":{"type":"string"},"name":{"type":"string"},"province_code":{"type":"string"},"regency_code":{"type":"string"},"district_code":{"type":"string"},"postal_code":{"type":["string","null"]},"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]},"boundary":{"type":"object","required":["available"],"properties":{"available":{"type":"boolean"},"source":{"type":"string","enum":["cahyadsn/wilayah_boundaries"]},"reason":{"type":"string"}}}}}}}}}}}},"/search":{"get":{"tags":["Search"],"servers":[{"url":"https://api.peta.kues.us","description":"Search, boundary, and spatial endpoints"}],"summary":"Search regions","parameters":[{"name":"q","in":"query","required":true,"description":"Search text, code, compact code, or postal-code signal","schema":{"type":"string","minLength":2}},{"name":"limit","in":"query","required":false,"description":"Maximum results","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"level","in":"query","required":false,"description":"Optional region level filter","schema":{"type":"string","enum":["province","regency","district","village"]}},{"name":"province_code","in":"query","required":false,"description":"Optional province code filter","schema":{"type":"string"}},{"name":"regency_code","in":"query","required":false,"description":"Optional regency code filter","schema":{"type":"string"}},{"name":"district_code","in":"query","required":false,"description":"Optional district code filter","schema":{"type":"string"}},{"name":"boundary_available","in":"query","required":false,"description":"Optional boundary availability filter","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Matching regions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"description":"Invalid search query or filter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Search unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/autocomplete":{"get":{"tags":["Autocomplete"],"servers":[{"url":"https://api.peta.kues.us","description":"Search, boundary, and spatial endpoints"}],"summary":"Autocomplete Indonesian regions for forms","description":"Compact autocomplete for Indonesian provinces, regencies, districts, villages, and postal codes. Designed for address forms, checkout pages, CRM apps, logistics forms, and internal systems.","parameters":[{"name":"q","in":"query","required":true,"description":"Search text, region code, compact code, or postal code","schema":{"type":"string","minLength":2,"maxLength":100}},{"name":"limit","in":"query","required":false,"description":"Maximum suggestions","schema":{"type":"integer","minimum":1,"maximum":20,"default":10}}],"responses":{"200":{"description":"Autocomplete suggestions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutocompleteResponse"}}}},"400":{"description":"Invalid autocomplete query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Autocomplete unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/regions/{code}":{"get":{"tags":["Region Details"],"servers":[{"url":"https://api.peta.kues.us","description":"Search, boundary, and spatial endpoints"}],"summary":"Get region by code","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Region detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Region"}}}}}},"400":{"description":"Invalid code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Region not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/regions/{code}/children":{"get":{"tags":["Region Details"],"servers":[{"url":"https://api.peta.kues.us","description":"Search, boundary, and spatial endpoints"}],"summary":"List direct child regions","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Maximum child regions","schema":{"type":"integer","minimum":1,"maximum":500}},{"name":"offset","in":"query","required":false,"description":"Pagination offset","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Child regions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChildrenResponse"}}}},"400":{"description":"Invalid code or pagination parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Parent region not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/regions/{code}/ancestors":{"get":{"tags":["Region Details"],"servers":[{"url":"https://api.peta.kues.us","description":"Search, boundary, and spatial endpoints"}],"summary":"List ancestor regions","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ancestor chain","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Region"}}}}}}},"400":{"description":"Invalid code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Region not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/regions/{code}/boundary":{"get":{"tags":["Boundaries"],"servers":[{"url":"https://api.peta.kues.us","description":"Search, boundary, and spatial endpoints"}],"summary":"Get boundary GeoJSON","description":"Download one selected region as a GeoJSON Feature when boundary data is available.","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}},{"name":"simplify","in":"query","required":false,"description":"Whether to simplify the geometry","schema":{"type":"boolean"}},{"name":"tolerance","in":"query","required":false,"description":"Simplification tolerance","schema":{"type":"number","minimum":0}}],"responses":{"200":{"description":"GeoJSON Feature boundary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoJsonFeature"}}}},"400":{"description":"Invalid code or boundary parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Boundary not available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/boundaries":{"post":{"tags":["Boundaries"],"servers":[{"url":"https://api.peta.kues.us","description":"Search, boundary, and spatial endpoints"}],"summary":"Export selected boundaries as GeoJSON","description":"Return a GeoJSON FeatureCollection for selected regions. Parent regions are exported exactly by default; expansion to regencies/cities, districts, or villages must be requested explicitly.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoundaryExportRequest"},"examples":{"selectedOnly":{"summary":"Selected regions only","value":{"codes":["21.03.19.2002","33.27"],"scope":"selected","simplify":false}},"expandDistricts":{"summary":"Expand parent regions to districts","value":{"codes":["33.27"],"scope":"districts","simplify":false}}}}}},"responses":{"200":{"description":"GeoJSON FeatureCollection boundary export","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoJsonFeatureCollection"}}}},"400":{"description":"Invalid request, code, or scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Export output is too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/spatial/reverse":{"get":{"tags":["Spatial Queries"],"servers":[{"url":"https://api.peta.kues.us","description":"Search, boundary, and spatial endpoints"}],"summary":"Find regions containing a point","parameters":[{"name":"lat","in":"query","required":true,"description":"Latitude","schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"lng","in":"query","required":true,"description":"Longitude","schema":{"type":"number","minimum":-180,"maximum":180}}],"responses":{"200":{"description":"Containing regions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReverseSpatialResponse"}}}},"400":{"description":"Invalid coordinates","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/spatial/contains":{"get":{"tags":["Spatial Queries"],"servers":[{"url":"https://api.peta.kues.us","description":"Search, boundary, and spatial endpoints"}],"summary":"Check whether one region contains a point","parameters":[{"name":"code","in":"query","required":true,"description":"Region code","schema":{"type":"string"}},{"name":"lat","in":"query","required":true,"description":"Latitude","schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"lng","in":"query","required":true,"description":"Longitude","schema":{"type":"number","minimum":-180,"maximum":180}}],"responses":{"200":{"description":"Containment result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContainsSpatialResponse"}}}},"400":{"description":"Invalid code or coordinates","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Boundary not available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"Region":{"type":"object","properties":{"level":{"type":"string","enum":["province","regency","district","village"]},"code":{"type":"string"},"code_plain":{"type":"string"},"name":{"type":"string"},"parent_path":{"type":"string"},"province_code":{"type":"string"},"regency_code":{"type":"string"},"district_code":{"type":"string"},"postal_code":{"type":["string","null"]},"boundary":{"type":"object","properties":{"available":{"type":"boolean"}}},"bbox":{"type":["array","null"],"minItems":4,"maxItems":4,"items":{"type":"number"}}}},"SearchResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Region"}},"meta":{"type":"object","properties":{"query":{"type":"string"},"limit":{"type":"integer"},"count":{"type":"integer"}}}}},"AutocompleteResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AutocompleteItem"}},"meta":{"type":"object","properties":{"query":{"type":"string"},"limit":{"type":"integer"},"count":{"type":"integer"}}}}},"AutocompleteItem":{"type":"object","properties":{"label":{"type":"string","example":"Banyumudal, Moga, Pemalang, Jawa Tengah"},"level":{"type":"string","enum":["province","regency","district","village"]},"code":{"type":"string","example":"33.27.07.2006"},"name":{"type":"string","example":"Banyumudal"},"postal_code":{"type":["string","null"],"example":"52354"},"components":{"type":"object","properties":{"province":{"$ref":"#/components/schemas/AutocompleteComponent"},"regency":{"$ref":"#/components/schemas/AutocompleteComponent"},"district":{"$ref":"#/components/schemas/AutocompleteComponent"},"village":{"$ref":"#/components/schemas/AutocompleteComponent"}}},"boundary":{"type":"object","properties":{"available":{"type":"boolean"}}}}},"AutocompleteComponent":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}}},"ChildrenResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Region"}},"meta":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"count":{"type":"integer"}}}}},"GeoJsonFeature":{"type":"object","required":["type","properties","geometry"],"properties":{"type":{"type":"string","const":"Feature"},"properties":{"type":"object"},"geometry":{"type":"object","properties":{"type":{"type":"string","enum":["Polygon","MultiPolygon"]},"coordinates":{"type":"array"}}}}},"GeoJsonFeatureCollection":{"type":"object","required":["type","features","metadata"],"properties":{"type":{"type":"string","const":"FeatureCollection"},"name":{"type":"string","example":"Peta Kuesus selected regions"},"features":{"type":"array","items":{"$ref":"#/components/schemas/GeoJsonFeature"}},"metadata":{"$ref":"#/components/schemas/BoundaryExportMetadata"}}},"BoundaryExportRequest":{"type":"object","required":["codes"],"properties":{"codes":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string"}},"scope":{"type":"string","enum":["selected","regencies","districts","villages"],"default":"selected"},"simplify":{"type":"boolean","default":false},"tolerance":{"type":"number","minimum":0,"maximum":1,"default":0.001}}},"BoundaryExportMetadata":{"type":"object","properties":{"generated_by":{"type":"string","example":"Peta Kuesus"},"selected_count":{"type":"integer"},"expanded_count":{"type":"integer"},"output_feature_count":{"type":"integer"},"downloaded_count":{"type":"integer"},"missing_boundary_count":{"type":"integer"},"expansion_scope":{"type":"string","enum":["selected","regencies","districts","villages"]},"missing_boundaries":{"type":"array","items":{"$ref":"#/components/schemas/Region"}}}},"ReverseSpatialResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"point":{"$ref":"#/components/schemas/Point"},"matches":{"type":"array","items":{"$ref":"#/components/schemas/Region"}}}}}},"ContainsSpatialResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"contains":{"type":"boolean"},"region":{"$ref":"#/components/schemas/Region"}}}}},"Point":{"type":"object","properties":{"lat":{"type":"number"},"lng":{"type":"number"}}},"LevelCounts":{"type":"object","properties":{"province":{"type":"integer","example":38},"regency":{"type":"integer","example":514},"district":{"type":"integer","example":7285},"village":{"type":"integer","example":83762}}}}}}