Google 지도 API를 웹사이트에 적용하기

📝 한줄 요약

담당자가 구글맵을 하나씩 열어서 재던 거리를, 주소만 넣으면 자동으로 나오게 만들었습니다. 중간에 Failed to fetch 에러로 막혔는데, 그걸 뚫는 과정에서 API 키까지 안전해졌습니다.

Before: 미팅 건마다 구글맵을 열어 출발지와 도착지를 찍고 눈으로 확인

After: 주소를 고르면 1.9 miles가 자동으로 뜸

👥 이런 분께 추천

• 외부 API를 처음 붙여보는 비개발자

• API 키를 발급받았는데 어디에 넣어야 할지 모르는 분

• Failed to fetch 에러를 만나서 검색 중인 분

• 유료 API를 쓰는 게 무서운 분

🙋 내 스펙 & 환경

진행 방법

1. 왜 하게 되었나

초과근무 미팅에는 거리에 따라 수당 타입이 갈립니다. 기준 거리를 넘으면 타입 B, 안 넘으면 타입 A예요.

그런데 지금은 이걸 담당자가 구글맵을 하나씩 열어서 확인합니다. 한 달에 50건 가까이 되는데 매번 그러고 있어요. 게다가 눈으로 재다 보니 기준에 아슬아슬한 건은 판단이 갈립니다.

그래서 주소만 넣으면 사무실에서 몇 마일인지 자동으로 뜨게 만들기로 했습니다.

2. 첫 번째 벽: 직선거리는 실제 거리가 아니다

처음에는 좌표 두 개로 직선거리를 계산했습니다. 지도 서비스를 안 써도 되니 카드 등록이 필요 없고 무료거든요.

화면에 숫자는 잘 떴습니다. 그런데 보다가 이게 아니라는 걸 알았어요.

수당이 걸린 값이라 실제 운전 거리여야 합니다.

그래서 Google 지도 API로 방향을 틀었습니다.

판단 기준: 정확도가 돈으로 이어지는 값이면 무료로 때우면 안 됩니다.

3. API 키 발급받기

Google Cloud에 가입하니 카드를 요구했습니다. 팝업에는 이렇게 적혀 있었어요.

임시로 $50 승인이 카드에 걸립니다.
카드가 유효한지 확인하는 용도이며, 보통 일주일 안에 해제됩니다.

실제로 청구되는 게 아니라 카드가 진짜인지 확인하는 절차였습니다.

무료 사용량 안에서만 쓰면 요금은 0원이고요.

카드까지 등록했으니 이제 API 키를 만들면 됩니다.

단계:

1. Google Cloud Console에서 “APIs & Services” → “Credentials” 메뉴 들어가기

2. “Create Credentials” → “API Key” 클릭

3. 생성된 키 복사해서 .env.local 파일에 저장

   사본

   GOOGLE_MAPS_API_KEY=AIzaSy...

4. Console에서 그 키를 클릭해 “API restriction” 설정

   • 여러 API를 쓸 수 있게 하되, Distance Matrix API만 체크해서 보안 강화

이 과정은 처음에는 낯설지만, 천천히 따라 하면 5분 안에 끝납니다. 키를 발급받는 순간부터 코드에 붙일 준비가 된 것입니다.

4. 세 번째 벽: Failed to fetch

API 키를 발급받아 넣고 주소를 골랐는데, 거리가 안 떴습니다.

화면 아래에 오류 1건이라고만 나왔어요.

개발자 도구를 열어 보니 이렇게 찍혀 있었습니다.

Distance calculation failed: TypeError: Failed to fetch
    at calculateDistance (...)
    at SubmitForm.useEffect (...)

Failed to fetch는 “요청을 아예 보내지도 못했다”는 뜻입니다. 주소가 틀렸거나 키가 틀린 게 아니라, 요청 자체가 출발을 못 한 상태예요.

원인은 CORS였습니다. Google이 브라우저에서 직접 오는 요청을 막아둔 것이었어요.

왜 막느냐면, 브라우저 코드는 누구나 열어볼 수 있기 때문입니다. 거기에 API 키를 넣으면 남이 그 키를 꺼내서 내 계정으로 요금을 쓸 수 있어요. 그래서 Google이 아예 브라우저 호출을 안 받습니다.

5. 해결: 서버를 한 번 거치게 만들기

브라우저가 직접 못 부르면, 내 서버가 대신 물어보게 하면 됩니다.

[바뀌기 전] 화면 → Google        (막힘)
[바뀐 뒤]   화면 → 내 서버 → Google  (됨)

이렇게 바꾸면서 API 키를 넣는 위치도 함께 바뀌었습니다. 이게 중요한 부분이에요.

