Places API vs Geocoding vs Directions 차이: 어떤 상황에서 무엇을 써야 할까

Google Maps Platform을 붙일 때 가장 먼저 막히는 지점은 지도를 띄우는 일보다 어떤 API가 현재 문제에 맞는지 고르는 일입니다. 이름이 비슷해서 같은 역할처럼 보이지만, Places API는 장소를 찾고 설명하는 데 강하고, Geocoding API는 주소와 좌표를 바꾸는 데 쓰이며, Directions는 출발지와 도착지 사이의 경로를 계산하는 데 맞습니다.

선택이 어긋나면 응답 구조가 달라지고, 필요한 데이터도 부족해지며, 과금 포인트까지 헷갈리기 쉽습니다. 기준은 단순합니다. 지금 필요한 것이 장소 검색인지, 주소 정규화인지, 길찾기인지부터 나누면 대부분 바로 결정됩니다.

세 API 차이를 한눈에 보면

처음 붙일 때는 입력값과 원하는 출력값을 기준으로 보면 가장 빠릅니다. 아래 표만 기억해도 선택 실수가 많이 줄어듭니다.

Places API가 맞는 상황

Places API는 “이 주변에 무엇이 있나”, “사용자가 입력한 이 문자열이 어떤 장소를 뜻하나”, “이 장소의 상세 정보가 무엇인가” 같은 질문에 답하는 용도입니다. 단순한 주소 변환이 아니라 장소를 찾고, 후보를 좁히고, 선택한 장소의 정보를 보여주는 흐름에 잘 맞습니다.

검색창 자동완성이나 매장 찾기라면 Places API가 먼저입니다

사용자가 검색창에 “강남 스타벅스”, “성수 파스타”, “판교역 근처 카페”처럼 모호한 표현을 입력할 때는 Geocoding보다 Places API가 자연스럽습니다. 자동완성으로 후보를 보여주고, 선택된 항목에서 place ID를 얻은 뒤 상세 정보 화면으로 이어가기 좋기 때문입니다.

장소 상세 화면이 필요하면 Places API가 핵심입니다

가게명, 주소, 전화번호, 영업 상태, 사용자 평점, 리뷰 같은 장소 중심 정보가 필요하면 Places API가 맞습니다. 특히 장소 상세 화면을 만들 때는 처음부터 Places 흐름으로 가져가야 응답 구조가 덜 꼬입니다. 단, 필요한 필드만 요청하도록 설계하는 편이 응답 크기와 비용을 함께 관리하기 좋습니다.

Places API가 아닌 경우도 분명합니다

이미 정확한 도로명 주소를 가지고 있고, 그 주소를 위도·경도로 저장하려는 목적이라면 Places까지 갈 필요가 없습니다. 이때는 Geocoding이 더 단순하고 목적에 맞습니다. 반대로 출발지와 도착지 사이 이동시간이 필요하다면 Places가 아니라 Directions 계열을 봐야 합니다.

Geocoding API가 맞는 상황

Geocoding API는 주소와 좌표를 서로 바꾸는 도구입니다. 핵심은 장소 추천이 아니라 위치 변환입니다. 사람이 읽는 주소를 시스템이 다루기 쉬운 좌표로 바꾸거나, 반대로 사용자가 찍은 지점을 사람에게 읽기 쉬운 주소로 바꿔 보여줄 때 가장 깔끔합니다.

주소를 좌표로 바꿔 저장할 때

회원 가입 주소, 배송지, 지점 주소, 부동산 주소처럼 이미 문자열 주소가 있는 경우에는 Geocoding이 기본 선택입니다. 이 작업은 검색 경험보다 데이터 정규화에 가깝기 때문에 Places보다 Geocoding 쪽이 역할이 분명합니다. 지도 마커를 찍거나 거리 계산의 기초 좌표를 만들 때 자주 쓰입니다.

좌표를 주소로 바꿔 보여줄 때

지도에서 사용자가 핀을 찍었거나 모바일 위치 권한으로 좌표를 얻었다면 역지오코딩이 필요합니다. 이때는 위도·경도를 사람이 읽을 수 있는 주소로 바꾸어 “선택한 위치”, “현재 위치”, “픽업 지점” 같은 화면에 연결하면 됩니다. 좌표를 주소로 바꾸는 문제까지 Places로 해결하려 하면 오히려 흐름이 복잡해질 수 있습니다.

