3 - 파이썬으로 네이버 장소 검색 API 활용하기 – 코드 예제와 실전 팁

네이버 지도 API를 활용한 자동화 프로젝트의 첫걸음은 바로 ‘장소 검색’입니다. 이 포스팅에서는 파이썬을 이용해 네이버 검색 API(Local)를 호출하고, 원하는 장소 데이터를 효과적으로 수집‧활용하는 모든 과정을 실무 관점에서 상세히 안내합니다. API의 구조와 파라미터, 페이징 및 대량 수집, 좌표 변환, 데이터 정제, 엑셀 연동까지 실제 현업 자동화나 데이터 분석에 곧바로 응용할 수 있도록 구성했습니다.

---

네이버 장소 검색 API 개요 및 파라미터

네이버 장소 검색 API(Local)는 RESTful 방식으로 동작하며, 전국의 다양한 장소·업체 정보를 파이썬 등 다양한 환경에서 쉽게 가져올 수 있습니다. 주요 파라미터는 아래와 같습니다.

• query: 검색 키워드(예: “강남역 카페”, “부산 해운대 맛집” 등)
• display: 결과 개수(1~100개, 기본 10)
• start: 검색 시작 위치(1~1000)
• sort: 정렬 방식(‘random’: 유사도순, ‘comment’: 리뷰 많은 순 등)

호출 시에는 네이버 개발자센터에서 발급받은 Client ID와 Client Secret을 HTTP 헤더에 포함해야 하며, 엔드포인트는 아래와 같습니다.

GET https://openapi.naver.com/v1/search/local.json

참고: 파이썬의 requests는 한글 쿼리도 자동으로 UTF-8 인코딩 처리하므로 별도 인코딩 설정이 필요하지 않습니다.

---

파이썬으로 장소 검색 API 호출하기

아래 예시는 requests 라이브러리를 활용해 네이버 장소 검색 API를 호출하고, 결과를 JSON으로 받아 파싱하는 기본 패턴입니다. 실제 프로젝트에서는 이 코드를 기반으로 페이징, 대량 수집, 데이터 정제 등 다양한 확장 작업이 가능합니다.

import requests
import re

NAVER_CLIENT_ID = "<네이버_클라이언트_ID>"
NAVER_CLIENT_SECRET = "<네이버_클라이언트_시크릿>"

url = "https://openapi.naver.com/v1/search/local.json"
params = {
    'query': '강남역 카페',   # 검색어
    'display': 10,           # 최대 10개 결과
    'start': 1,              # 1번부터 시작
    'sort': 'random'         # 정렬 기준
}
headers = {
    'X-Naver-Client-Id': NAVER_CLIENT_ID,
    'X-Naver-Client-Secret': NAVER_CLIENT_SECRET
}

response = requests.get(url, params=params, headers=headers)
data = response.json()

if response.status_code == 200:
    print(f"총 결과: {data['total']}")
    for idx, item in enumerate(data['items'], 1):
        title = re.sub('<.*?>', '', item['title'])  #  태그 제거
        print(f"[{idx}] {title}")
        print(f"  - 주소: {item['roadAddress']} / {item['address']}")
        print(f"  - 전화번호: {item['telephone']}")
        print(f"  - 좌표(mapx, mapy): {item['mapx']}, {item['mapy']}")
        print(f"  - 카테고리: {item['category']}")
        print("")
else:
    print("API 호출 실패", data)

주요 필드 설명

• title: 장소명(HTML <b> 태그 포함될 수 있음)
• roadAddress, address: 도로명/지번 주소
• telephone: 전화번호(미기재 시 빈 문자열)
• category: 장소 분류(카페, 음식점, 은행 등)
• mapx, mapy: 네이버 TM128 좌표계 X, Y 값(지도 표시에는 위도/경도 변환 필요)

---

페이징 및 대량 데이터 수집 전략

네이버 장소 검색 API는 한 번에 최대 100개, 1000건까지 검색이 가능합니다. 대량 수집이 필요하다면 start 값을 1, 101, 201… 순으로 조정하여 여러 번 호출해 데이터를 누적하면 됩니다.

all_items = []
for start in range(1, 1001, 100):  # 1, 101, 201, ...
    params['start'] = start
    response = requests.get(url, params=params, headers=headers)
    data = response.json()
    if response.status_code == 200 and data['items']:
        all_items.extend(data['items'])
    else:
        break
print(f"총 {len(all_items)}건 수집 완료")

팁: 일 25,000회 쿼터 내에서 sleep을 적절히 적용하고, 중복·결과 품질 관리도 필요합니다.

---

좌표(mapx, mapy) → 위도/경도(WGS84) 변환

