{"openapi":"3.0.3","info":{"title":"APICK 장소 검색·거리 정렬","version":"1.0.0","description":"장소명으로 검색해 분류·주소·좌표를 정리하고, 기준점이 있으면 각 결과의 거리·방위를 계산해 가까운 순으로 정렬합니다. 주변 후보를 가까운 순서로 보여줄 때 씁니다."},"servers":[{"url":"https://apick.app"}],"paths":{"/rest/geo_place_search":{"post":{"summary":"장소 검색·거리 정렬","description":"장소명으로 검색해 분류·주소·좌표를 정리하고, 기준점이 있으면 각 결과의 거리·방위를 계산해 가까운 순으로 정렬합니다. 주변 후보를 가까운 순서로 보여줄 때 씁니다.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"서비스별 성공·처리 상태 응답","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"query":{"type":"string"},"origin":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"},"crs":{"type":"string"}},"description":"적용한 기준점입니다. 없으면 null 입니다.","nullable":true},"radius":{"type":"integer"},"page":{"type":"object","properties":{"current":{"type":"integer"},"size":{"type":"integer"},"total":{"type":"integer"}}},"count":{"type":"integer","description":"반환한 결과 수입니다."},"items":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"id":{"type":"string","description":"장소 식별자입니다."},"name":{"type":"string","description":"장소 이름입니다."},"category":{"type":"object","properties":{"full":{"type":"string","description":"분류 전체 표기입니다."},"large":{"type":"string","description":"대분류입니다."},"middle":{"type":"string","description":"중분류입니다."},"small":{"type":"string","description":"소분류입니다."}}},"address":{"type":"object","properties":{"road":{"type":"string","description":"도로명 주소입니다."},"parcel":{"type":"string","description":"지번 주소입니다."}}},"point":{"type":"object","properties":{"x":{"type":"number","description":"경도입니다."},"y":{"type":"number","description":"위도입니다."},"crs":{"type":"string"}}},"distanceM":{"type":"number","description":"기준점과의 거리(m)입니다. 기준점이 있을 때만 있습니다."},"bearing":{"type":"number","description":"기준점에서 본 방위(도, 북쪽 0·동쪽 90)입니다."}}}},"error":{"type":"string","description":"실패 사유입니다. 이 필드가 있으면 과금되지 않습니다."}}},"api":{"type":"object","properties":{"cost":{"type":"integer","description":"차감된 포인트입니다. 실패한 응답은 0입니다."},"success":{"type":"boolean"},"ms":{"type":"integer","description":"처리 시간(밀리초)입니다."}}}}}}}},"default":{"description":"HTTP 상태 및 서비스 오류코드 확인","content":{"application/json":{"schema":{"type":"object"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"장소 검색어 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. (string)","example":"강남역"},"origin":{"type":"string","description":"기준점 \"경도,위도\" (예: 127.025,37.504) 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. (string)","example":"127.0249287,37.5044445"},"x":{"type":"string","description":"기준점 경도. origin 대신 사용합니다. 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다. (number)"},"y":{"type":"string","description":"기준점 위도. origin 대신 사용합니다. 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다. (number)"},"radius":{"type":"string","description":"반경(m). 주면 반경 밖 결과를 제외합니다. 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다. (number)","example":"1000"},"sort":{"type":"string","description":"정렬 (기본 distance, 기준점이 있을 때만 적용) 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. 가능한 값은 2가지입니다. distance = distance 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. relevance = 검색어와의 관련도가 높은 순서로 정렬하는 값입니다. 기본 정렬로 가장 많이 쓰입니다. (string)","enum":["distance","relevance"]},"page":{"type":"string","description":"조회할 페이지 번호입니다. 1부터 시작하며, 전체 결과 범위를 넘으면 빈 배열이 옵니다. (integer)"},"size":{"type":"string","description":"출력 이미지의 크기입니다. 1024x1024 같은 WxH 형식으로 보내며, 모델별 지원 크기를 확인하세요. (integer)","example":"5"}},"required":["query"]}}}}}}},"x-code-tables":[{"title":"오류 코드","columns":["상황","data.error 예","대처"],"rows":[["입력 누락·형식 오류","검색어가 필요합니다. / 주소 유형이 잘못됐습니다. / 좌표가 올바르지 않습니다. …","문구가 가리키는 입력을 고쳐 다시 요청합니다. 조회 전에 끝나며 과금되지 않습니다."],["개수·길이 초과","주소가 너무 깁니다. / 한 요청에 주소를 50개까지 보낼 수 있습니다. …","표의 최대값 안으로 줄이거나 나눠서 요청합니다."],["위치를 찾지 못함","입력한 위치를 찾지 못했습니다.","주소 표기(시도·시군구 포함 여부, 오탈자)를 확인합니다. 과금되지 않습니다."],["처리 시간 초과","처리 시간이 초과됐습니다. 범위를 줄여 다시 시도해 주세요.","목록 건수·반경·분류 수를 줄여 다시 요청합니다. 과금되지 않습니다."],["일시적 실패","공간정보를 일시적으로 가져오지 못했습니다. 잠시 후 다시 시도해 주세요.","잠시 뒤 같은 요청을 다시 보냅니다. 과금되지 않습니다."]]}],"x-service-errors":[],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}}}