Geocoding으로 해결하기 어려운 요청

“서울역 근처 조용한 카페”, “별점 높은 일식집”, “지금 영업 중인 약국”처럼 검색 의도가 장소 탐색이라면 Geocoding으로는 답이 부족합니다. Geocoding은 어디인지 알려주는 도구이지, 무엇이 좋은 장소인지 고르는 도구는 아닙니다. 이런 경우는 Places API로 넘어가야 합니다.

Directions가 맞는 상황

Directions는 출발지와 도착지 사이를 어떻게 이동할지 계산하는 데 쓰입니다. 결과로는 전체 경로, 구간별 단계, 이동 거리, 예상 소요시간 같은 길찾기 정보가 나옵니다. 사용자에게 안내 경로를 보여주거나, 배송 예상시간을 계산하거나, 경유지를 포함한 이동 계획을 세울 때 자연스럽습니다.

길찾기 결과가 필요하면 Directions를 고릅니다

“회사에서 고객사까지 차로 얼마나 걸리는지”, “도보 기준으로 어느 길로 가야 하는지”, “여러 지점을 거치는 경로를 어떻게 잡아야 하는지”처럼 이동 자체가 핵심이면 Directions가 맞습니다. Places처럼 장소를 찾는 API도 아니고, Geocoding처럼 주소를 정리하는 API도 아닙니다. 문제의 중심이 경로 계산이면 길찾기 API를 써야 합니다.

신규 프로젝트라면 Routes API도 함께 확인하는 편이 좋습니다

기존 예제와 검색 결과에는 Directions API가 많이 보이지만, 현재 신규 구축 관점에서는 Routes API 문서도 같이 보는 편이 안전합니다. 경로 계산을 오래 운영할 서비스라면 처음부터 최신 경로 계열 문서를 기준으로 구조를 잡아두는 쪽이 이후 유지보수에 유리합니다. 기존 시스템을 이해할 때는 Directions를 읽고, 새 설계에서는 Routes까지 함께 비교하면 판단이 훨씬 쉬워집니다.

출처: Google Maps Platform 공식 문서

Directions만으로 해결되지 않는 경우

사용자가 아직 목적지를 정하지 못했고 검색창에 장소명을 입력하는 단계라면 Directions를 먼저 부르면 안 됩니다. 먼저 Places로 후보를 찾고, 필요하면 Geocoding으로 좌표를 정리한 뒤, 마지막에 Directions나 Routes로 경로를 계산하는 순서가 더 자연스럽습니다.

실무에서는 하나만 쓰기보다 조합하는 경우가 많습니다

실제 서비스에서는 세 API가 경쟁 관계라기보다 역할 분담 관계에 가깝습니다. 장소 검색, 주소 변환, 길찾기가 한 화면 안에서도 이어질 수 있기 때문입니다. 아래처럼 흐름을 나누면 설계가 빨라집니다.

처음 붙일 때 무엇부터 고르면 좋은가

판단 기준은 생각보다 단순합니다. 사용자 입력이 애매한 장소명인지, 이미 확정된 주소인지, 아니면 이동 경로인지부터 먼저 자르면 됩니다. 검색창이 있으면 Places, 확정 주소를 DB에 넣을 거면 Geocoding, 이동시간과 안내가 필요하면 Directions 계열이라고 보면 대부분 맞습니다.

비용과 응답 구조까지 함께 생각하면 더 안정적입니다. Places는 요청하는 상세 필드 범위에 따라 설계 차이가 커지기 쉽고, Geocoding은 주소 변환 중심이라 구조가 비교적 단순하며, 경로 계산은 길찾기 요구사항이 늘어날수록 Directions 또는 Routes 설계가 중요해집니다. API를 먼저 고르기보다 화면에서 보여줄 결과를 먼저 그려보면 선택이 훨씬 쉬워집니다.

자주 묻는 질문

---

Maps API 선택은 기능 이름보다 입력값과 원하는 결과를 먼저 나누는 순간 훨씬 쉬워집니다. 장소 탐색, 주소 변환, 경로 계산을 분리해서 보면 설계와 비용 판단 모두 한결 단순해집니다.