주소지 주변 상가 조회 북마크로 api 서버의 GET, POST 이해하기

저번에 간단한 API 서버 구현을 통해 GET = 조회, POST = 변경의 개념은 이해했고, 이제 이걸 제 취향을 섞어 간단한 웹 사이트를 만들어보았습니다.

도로명 주소를 입력하고 반경 거리를 입력하면 그 반경 내의 상가 목록을 보여주고(=GET), 메모와 북마크를 남기고 삭제할 수 있는(=POST, DELETE) 웹 사이트입니다.

ALT

한국사이트 스크린샷

조회, 북마크, 삭제 버튼을 눌렀을 때 요청과 응답 메세지가 어떻게 나오는지 확인하기 위해 밑에 코드 박스도 추가했습니다.

👩‍💻 진행 방법

• 서울 상권 정보 : 공공데이터포털 csv (open api는 승인을 받는 시간이 걸려서 보류했는데 요걸로 구현하는 것도 해보고 싶네요.)

• 사용 도구 : Cursor (Grok 4.5)

첫 번째. 데이터 저장소 선택하기 + csv 파일 구조를 파악하기

이 csv는 각 상가의 도로명주소, 지번주소, 경도, 위도에 대한 정보가 있습니다. 그래서 단순히 도로명주소에 정확히 해당하는 상가 검색은 바로 가능하지만 특정 반경 내의 상가 목록을 조회를 하려면 한 가지 절차를 거쳐야 했습니다.

커서가 데이터 저장소(SQLite, PostgreSQL)과 지오코딩, Harversine이 필요하다고 답변했습니다.

(1) SQLite vs PostgreSQL

상용화하면서 상시 돌아가는 서비스를 만들기 위해서는 PostgreSQL을 고려해야하는 것 같습니다.

여기서는 280MB 정도의 작은 실습이니 SQLite가 적합하다고 합니다.

그래도 저장소가 없으면 매번 csv 파일을 불러와야하고, 메모와 북마크를 남길 별도의 테이블도 필요해서 csv를 한 번 읽어서 DB에 넣는 과정이 반드시 필요합니다.

(2) 주소를 컴퓨터가 읽고 계산하기 편한 좌표로 바꾸기

컴퓨터는 두 위치의 거리 계산을 위해 위도, 경도라는 숫자 좌표가 필요합니다. 그래서 클라이언트가 주소를 입력하면 이를 위도, 경도로 바꿔주는 지오코딩이 필요합니다. 참고로 좌표를 주소로 바꿔주는 것은 역지오코딩이라고 합니다.

그리고 Harversine은 거리 검색 로직 중 하나인데 지구가 둥글다는 것을 고려해 두 위도, 경도 사이의 거리를 구하는 공식입니다.

두 번째. 요청부터 응답까지의 전체적인 구조 이해하기

[사용자]
  "서울 영등포구 OO로 123 근처 500m 상가 보여줘"
        │
        ▼
[API 서버]  GET /stores?address=...&radius=500
        │
        ├─① 지오코딩: 주소 → (위도, 경도)
        │
        ├─② DB에서 후보 상가 조회
        │     (가능하면 인덱스로 근처만 좁힘)
        │
        ├─③ 각 상가와 Haversine 거리 계산
        │     500m 이하만 남김
        │
        └─④ JSON으로 목록 응답

[나중에]
  마음에 드는 상가에 별/메모
        │
        ▼
[API 서버]  POST /bookmarks
        │
        └─ DB의 bookmarks 테이블에 저장

세 번째. 검색, 북마크, 삭제 시 json 메시지 확인하기

(1) 검색

'중구 세종대로 101'을 입력할 때의 조회 화면과 패널 화면입니다.

ALT

한국어 앱 스크린샷

ALT

한국사이트 스크린샷

요청의 'address='의 내용은 한글 주소를 인코딩한 내용입니다. address=중구 세종대로 101&radius=50 (위 주소 반경 50m를 조회하라)라는 의미입니다.

(2) 북마크 등록 & 조회 & 삭제

제가 점심에 자주 가는 식당을 북마크했습니다.

POST /api/bookmarks

• POST = “새로 저장해 주세요”

• /api/bookmarks = 북마크함으로 가는 주소

Content-Type: application/json

• “이번 편지는 JSON 형식이야”

• 서버가 body를 JSON으로 읽게 해줌

내 북마크 다시 불러오기 버튼을 누르는 것은 요청 메세지가 좀더 간단합니다.

ALT

한국어가 포함된 한국어 웹사이트 스크린샷

삭제는 등록할 때의 id로 무엇을 삭제하는지를 나타내고 있습니다.

💦 시행착오

코드를 바꾸고 웹을 새로고침했는데 안 바뀌던 오류

웹에 북마크 삭제 기능을 추가하라고 했고 커서가 코드(index.js)와 화면의 삭제 버튼이 반영된 것을 확인하고 새로고침을 눌렀을 때, 응답 패널에는 JSON 파싱 실패 라는 메세지가 떴습니다.

그 밖에도 코드 수정 후 바로 웹을 새로고침하여 오류를 보는 일을 서너번 반복했습니다.

원인은 두 가지 때문이었는데요,

1. 이미 실행 중이던 서버 프로세스에 옛 코드가 남아있어 새로고침 후에도 같은 서버에 다시 요청하는 것만 되었을 뿐, 바뀐 코드를 다시 읽지 않았으며

2. 터미널 스크립트로 pnpm dev → node --watch index.js (파일 바뀌면 프로세스 재시작)이 아닌 pnpm start → node index.js 를 사용함.

start를 사용할 경우 코드 변경 후 서버를 종료하고 다시 실행해야 했습니다.

반면 html, css처럼 화면 자체의 변경 사항이 있는 것들 (public/파일)은 대체로 새로고침만으로 바로 확인할 수 있습니다.

• 화면(정적 파일) 수정 → 새로고침으로 확인하는 경우가 많음

• API/라우트/DB 로직 수정 → 서버 프로세스 재시작 필요

API 서버를 만들라고 들었을 땐 낯설고 새로운 것이라고 생각했는데 알고보면 예전에 바이브코딩으로 했던 것들 안에 그 개념들이 들어있는 거였더라고요. 그렇지만 서버의 개념으로 다시 접근하니 새롭게 느껴졌습니다.

직접 타자치면서 하나하나 되짚어보니 여태 잘 알려고 하지 않고, ai의 답변을 제대로 읽지 않고 넘어갔었다는 생각이 들었습니다. 매번 100 프로 이해하려고는 하지 않더라도 이런 내용들은 알고 바이브코딩을 하면 더 도움이 될 것 같아요