{"openapi":"3.1.0","info":{"title":"WaterMap Public API","version":"16.0.0","description":"WaterMap 웹·지도·향후 모바일 앱이 공유하는 읽기 전용 공개 카탈로그 API입니다. directory 등급은 추가 공식 검증 전까지 검색엔진 색인에서 제외될 수 있으며, 가격·시즌·운영 상태는 예약 전 공식 원문에서 재확인해야 합니다.","license":{"name":"WaterMap API terms — source attribution remains required"}},"servers":[{"url":"https://watermap-self.vercel.app","description":"Production"}],"tags":[{"name":"Places","description":"운영사·자연 장소 검색과 상세 정보"},{"name":"Map","description":"지도 클라이언트용 축약 데이터"},{"name":"Coverage","description":"ISO 3166-1 조사·검증 현황"}],"paths":{"/api/v1/places":{"get":{"tags":["Places"],"operationId":"listPlaces","summary":"장소·운영사 검색","description":"다국어 검색, 국가, 액티비티, 해양동물, 만남 방식, 월, 공개 가격, 장소 종류와 프로필 검증 등급을 조합해 페이지 단위로 조회합니다.","parameters":[{"name":"q","in":"query","description":"업체·지역·상품·가격·한영 동의어 검색어","schema":{"type":"string","maxLength":120}},{"name":"country","in":"query","description":"WaterMap countrySlug","schema":{"type":"string","maxLength":80}},{"name":"iso","in":"query","description":"ISO 3166-1 alpha-2","schema":{"type":"string","minLength":2,"maxLength":2,"example":"JP"}},{"name":"region","in":"query","description":"WaterMap regionSlug","schema":{"type":"string","maxLength":100}},{"name":"activity","in":"query","description":"액티비티 별칭 또는 한국어 라벨","schema":{"type":"string","enum":["all","diving","freediving","scuba-diving","snorkeling","swimming","beach","boat","paddle","liveaboard","marine-life","surfing","family","전체","다이빙","프리다이빙","스쿠버다이빙","스노클링","수영","해변·물놀이","호핑·보트","카약·패들","리브어보드","해양 동물","서핑·SUP","가족·어린이"]}},{"name":"animal","in":"query","description":"해양동물 라벨. 같은 키를 반복하거나 쉼표로 구분하면 OR 조건으로 조회합니다.","style":"form","explode":true,"schema":{"type":"array","maxItems":12,"items":{"type":"string","maxLength":80},"example":["혹등고래","돌고래"]}},{"name":"encounter","in":"query","description":"Ocean Safari·관찰·입수 방식 별칭","schema":{"type":"string","enum":["ocean-safari","watching","boat-watching","land-watching","snorkeling","swimming","freediving","scuba-diving","Ocean Safari","선상 관찰","육상 관찰","스노클링","수영","프리다이빙","스쿠버다이빙"]}},{"name":"month","in":"query","description":"1–12, 여러 달은 쉼표로 구분","schema":{"type":"string","pattern":"^(?:[1-9]|1[0-2])(?:,(?:[1-9]|1[0-2]))*$"},"example":"1,2,3"},{"name":"liveaboard","in":"query","schema":{"type":"boolean"}},{"name":"kind","in":"query","schema":{"type":"string","enum":["operator","place"]}},{"name":"published_price","in":"query","schema":{"type":"boolean"}},{"name":"profile_tier","in":"query","description":"프로필 검증 등급","schema":{"type":"string","enum":["complete","verified","directory"]}},{"name":"beginner","in":"query","description":"초보자 적합 장소만 조회","schema":{"type":"boolean"}},{"name":"kids","in":"query","description":"가족·어린이 적합 장소만 조회","schema":{"type":"boolean"}},{"name":"korean","in":"query","description":"한국어 지원 운영사만 조회","schema":{"type":"boolean"}},{"name":"official","in":"query","description":"공식·정부·공식 관광·복수 출처 검증 장소만 조회","schema":{"type":"boolean"}},{"name":"website","in":"query","description":"운영사가 직접 관리하는 공식 웹사이트가 등록된 장소만 조회합니다. 지도·디렉터리·예약 플랫폼·SNS 링크는 제외합니다.","schema":{"type":"boolean"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":24}}],"responses":{"200":{"description":"성공","headers":{"X-WaterMap-API-Version":{"description":"응답 데이터 계약 버전","schema":{"type":"integer","example":16}}},"content":{"application/json":{"schema":{"type":"object","required":["apiVersion","generatedAt","filters","pagination","links","facets","places"],"properties":{"apiVersion":{"type":"integer","example":16},"generatedAt":{"type":"string","format":"date"},"filters":{"type":"object","additionalProperties":true},"pagination":{"type":"object","required":["page","limit","total","totalPages","hasNextPage"],"properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"},"hasNextPage":{"type":"boolean"}}},"links":{"type":"object","additionalProperties":{"type":["string","null"],"format":"uri"}},"facets":{"type":"object","additionalProperties":true},"places":{"type":"array","items":{"$ref":"#/components/schemas/PlaceRecord"}}}}}}},"400":{"description":"잘못된 필터","headers":{"X-WaterMap-API-Version":{"description":"응답 데이터 계약 버전","schema":{"type":"integer","example":16}}},"content":{"application/json":{"schema":{"type":"object","required":["apiVersion","error"],"properties":{"apiVersion":{"type":"integer","example":16},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"received":{"type":["string","null"]}}}}}}}}}}},"/api/v1/places/{country}/{region}/{slug}":{"get":{"tags":["Places"],"operationId":"getPlace","summary":"장소·운영사 상세","parameters":[{"name":"country","in":"path","required":true,"schema":{"type":"string"}},{"name":"region","in":"path","required":true,"schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"성공","headers":{"X-WaterMap-API-Version":{"description":"응답 데이터 계약 버전","schema":{"type":"integer","example":16}}},"content":{"application/json":{"schema":{"type":"object","required":["apiVersion","generatedAt","canonical","place"],"properties":{"apiVersion":{"type":"integer"},"generatedAt":{"type":"string","format":"date"},"canonical":{"type":"string","format":"uri-reference"},"place":{"$ref":"#/components/schemas/PlaceRecord"}}}}}},"404":{"description":"장소를 찾을 수 없음","headers":{"X-WaterMap-API-Version":{"description":"응답 데이터 계약 버전","schema":{"type":"integer","example":16}}},"content":{"application/json":{"schema":{"type":"object","required":["apiVersion","error"],"properties":{"apiVersion":{"type":"integer","example":16},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"received":{"type":["string","null"]}}}}}}}}}}},"/api/v1/map":{"get":{"tags":["Map"],"operationId":"getMapCatalog","summary":"모바일 지도용 core wire 카탈로그","description":"초기 지도 다운로드를 줄이기 위해 문자열 풀(strings)과 인덱스 tuple(places)로 반환합니다. tuple 해석은 MapCoreRow 스키마를 따르며, 자유문 검색은 /api/v1/map/search를 필요할 때만 불러옵니다. 전체 객체 형식은 이전 호환용 /api/v1/map/full을 사용하세요.","responses":{"200":{"description":"성공","headers":{"X-WaterMap-API-Version":{"description":"응답 데이터 계약 버전","schema":{"type":"integer","example":16}},"X-WaterMap-Map-Format":{"description":"지도 응답의 wire format 식별자","schema":{"type":"string","example":"watermap-map-core-v1"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MapCorePayload"}}}}}}},"/api/v1/map/search":{"get":{"tags":["Map"],"operationId":"getMapSearchIndex","summary":"지도 자유문 검색 색인","description":"/api/v1/map의 places와 같은 순서로 정렬된 다국어 검색 문자열입니다. 검색어가 있을 때만 지연 로드하세요.","responses":{"200":{"description":"성공","headers":{"X-WaterMap-API-Version":{"description":"응답 데이터 계약 버전","schema":{"type":"integer","example":16}},"X-WaterMap-Map-Format":{"description":"지도 응답의 wire format 식별자","schema":{"type":"string","example":"watermap-map-search-v2"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MapSearchPayload"}}}}}}},"/api/v1/map/full":{"get":{"deprecated":true,"tags":["Map"],"operationId":"getLegacyFullMapCatalog","summary":"이전 호환용 전체 지도 객체","description":"기존 클라이언트를 위한 이전 호환 경로입니다. 신규 모바일·웹 클라이언트는 /api/v1/map과 /api/v1/map/search를 사용하세요.","responses":{"200":{"description":"성공","headers":{"X-WaterMap-API-Version":{"description":"응답 데이터 계약 버전","schema":{"type":"integer","example":16}}},"content":{"application/json":{"schema":{"type":"object","required":["apiVersion","generatedAt","count","places"],"properties":{"apiVersion":{"type":"integer"},"generatedAt":{"type":"string","format":"date"},"count":{"type":"integer"},"places":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}}}}},"/api/v1/coverage":{"get":{"tags":["Coverage"],"operationId":"getCoverage","summary":"국가·영토 조사 현황","description":"ISO 3166-1 단위별 등록·조사 대기·내륙 후보·안전 보류·제외 상태와, 모바일·웹이 공유하는 운영사 필드 충족률을 반환합니다. registered는 국가 전수조사 완료를 뜻하지 않습니다.","responses":{"200":{"description":"성공","headers":{"X-WaterMap-API-Version":{"description":"응답 데이터 계약 버전","schema":{"type":"integer","example":16}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CoverageResponse"}}}}}}}},"components":{"schemas":{"PlaceRecord":{"type":"object","required":["id","href","name","location","classification","placeKind","profileQuality","season","price","contact"],"properties":{"id":{"type":"string","description":"country/region/slug로 구성된 안정적인 WaterMap ID"},"href":{"type":"string","format":"uri-reference"},"name":{"type":"string"},"localName":{"type":["string","null"]},"location":{"type":"object","required":["country","countrySlug","countryDisplayName","region","regionSlug","latitude","longitude"],"properties":{"country":{"type":"string"},"countrySlug":{"type":"string"},"countryDisplayName":{"type":"string"},"isoAlpha2":{"type":["string","null"],"minLength":2,"maxLength":2},"sovereignParent":{"type":["string","null"]},"region":{"type":"string"},"regionSlug":{"type":"string"},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}}},"image":{"type":"object","required":["url","source","license","attribution"],"properties":{"url":{"type":"string","format":"uri"},"source":{"type":["string","null"],"format":"uri"},"license":{"type":["string","null"]},"attribution":{"type":["string","null"]}}},"classification":{"type":"object","description":"웹·지도·모바일 앱이 공통으로 사용하는 액티비티 분류","additionalProperties":true},"placeKind":{"type":"string","enum":["operator","place"]},"profileQuality":{"type":"object","required":["tier","score","seoIndexable"],"properties":{"tier":{"type":"string","enum":["complete","verified","directory"]},"score":{"type":"number"},"seoIndexable":{"type":"boolean"},"missing":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"type":{"type":"string"},"summary":{"type":"string"},"serviceOverview":{"type":["string","null"]},"primaryActivity":{"type":["string","null"]},"serviceTags":{"type":"array","items":{"type":"string"}},"audience":{"type":"object","required":["beginner","kids","koreanSupport"],"properties":{"beginner":{"type":"boolean"},"kids":{"type":"boolean"},"koreanSupport":{"type":"boolean"}}},"season":{"type":"string"},"status":{"type":"string"},"safetyNote":{"type":["string","null"]},"verifiedAt":{"type":"string"},"mainProduct":{"type":["object","null"],"additionalProperties":true},"products":{"type":"array","items":{"type":"object","additionalProperties":true}},"price":{"type":"object","required":["hasPublishedPrice","label","items","note","sourceUrl"],"properties":{"hasPublishedPrice":{"type":"boolean"},"label":{"type":["string","null"]},"items":{"type":"array","items":{"type":"object","additionalProperties":true}},"note":{"type":["string","null"]},"sourceUrl":{"type":["string","null"],"format":"uri"}}},"marineEncounters":{"type":"array","items":{"type":"object","additionalProperties":true}},"contact":{"type":"object","required":["website","mapUrl","address","phone","email","openingHours"],"properties":{"website":{"type":["string","null"],"format":"uri"},"mapUrl":{"type":["string","null"],"format":"uri"},"address":{"type":["string","null"]},"phone":{"type":["string","null"]},"email":{"type":["string","null"]},"openingHours":{"type":["string","null"]}}},"sourceUrl":{"type":["string","null"],"format":"uri"}}},"ErrorResponse":{"type":"object","required":["apiVersion","error"],"properties":{"apiVersion":{"type":"integer","example":16},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"received":{"type":["string","null"]}}}}},"CoverageMetric":{"type":"object","required":["count","total","percent"],"properties":{"count":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0},"percent":{"type":"number","minimum":0,"maximum":100}}},"CoverageResponse":{"type":"object","required":["apiVersion","generatedAt","methodology","totals","quality","safetyAudit","territories"],"properties":{"apiVersion":{"type":"integer","example":16},"generatedAt":{"type":"string","format":"date"},"methodology":{"type":"object","additionalProperties":true},"totals":{"type":"object","required":["operators","naturalPlaces","places","registeredUnits","thinRegisteredUnits","publicationHolds","safetyReviews"],"properties":{"operators":{"type":"integer","minimum":0},"naturalPlaces":{"type":"integer","minimum":0},"places":{"type":"integer","minimum":0},"registeredUnits":{"type":"integer","minimum":0},"thinRegisteredUnits":{"type":"integer","minimum":0},"publicationHolds":{"type":"integer","minimum":0},"safetyReviews":{"type":"integer","minimum":0}}},"quality":{"type":"object","required":["profileTiers","operatorProfileTiers","naturalPlaceProfileTiers","seoIndexablePlaces","directOperatorWebsites","publishedPriceOperators","operatorFields","marineFields","disclosure"],"properties":{"profileTiers":{"type":"object","required":["complete","verified","directory"],"properties":{"complete":{"type":"integer","minimum":0},"verified":{"type":"integer","minimum":0},"directory":{"type":"integer","minimum":0}}},"operatorProfileTiers":{"type":"object","description":"운영사·업체만 분리한 프로필 검증 등급입니다.","required":["complete","verified","directory"],"properties":{"complete":{"type":"integer","minimum":0},"verified":{"type":"integer","minimum":0},"directory":{"type":"integer","minimum":0}}},"naturalPlaceProfileTiers":{"type":"object","description":"해변·다이빙 포인트 등 비운영사 자연 장소만 분리한 프로필 검증 등급입니다.","required":["complete","verified","directory"],"properties":{"complete":{"type":"integer","minimum":0},"verified":{"type":"integer","minimum":0},"directory":{"type":"integer","minimum":0}}},"seoIndexablePlaces":{"type":"integer","minimum":0},"directOperatorWebsites":{"type":"integer","minimum":0},"publishedPriceOperators":{"type":"integer","minimum":0},"operatorFields":{"type":"object","required":["directOperatorWebsite","address","directContact","specificOpeningHours","specificSeason","specificProduct","multipleProducts","publishedPrice","completeProfile","seoIndexable"],"properties":{"directOperatorWebsite":{"type":"object","required":["count","total","percent"],"properties":{"count":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0},"percent":{"type":"number","minimum":0,"maximum":100}}},"address":{"type":"object","required":["count","total","percent"],"properties":{"count":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0},"percent":{"type":"number","minimum":0,"maximum":100}}},"directContact":{"type":"object","required":["count","total","percent"],"properties":{"count":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0},"percent":{"type":"number","minimum":0,"maximum":100}}},"specificOpeningHours":{"type":"object","required":["count","total","percent"],"properties":{"count":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0},"percent":{"type":"number","minimum":0,"maximum":100}}},"specificSeason":{"type":"object","required":["count","total","percent"],"properties":{"count":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0},"percent":{"type":"number","minimum":0,"maximum":100}}},"specificProduct":{"type":"object","required":["count","total","percent"],"properties":{"count":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0},"percent":{"type":"number","minimum":0,"maximum":100}}},"multipleProducts":{"type":"object","required":["count","total","percent"],"properties":{"count":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0},"percent":{"type":"number","minimum":0,"maximum":100}}},"publishedPrice":{"type":"object","required":["count","total","percent"],"properties":{"count":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0},"percent":{"type":"number","minimum":0,"maximum":100}}},"completeProfile":{"type":"object","required":["count","total","percent"],"properties":{"count":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0},"percent":{"type":"number","minimum":0,"maximum":100}}},"seoIndexable":{"type":"object","required":["count","total","percent"],"properties":{"count":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0},"percent":{"type":"number","minimum":0,"maximum":100}}}}},"marineFields":{"type":"object","required":["structuredEncounterPrograms"],"properties":{"structuredEncounterPrograms":{"type":"object","required":["count","total","percent"],"properties":{"count":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0},"percent":{"type":"number","minimum":0,"maximum":100}}}}},"disclosure":{"type":"string"}}},"safetyAudit":{"type":"object","additionalProperties":true},"territories":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"MapCoreRow":{"type":"array","description":"0 slug, 1 country, 2 countrySlug, 3 countryDisplayName, 4 ISO, 5 sovereignParent, 6 region, 7 regionSlug, 8 name, 9 localName, 10 image, 11 activities, 12 type, 13 season, 14 status, 15 latitude, 16 longitude, 17 bit flags, 18 mainProduct, 19 priceItems, 20 marineEncounters, 21 imageSource, 22 imageLicense, 23 imageAttribution. 문자열 값은 strings 배열의 인덱스이며, 선택 이미지 크레딧은 -1입니다. 21개 필드의 기존 core-v1 row도 디코딩할 수 있습니다.","minItems":21,"maxItems":24,"prefixItems":[{"type":"integer"},{"type":"integer"},{"type":"integer"},{"type":"integer"},{"type":"integer"},{"type":"integer"},{"type":"integer"},{"type":"integer"},{"type":"integer"},{"type":"integer"},{"type":"integer"},{"type":"array","items":{"type":"integer"}},{"type":"integer"},{"type":"integer"},{"type":"integer"},{"type":"number","minimum":-90,"maximum":90},{"type":"number","minimum":-180,"maximum":180},{"type":"integer","minimum":0},{"oneOf":[{"const":0},{"type":"array","minItems":4,"maxItems":4,"items":{"type":"integer"}}]},{"oneOf":[{"const":0},{"type":"array","items":{"type":"array","minItems":2,"maxItems":2,"items":{"type":"integer"}}}]},{"oneOf":[{"const":0},{"type":"array","items":{"type":"array","minItems":4,"maxItems":4}}]},{"type":"integer","minimum":-1},{"type":"integer","minimum":-1},{"type":"integer","minimum":-1}],"items":false},"MapCorePayload":{"type":"object","required":["apiVersion","generatedAt","count","format","strings","places"],"properties":{"apiVersion":{"type":"integer"},"generatedAt":{"type":"string","format":"date"},"count":{"type":"integer"},"format":{"const":"watermap-map-core-v1"},"strings":{"type":"array","items":{"type":"string"}},"places":{"type":"array","items":{"$ref":"#/components/schemas/MapCoreRow"}}}},"MapSearchPayload":{"type":"object","required":["apiVersion","generatedAt","count","format","keys","searchText"],"properties":{"apiVersion":{"type":"integer"},"generatedAt":{"type":"string","format":"date"},"count":{"type":"integer"},"format":{"const":"watermap-map-search-v2"},"keys":{"type":"array","description":"countrySlug/regionSlug/slug 형식의 안정적인 지도 키","items":{"type":"string"}},"searchText":{"type":"array","items":{"type":"string"}}}}}}}