브라우저만으로 지오코딩 사용하기

보통 지오코딩이라고 하면 Google Maps API나 별도 geocoding 서버를 떠올립니다. 그런데 이 프로젝트는 DuckDB-WASM으로 브라우저 안에 SQL 엔진을 올리고, Overture Maps 주소 데이터를 Parquet 파일로 직접 조회해서 정방향/역방향 지오코딩을 처리합니다. README 기준으로 4억 6,900만 건 이상 주소, 39개국 지원, 지도 클릭 기반 reverse geocoding, H3 타일 기반 조회 최적화까지 포함합니다. (GitHub)

이런 도구는 특히 다음 독자에게 도움이 됩니다. 지도 서비스나 위치 검색 UI를 만드는 프론트엔드 개발자, 지오스페이셜 데이터 처리 흐름을 이해하고 싶은 개발자, 서버 비용 없이 데모나 프로토타입을 만들고 싶은 팀입니다. 공개된 저장소 기준으로 확인되는 범위 안에서, 배경부터 구조, 사용법까지 한 번에 정리해보겠습니다. (GitHub)

GitHub - walkthru-earth/geocoding-playground: Browser-based geocoder powered by DuckDB-WASM and Overture Maps, 469M+ addresses,

 

왜 이 문제가 중요한가

지오코딩은 생각보다 비용과 제약이 큰 문제입니다.

기존 방식은 대체로 외부 API 호출이나 자체 geocoding 서버 운영에 의존합니다. 둘 다 단점이 분명합니다.

• API 비용이 누적된다
  • 주소 검색이 많아질수록 요청 수 기반 과금이 커집니다.
  • 내부 운영 도구나 B2B 서비스에서도 트래픽이 쌓이면 부담이 됩니다.
• 응답 지연이 생긴다
  • 검색할 때마다 네트워크 왕복이 필요합니다.
  • 지도에서 클릭할 때 reverse geocoding까지 붙으면 체감 지연이 더 커집니다.
• 데이터 통제권이 약하다
  • 어떤 주소 데이터가 쓰이는지, 파싱 규칙이 어떻게 적용되는지 직접 제어하기 어렵습니다.
  • 국가별 주소 형식 차이를 세밀하게 다루기 힘든 경우가 많습니다.
• 오프라인성 또는 프라이버시 요구에 약하다
  • 사용자 입력 주소나 좌표가 외부 서버로 전송됩니다.
  • 민감한 위치 데이터를 다루는 환경에서는 이 자체가 제약이 됩니다.
• 프로토타입 만들 때도 인프라가 필요하다
  • 단순 데모를 만들고 싶어도 API 키, 서버, 캐시, 데이터 파이프라인이 따라옵니다.

예를 들어 실무에서는 이런 불편이 자주 나옵니다.

1. 관리자 화면에서 하루 수천 건 주소 정규화를 돌리는데 API 비용이 계속 올라간다.
2. 물류/배달/부동산 서비스에서 국가별 주소 표기 차이 때문에 검색 정확도가 흔들린다.
3. 지도 클릭으로 주소를 보여주는 기능이 필요한데 서버를 추가로 운영해야 한다.
4. PoC 단계인데도 geocoder API 선정, 키 발급, 쿼터 관리부터 해야 한다.
5. 외부 전송이 어려운 환경이라 주소 입력 자체를 서버로 보내기 부담스럽다.

Geocoding Playground가 흥미로운 이유는 이 문제를 **“브라우저 안에서 직접 쿼리한다”**는 방식으로 풀기 때문입니다. README에 따르면 이 프로젝트는 백엔드 없이 Parquet 파일을 HTTP range request로 읽어 주소를 조회합니다. (GitHub)

Geocoding Playground란 무엇인가

Geocoding Playground는 DuckDB-WASM과 Overture Maps 주소 데이터를 이용해, 브라우저 안에서 직접 지오코딩을 수행하는 오픈소스 도구입니다. (GitHub)

쉽게 말하면 이렇습니다.

• 브라우저 안에 DuckDB 엔진이 올라가고
• 주소 데이터는 Parquet 형태로 원격에 있고
• 필요한 부분만 HTTP range request로 가져와
• SQL처럼 조회해서 주소 검색과 역검색을 수행합니다. (GitHub)

기존 방식과의 차이는 분명합니다.

• 기존 geocoding API: “주소를 서버에 보내고 결과를 받는다”
• 이 프로젝트: “브라우저가 직접 데이터를 조회해 결과를 만든다” (GitHub)