API의 mapx, mapy 값은 네이버 TM128 좌표계(EPSG:5179)입니다. 지도 시각화나 외부 서비스 연동을 위해서는 WGS84(위도·경도, EPSG:4326)로 변환해야 합니다. 오픈소스 pyproj를 사용하면 간편하게 처리할 수 있습니다.

from pyproj import Transformer

def tm128_to_wgs84(mapx, mapy):
    transformer = Transformer.from_crs("EPSG:5179", "EPSG:4326", always_xy=True)
    lon, lat = transformer.transform(mapx, mapy)
    return lat, lon

for item in data['items']:
    mapx = float(item['mapx'])
    mapy = float(item['mapy'])
    lat, lon = tm128_to_wgs84(mapx, mapy)
    print(f"위도: {lat:.7f}, 경도: {lon:.7f}")

• EPSG:5179는 네이버 TM128 좌표계, EPSG:4326은 GPS(WGS84)입니다.
• Static Map, folium, pandas 등 다양한 지도 시각화와 데이터 분석에 바로 활용 가능합니다.

참고: pyproj 미설치 시 pip install pyproj로 쉽게 추가할 수 있습니다.

---

대량 수집 및 데이터 정제 실전 노하우

• 검색어/지역명 표준화: 동일 업체·프랜차이즈라면 지역명을 추가해 쿼리 품질을 높일 수 있습니다(예: “스타벅스 부산”).
• 중복·오류 필터링: 동일 상호명, 오타, 잘못된 위치(예: 위도/경도 0,0 등)는 수집 후 파이썬으로 한 번 더 정제하세요.
• display/start 값 관리: start 값 1000 초과 시 응답이 나오지 않으니 주의하세요.
• API 쿼터 관리: 반복 자동화 시 25,000회 내에서 동작하도록 sleep, 로깅 활용
• 정렬 기준 활용: ‘random’, ‘comment’ 등 원하는 데이터 특성에 따라 정렬을 변경할 수 있습니다.
• 에러 및 빈 결과 처리: try-except로 빈 결과, 오류(400, 401, 500 등)에 대비해 안정성을 확보하세요.

---

pandas·엑셀 연동 및 자동화

수집한 결과를 pandas 데이터프레임으로 변환해 저장·분석하거나, 엑셀 등 외부 시스템과 연동할 수 있습니다.

import pandas as pd

items_for_df = []
for item in all_items:
    mapx = float(item['mapx'])
    mapy = float(item['mapy'])
    lat, lon = tm128_to_wgs84(mapx, mapy)
    items_for_df.append({
        'name': re.sub('<.*?>', '', item['title']),
        'roadAddress': item['roadAddress'],
        'category': item['category'],
        'lat': lat,
        'lon': lon,
        'tel': item['telephone']
    })
df = pd.DataFrame(items_for_df)
# df.to_csv('places.csv', index=False)
print(df.head())

이렇게 하면 장소 데이터 자동 수집·좌표 변환·엑셀 저장까지 한 번에 처리할 수 있습니다. 향후 Streamlit 대시보드, 지도 시각화, 리포트 자동화로도 바로 연계할 수 있습니다.

---

실무 활용을 위한 추가 팁

• 네트워크/인증 오류 대처: 잘못된 Client ID/Secret, 쿼터 초과, 네트워크 장애 등 에러 상황에 예외처리 코드를 두는 것이 좋습니다.
• 불필요한 중복 요청 방지: 이미 수집한 결과는 중복 호출하지 않도록 캐시, 로그, DB를 적극 활용하세요.
• 검색어 최적화: 지역명+업종, 브랜드명+카테고리 등 복합 쿼리로 품질을 높일 수 있습니다.
• 결과 데이터 검증: 실제 좌표를 지도에 찍어 오류·누락을 점검하고, 데이터 가공 후 시각화를 자주 수행하세요.
• 공식 문서·예제 코드 적극 활용: 네이버 공식 문서, 개발자 포럼, GitHub 오픈소스 예제 등 실무 사례를 적극 참고하세요.

---

참고 자료 및 공식 문서

• 네이버 검색 API 공식 문서(Local)
• 좌표계 변환 pyproj 공식 문서
• 파이썬 requests 공식 문서
• pandas 공식 문서

---

마치며

이 글에서는 네이버 지도 API를 파이썬으로 호출하고, 원하는 장소 데이터를 수집·가공·저장하는 실전 전 과정을 코드와 함께 안내했습니다. 이제 이 데이터를 활용해 Static Map 등 지도 시각화, Streamlit 자동화 앱, 데이터 분석 리포트 등 다양한 확장 작업이 가능합니다.

다음 포스팅에서는 수집한 데이터를 실제 지도에 표시하는 방법(네이버 Static Map API 활용)과 자동화된 시각화 코드 구현을 중심으로 다룰 예정입니다.

---