Next.js에서는 환경변수 이름 앞에 NEXT_PUBLIC_이 붙으면 그 값이 브라우저까지 전달됩니다. 처음엔 이걸 모르고 붙였는데, 서버로 옮기면서 떼게 됐어요.

즉 막혀서 돌아간 길이 결과적으로 더 안전한 길이었습니다.

6. 함께 잡은 버그: 미터를 마일로 착각

서버로 옮기면서 버그를 하나 발견했습니다. Google이 돌려주는 거리 값을 그대로 마일로 쓰고 있었는데, Google은 미터로 줍니다.

[틀림] 3060 → 3060 miles
[맞음] 3060 ÷ 1609.344 → 1.9 miles

이런 버그는 에러가 안 납니다. 숫자가 그냥 이상하게 클 뿐이에요. 그래서 직접 아는 답과 대조해봐야 잡힙니다.

7. 검증: 내가 아는 거리로 확인하기

실제로 거리를 아는 두 곳을 넣어봤습니다.

둘 다 실제 운전 거리와 맞았습니다.

휴대폰 크기(375px)에서도 가로로 넘치는 부분 없이 잘 보이는 걸 확인했습니다.

8. 마지막: 키가 GitHub에 안 올라가는지 확인

API 키를 쓰게 됐으니 실수로 인터넷에 올라가지 않는지 확인했습니다. 이건 나중에 몰아서 하면 늦어요. 키를 만든 그날 확인해야 합니다.

제가 던진 요청은 이거였습니다.

API 키를 쓰게 됐어. 실수로 GitHub에 올라가지 않게 안전하게 넣어줘.
- 키를 코드에 직접 쓰지 말고 따로 관리하는 방식으로 해줘.
- 그 파일이 .gitignore에 들어 있는지 확인해줘.
- 혹시 이미 올라간 적이 있으면 알려줘.

확인 결과입니다.

🛠 사용한 도구

📚 오늘 배운 용어

적용할 점

🎯 결과

📋 복붙 가능한 프롬프트

같은 걸 만들고 싶은 분을 위해 제가 실제로 쓴 요청입니다.

거리 계산을 붙일 때:

주소를 넣으면 사무실에서 몇 마일인지 자동으로 뜨게 해줘.

[조건]
- 직선거리가 아니라 차로 이동하는 실제 거리여야 해 (구글 네비게이션 기준)
- 사무실 주소는 설정 화면에 저장된 값을 기준으로
- 사용자가 고칠 수 없는 읽기 전용으로 표시

[확인]
- 내가 거리를 아는 장소 두 곳으로 검증해줘
- 휴대폰 크기(375px)에서도 안 깨지는지 확인해줘

API 키를 받은 직후에 던질 요청입니다. 이건 키를 쓰는 모든 프로젝트에 그대로 쓸 수 있어요.

API 키를 쓰게 됐어. 실수로 GitHub에 올라가지 않게 안전하게 넣어줘.
- 키를 코드에 직접 쓰지 말고 따로 관리하는 방식으로 해줘.
- 그 파일이 .gitignore에 들어 있는지 확인해줘.
- 혹시 이미 올라간 적이 있으면 알려줘.

📋 API 키를 처음 쓸 때 체크리스트

• 키가 소스코드에 직접 박혀 있지 않은가

• 키를 담은 파일이 .gitignore에 들어 있는가

• 과거 커밋 이력에 키가 올라간 적이 없는가

• 환경변수 이름에 브라우저로 전달되는 접두어가 붙어 있지 않은가

• Google Console에서 그 키가 쓸 수 있는 API를 하나로 제한했는가

• 예산 알림을 걸어뒀는가

🔜 다음 계획

1. Day 7: 거리가 나오면 수당 타입을 자동으로 제안하게 만들기 (사람이 고칠 수 있게)

2. Day 8: 전자서명을 고르면 거리 영역이 사라지게 만들기

3. 배포 전: 예산 알림 걸기

솔직한 소감

뿌듯했습니다.

주소만 넣었는데 18.7 miles가 툭 뜨는 순간이 좋았어요.

담당자가 구글맵을 하나씩 열어서 재던 일이 사라지는 거니까요.

그런데 오늘 제일 재밌었던 건 성공한 순간이 아니라 막힌 순간이었습니다.

Failed to fetch를 보고 “아 뭐가 잘못됐지” 했는데, 알고 보니 Google이 일부러 막아둔 거였고, 그 이유가 “브라우저에 비밀을 두면 안 되니까”였어요. 그래서 서버로 돌아갔더니 원래 하려던 것도 되고 보안도 같이 해결됐습니다.