즉, 핵심은 지오코딩 엔진이 서버가 아니라 클라이언트에 있다는 점입니다.

핵심 특징

• Forward Geocoding 지원
  • 거리명, 우편번호, 전체 주소로 검색할 수 있습니다. (GitHub)
• Reverse Geocoding 지원
  • 지도 클릭이나 좌표 입력으로 가까운 주소를 찾을 수 있습니다. (GitHub)
• 39개국 지원
  • README 기준 39개국 주소 검색을 지원합니다. (GitHub)
• 국가별 주소 파서
  • NL, US, DE, FR, IT, ES, BR, AU, CA, JP에 대해 전용 파서를 둡니다. 즉, “39개국 전체에 동일 로직”이 아니라 일부 국가는 형식 특화 파서를 더 깊게 적용합니다. (GitHub)
• 3단계 캐싱
  • WASM 초기화, 국가별 prefetch, 타일 LRU 캐시를 사용해 반복 조회를 빠르게 만듭니다. (GitHub)
• 지도 UI 내장
  • MapLibre GL 지도와 H3 타일 오버레이, 결과 마커를 함께 제공합니다. (GitHub)
• Overture 릴리스 선택
  • 네비게이션 바에서 사용 가능한 Overture Maps 릴리스를 바꿔볼 수 있습니다. (GitHub)

실제로 어떤 효과가 있는가

이 프로젝트의 가장 큰 효과는 지오코딩 시스템의 무게중심을 서버에서 브라우저로 옮긴다는 점입니다. (GitHub)

공개된 자료 기준으로 확인되는 효과는 다음과 같습니다.

• 백엔드가 없어도 된다
  • README는 “No backend required”를 명시합니다. 즉, 최소한 데모나 프로토타입 단계에서는 geocoding 서버를 별도로 두지 않아도 됩니다. (GitHub)
• 전체 데이터를 한 번에 내려받지 않는다
  • Parquet 파일을 HTTP range request로 직접 조회하므로, 필요한 조각만 가져오는 구조입니다. 이것이 브라우저에서 수억 건 데이터셋을 다루는 핵심입니다. (GitHub)
• 반복 조회가 빨라진다
  • 프로젝트 문서에는 sub-second queries를 목표로 하는 3단계 캐싱이 설명되어 있습니다. 다만 이것은 README의 프로젝트 설명이며, 모든 브라우저·네트워크 환경에서 동일하게 보장되는 수치라고 단정할 수는 없습니다. (GitHub)
• 초기 로딩과 국가 전환 비용이 분리된다
  • README 기준으로 WASM 초기화는 약 2~4초, 국가 prefetch는 약 3~8초로 설명됩니다. 즉, 한 번의 무거운 전체 로딩보다 “초기화 → 국가 범위 준비 → 실제 조회” 흐름으로 나뉘어 있습니다. (GitHub)

실무적으로 보면 효과가 큰 상황은 아래와 같습니다.

• 사내 운영툴에서 주소 검색이 필요하지만 별도 geocoder 서버를 두기 싫을 때
• 국가별 주소 형식 차이를 직접 제어하고 싶을 때
• 지도 기반 reverse geocoding 데모를 빨리 보여줘야 할 때
• 서버 비용이나 외부 API 의존을 줄이고 싶을 때

동작 원리 / 구조

저장소 구조부터 보면, 이 프로젝트는 pnpm 모노레포입니다. 크게 두 패키지로 나뉩니다. (GitHub)

packages/core/   @walkthru-earth/geocoding-core
apps/playground/ playground

• packages/core
  • 프레임워크 독립적인 TypeScript 라이브러리입니다.
  • DuckDB-WASM 래퍼, 주소 파싱, 검색 알고리즘, 캐싱, 타입 정의를 담습니다. (GitHub)
• apps/playground
  • Svelte 5 기반 UI입니다.
  • 인터랙티브 지도와 결과 화면을 제공하는 데모 앱입니다. (GitHub)

동작 흐름은 README에 단계별로 꽤 명확하게 정리되어 있습니다.

1) WASM 초기화

브라우저가 시작되면 DuckDB-WASM과 필요한 확장들을 로드합니다. README에는 httpfs, spatial, h3 확장을 로드한다고 설명합니다. 이 단계에서 글로벌 타일 인덱스와 매니페스트도 캐시합니다. (GitHub)

2) 국가별 사전 로딩

사용자가 특정 국가를 선택하면, 그 나라의 도시/우편번호/도로명 인덱스를 메모리 테이블로 미리 가져옵니다. 이 단계가 있어서 조회 범위를 처음부터 전 세계 전체로 넓게 잡지 않습니다. (GitHub)

