🔍검색 API 이렇게 만들었어요!!

임규성·2025년 5월 5일

한 스텝씩 신중히

검색 기능은 사용자가 뭘 원하는지 부터 기능이 정의 되어야합니다.
따라서 UX설계 -> UI설계 -> API설계 -> API구현 각 Step에서의 고민이 있었습니다.

1. UX

어떤 것을 사용자가 원할까?

단순히 검색 기능을 개발한다가 아닌 사용자의 진정한 Needs는 무엇일까에서 시작했습니다. 이후 3개로 정리할 수 있었습니다.

🔍 Need 1. 현재 위치에서 가까운 주차장을 알고 싶을 때
“약수역 근처에 주차장이 있나?”
✅ 사용자는 지도를 중심으로 한 주변 탐색을 원함
✅ 검색 없이도 현재 위치 중심 반경 주차장 조회 기능 필요

🔍 Need 2. 특정 장소 근처의 주차장을 알고 싶을 때
“약수역 횟집에서 친구들이랑 만나기로 했는데, 근처에 주차장 있나?”
✅ 사용자는 가게/장소명을 입력하고 그 주변 주차장을 탐색하고자 함
✅ 장소 검색 → 해당 위치 중심으로 지도 이동 → 주변 주차장 표시
(밑의 UI를 확인하면 이해가 쉽다..!!)

🔍 Need 3. 주차장명 "오제제%" 이름을 가지는 주차장
“그때 갔던 주차장이 ‘오제제 주차장’이었던 것 같은데…”
✅ 사용자는 기억나는 이름 일부만으로 검색하고 싶어함
✅ 텍스트 기반 주차장명 키워드 검색 기능 제공 필요

이렇게 사용자의 Needs와 핵심 UX를 설계했고 해당 아래에 UI로 구현해 보겠습니다.

2. UI

UX를 구현하기 위해 UI로 설계했습니다.
아래는 결과 입니다. 각 부연설명에 UX를 어떻게 구현할지가 나타나져 있습니다.

3. API 설계

1. 병목 발생 예상 가능

키워드 검색 시 API에서 검색 응답을 준다면 1)주차장 DB 탐색 2)카카오 로컬 검색 API호출을 하게 됩니다.
1)주차장 DB 탐색 완료했지만 2)카카오 로컬 검색 API호출 진행중인 병목이 발생할 수 있습니다.

해결책

API를 두개로 분리합니다!!!

1. Mathing된 키워드와 인덱스 표시

UI적으로 키워드와 매칭된 하이라이팅을 하게된다면 가독성이 좋아질 것입니다.
따라서 해당 필드도 Response DTO에 추가했습니다!

응답 JSON 일부

"parkingZones": [
      {
		      "matchedInfo": [
				  {
				    "field": "zoneName",
				    "value": "오제제 주차장",
				    "matchedText": "오제제",
				    "startIndex": 0,
				    "endIndex": 2
				  },
				  {
				    "field": "cityName",
				    "value": "서울특별시",
				    "matchedText": "서울",
				    "startIndex": 0,
				    "endIndex": 1
				  }
				]