3) 입력 파싱

입력된 문자열을 국가별 파서로 해석합니다. 나라에 따라 주소 형식이 다르기 때문에, 단순 문자열 검색보다 더 구조화된 해석이 들어갑니다. README는 일부 국가에 대해 전용 파서를 둔다고 설명합니다. (GitHub)

4) H3 타일로 범위 좁히기

파싱 결과를 바탕으로 관련 H3 타일 범위를 좁힙니다. 이 단계가 없으면 원격 Parquet 범위를 너무 넓게 읽게 됩니다. 즉, H3가 검색 공간을 빠르게 줄이는 인덱스 역할을 합니다. (GitHub)

5) Parquet 직접 조회

이제 DuckDB가 원격 Parquet를 필터 푸시다운과 함께 조회합니다. 필요한 행만 읽도록 최대한 범위를 줄인 뒤 결과를 만듭니다. README는 이 지점을 “queried directly from Parquet files via HTTP range requests”라고 설명합니다. (GitHub)

6) 타일 캐시 유지

한 번 조회한 타일은 메모리 LRU 캐시에 남겨 반복 요청을 빠르게 처리합니다. README에는 4M address budget이 적혀 있어, 메모리 예산 안에서 주소 데이터를 유지하는 방식임을 알 수 있습니다. (GitHub)

정리하면 흐름은 아래처럼 이해하면 됩니다.

사용자 입력
→ 국가별 파싱
→ H3 타일 후보 축소
→ DuckDB-WASM이 원격 Parquet 직접 조회
→ 결과 반환
→ 자주 본 타일은 캐시에 유지

설치 / 사용 방법

README 기준으로 로컬 실행은 간단합니다. 저장소 루트에서 아래 명령을 실행하면 됩니다. (GitHub)

pnpm install
pnpm dev

그다음 브라우저에서 아래 주소를 엽니다. README는 기본 로컬 경로를 다음처럼 안내합니다. (GitHub)

http://localhost:5173/geocoding-playground/

빌드와 프리뷰도 가능합니다. (GitHub)

pnpm build
pnpm preview

테스트 관련 스크립트도 준비되어 있습니다. 루트와 앱 패키지 설정을 보면 코어 테스트, E2E 테스트, 파서 검증 스크립트가 있습니다. (GitHub)

pnpm test
pnpm test:e2e
pnpm test:validate

기술 스택은 문서와 패키지 설정 기준으로 아래처럼 확인됩니다. (GitHub)

UI: Svelte 5
DB: DuckDB-WASM
Map: MapLibre GL
Geo Index: H3
Data: Overture Maps addresses (Parquet)
Build: Vite 8
Style: Tailwind CSS 4 + DaisyUI 5

앱 패키지에 적힌 의존성 버전도 흥미롭습니다. 예를 들어 공개된 apps/playground/package.json에는 Svelte ^5.55.2, Vite ^8.0.7, MapLibre GL ^5.22.0, H3 ^4.4.0, DuckDB-WASM 1.33.1-dev44.0이 명시되어 있습니다. (GitHub)

자주 쓰는 예시 / 활용 시나리오

1) 주소 검색 데모 만들기

부동산, 물류, 배달, 행정 서비스처럼 “주소 입력 → 지도 표시”가 필요한 앱에서 빠른 데모를 만들 수 있습니다. 서버 없이도 검색 UI를 바로 붙여볼 수 있다는 점이 큽니다. README 기준으로 forward geocoding과 interactive map이 이미 준비되어 있습니다. (GitHub)

2) 지도 클릭으로 주소 확인하기

현장 관리 툴이나 내부 운영 도구에서는 사용자가 지도를 클릭하고 해당 주소를 확인하는 기능이 자주 필요합니다. 이 프로젝트는 reverse geocoding을 기본 기능으로 제공하므로, 해당 UX를 구현하는 데 참고하기 좋습니다. (GitHub)

3) 국가별 주소 파싱 실험

주소 형식은 나라별로 많이 다릅니다. 이 프로젝트는 국가별 전문 파서를 일부 국가에 대해 별도로 둡니다. 따라서 “단순 full-text 검색”이 아니라 국가별 구조화 파싱이 얼마나 중요한지 보여주는 예제로도 좋습니다. (GitHub)

4) 프론트엔드 중심 geospatial 아키텍처 학습

DuckDB-WASM, HTTP range request, H3, Parquet, MapLibre를 한 번에 볼 수 있는 예제는 흔하지 않습니다. “브라우저가 어디까지 데이터 시스템 역할을 할 수 있는가”를 보여주는 교육용 샘플로 가치가 큽니다. (GitHub)

5) 자체 geocoding UI 프로토타이핑

README에 따르면 코어 로직은 @walkthru-earth/geocoding-core로 분리되어 있고 프레임워크 독립적입니다. 즉, Playground UI는 Svelte 5지만, 실제 로직은 다른 프레임워크에도 가져갈 여지가 있습니다. React, Vue, Next.js 같은 환경에서 재사용 가능성을 염두에 둔 구조입니다. (GitHub)

한계 / 주의할 점

이 프로젝트는 인상적이지만, 실무에서 그대로 도입할 때는 몇 가지를 분명히 봐야 합니다.

• 초기 로딩 비용이 있다
  • README 자체가 WASM 초기화와 국가 prefetch 시간을 명시합니다.
  • 즉, 완전히 즉시 반응하는 구조라기보다 “초기 준비 후 빠르게 조회”하는 모델입니다. (GitHub)
• 브라우저 메모리와 환경 제약을 받는다
  • 타일 캐시를 메모리에 유지하는 구조이므로, 저사양 기기나 모바일 환경에서는 한계가 더 빨리 드러날 수 있습니다.
  • README의 4M address budget는 이를 의식한 설계로 보입니다. 이는 문서 기반 해석입니다. (GitHub)
• 지원 국가와 파서 정밀도는 구분해서 봐야 한다
  • 39개국 지원과, 일부 국가 전용 파서 제공은 같은 말이 아닙니다.
  • 즉 “지원은 넓지만 정교한 파싱 로직은 특정 국가에 더 집중되어 있다”고 이해하는 편이 정확합니다. (GitHub)
• 데이터 최신성과 커버리지는 Overture 릴리스에 의존한다
  • 이 프로젝트는 Overture Maps 주소 데이터를 사용하고, 릴리스 선택 기능도 제공합니다.
  • 따라서 결과 품질은 사용하는 릴리스와 데이터 소스 특성의 영향을 받습니다. (GitHub)
• 라이선스와 출처 표기를 확인해야 한다
  • 저장소는 프로젝트 자체 라이선스와 별개로, Overture Maps 주소 데이터의 라이선스 및 국가별 attribution 요구사항을 안내합니다.
  • 실제 서비스 적용 전에는 이 부분을 반드시 검토해야 합니다. (GitHub)
• 프로덕션 geocoder의 모든 요구를 대체한다고 보긴 어렵다
  • Playground는 강력한 데모이자 아키텍처 사례입니다.
  • 대규모 상용 서비스에서는 브라우저 성능, SEO, 캐시 전략, 모바일 UX, 운영 관측성까지 함께 검토해야 합니다.

마무리

Geocoding Playground의 핵심 가치는 단순히 “브라우저에서 지오코딩이 된다”가 아닙니다. 더 중요한 점은 지오코딩을 서버 API 호출 문제로만 보지 않고, 클라이언트 데이터 처리 문제로 다시 설계했다는 데 있습니다. (GitHub)

DuckDB-WASM, Overture Maps Parquet, H3, MapLibre 조합은 “지도 검색도 이제 브라우저 안에서 꽤 많은 일을 할 수 있다”는 사실을 보여줍니다. 특히 백엔드 없이도 수억 건 규모 주소 데이터를 다룰 수 있게 만든 구조는, 프론트엔드와 데이터 엔지니어링의 경계가 어떻게 흐려지고 있는지를 잘 보여줍니다. (GitHub)

결국 이 도구는 지오코딩 데모를 빠르게 만들고 싶은 개발자, 브라우저 기반 데이터 처리 아키텍처를 탐구하는 개발자, 외부 geocoding API 의존을 줄이는 방법을 고민하는 팀에게 특히 유용합니다.

• 백엔드 없이 브라우저에서 직접 지오코딩을 수행하는 구조가 핵심입니다. (GitHub)
• DuckDB-WASM + Parquet + HTTP range request + H3 조합으로 수억 건 주소 데이터를 다룹니다. (GitHub)
• 39개국 지원, forward/reverse geocoding, MapLibre 기반 지도 UI가 이미 갖춰져 있습니다. (GitHub)
• 국가별 주소 파싱과 다단계 캐싱이 정확도와 속도를 받쳐줍니다. (GitHub)
• 실무 적용 전에는 초기 로딩, 브라우저 자원 제약, 데이터 라이선스를 함께 검토해야 합니다. (GitHub)