지오코딩 vs 장소 검색은 위치 쿼리에서 가장 먼저 나눠야 하는 역할입니다. 한 호출은 지리적 대상을 해석하고, 다른 호출은 후보 장소를 발견합니다. 주소, 좌표 또는 장소 식별자는 지오코딩에 해당합니다. 비즈니스, 랜드마크 또는 기타 이름이 있는 장소를 찾는 요청은 장소 검색에 해당합니다. 그다음 공간 쿼리가 애플리케이션이 이미 보유한 지오메트리를 검증하고, 벡터 검색은 의미를 일치시킵니다. 다만 벡터 검색만으로는 레코드가 가까이에 있거나 적격하다는 사실을 증명하지 못합니다.
각 위치 쿼리는 무엇에 답하나요?
각 방법은 서로 다른 질문에 답하며, 한 공급업체가 이를 같은 제품군 메뉴에 묶어 놓았다고 해서 차이가 사라지지는 않습니다. 지오코딩은 정체성을 해석합니다. 장소 검색은 공급업체 인덱스나 비공개 인덱스에서 후보를 발견합니다. 공간 쿼리는 애플리케이션이 이미 저장하는 레코드에 기하학적 관계를 적용합니다. 벡터 검색은 의미상 가까운 임베딩을 가진 레코드를 가져옵니다. 실제 운영 의사결정에서는 질문 자체가 정하는 순서로 이러한 답을 둘 이상 조합해야 하는 경우가 많습니다.
| 쿼리 | 역할 | 일반적인 입력 | 일반적인 출력 |
|---|---|---|---|
| 지오코딩 | 하나의 위치 해석 | 도로명 주소 또는 좌표 | 좌표, 정규화된 주소 또는 안정적인 식별자 |
| 장소 검색 | 이름이 있는 장소 발견 | 텍스트, 카테고리, 영역 | 후보 장소 집합 |
| 공간 쿼리 | 지오메트리 검증 | 거리 내, 폴리곤 내부, 교차, 최근접 | 관계를 만족하는 레코드 |
| 벡터 검색 | 의미 일치 | “첫 만남에 적합한 조용한 장소” 같은 문구 | 설명이 유사한 레코드 |
네 카드는 해석, 발견, 지리 필터링, 의미 일치를 구분합니다. 각 카드는 입력과 출력을 연결합니다. 주소와 좌표, 카테고리와 관심 지점, 기하학적 관계와 일치하는 레코드, 개념과 의미적 이웃입니다. 도로명 주소, 좌표, 카페 쿼리, 폴리곤 안의 장소 수는 그림의 예시 라벨입니다. 이 라벨은 Kaleidr 인덱스를 대상으로 실행한 실시간 쿼리 결과가 아닙니다.
표가 선택 규칙입니다. 질문이 아니라 엔드포인트 이름에서 시작하는 팀은 지오코더에게 추천을 요구하거나 벡터 인덱스에게 포함 여부 테스트를 요구하게 됩니다. 두 실수 모두 시스템이 실행하지 않은 질문에 자신 있게 답하는 결과를 만듭니다. 이 가이드의 나머지 부분에서는 네 역할을 분리한 채 유지한 다음, 파이프라인의 어디에서 결합해야 하는지를 보여 줍니다.
어떤 쿼리가 질문에 맞나요?
요청의 첫 문장이 대개 방법을 알려 줍니다. “이 주소는 어디인가요?”는 지오코딩으로 시작합니다. “이 텍스트나 카테고리에 맞는 장소는 어디인가요?”는 장소 검색으로 시작합니다. “우리 레코드 중 이 지리적 관계를 만족하는 것은 무엇인가요?”는 공간 쿼리로 시작합니다. “이 문구와 비슷한 의미의 레코드는 무엇인가요?”는 벡터 검색의 경우이며, 반드시 엄격한 지리적 한계와 비즈니스 한계를 먼저 적용한 뒤에 사용해야 합니다. 이런 질문이 섞인 요청에는 단일 승자가 아니라 하이브리드가 필요합니다.
| 질문 | 여기서 시작 |
|---|---|
| 이 주소는 어디에 있거나, 이 좌표의 주소는 무엇인가요? | 역지오코딩을 포함한 지오코딩 |
| 이 텍스트, 카테고리 또는 근처 의도에 맞는 이름 있는 장소는 무엇인가요? | 장소 검색 |
| 우리 레코드 중 이 거리, 폴리곤 또는 코리도 안에 있는 것은 무엇인가요? | 공간 쿼리 |
| 이 문구와 유사한 설명은 무엇인가요? | 적격 집합 내부의 벡터 검색 |
| 승인된 장소 중 상품이 있고 우회가 적은 곳은 어디인가요? | 비즈니스 필터, 이후 공간 또는 경로 계산, 이후 순위 |
트리는 호출자가 답하려는 질문에서 시작한 뒤, 하나의 주소 해석, 비즈니스 발견, 호출자 자체 레코드의 지리적 필터링, 의미가 유사한 레코드 찾기로 분기합니다. 하단의 다섯 번째 띠는 하나의 쿼리로 충분하지 않을 때 네 방법을 결합합니다. 예시 주소, 카페 카드, 1km 반경, 인용된 데이트 장소 문구는 그림 라벨입니다. 체크 표시는 각 방법의 역할을 설명하며, 측정된 품질 점수가 아닙니다.
하이브리드는 AI 지도 도우미에서 흔한 기본 사례이지, 나중 버전을 위해 남겨 둔 예외가 아닙니다. “20 W 34th St 근처 커피”도 근처 검색을 실행하기 전에 주소를 먼저 해석해야 합니다. “호텔 근처에서 9시 이후에도 여는 조용한 카페”는 그 해석 위에 비즈니스 필터와 의미적 선호를 추가합니다. 아래 파이프라인 섹션에서는 검토자가 테스트할 수 있는 순서로 이러한 단계를 유지합니다.
지오코딩은 무엇을 해석하나요?
지오코딩은 텍스트 위치를 지리적 표현으로 변환하고, 역지오코딩은 좌표나 장소 식별자를 읽을 수 있는 주소로 되돌립니다. Google의 Geocoding API 개요는 주소, 위도와 경도 또는 Place ID를 입력받아 주소를 좌표와 Place ID로 변환하거나, 좌표 또는 Place ID를 주소로 변환하는 서비스로 정의합니다 (Google, 2026). 같은 개요에서는 정방향 지오코딩 예시로 “1600 Amphitheatre Parkway, Mountain View, CA”를 사용하고, 역지오코딩 사용 사례로 배송과 픽업을 들고 있습니다. 성공한 호출의 출력은 지도에 배치할 수 있는 대상이지, 순위가 매겨진 비즈니스 집합이 아닙니다.
제품 경계는 변하고 있지만, 여전히 이름 붙여야 할 것은 검색 역할입니다. Google의 Geocoding API v4 개요는 정방향 지오코딩, 역지오코딩, 장소 지오코딩과 함께 주소, Place ID 또는 좌표를 받는 목적지 검색 메서드를 나열합니다 (Google, 2026). 또한 정식 제공, 프리뷰, 실험적 채널을 구분하고, 일반 제공 경로에 없는 목적지 기능에는 실험적 채널을 사용하라고 안내합니다. 목적지 조회는 애플리케이션이 이미 해석한 위치를 보강할 수 있습니다. 그렇다고 장소 발견 인덱스가 되는 것은 아니며, 실험적 채널이라고 해서 모든 필드가 프로덕션 계약에 준비되었다는 뜻도 아닙니다.
애플리케이션이 주소를 지도에 표시하거나, 저장 전에 정규화하거나, 지도를 중앙에 맞추거나, 장치 위치를 역지오코딩하거나, 후속 쿼리 전에 배송 지점을 해석해야 한다면 지오코딩이 올바른 도구입니다. 지오코딩은 최적의 근처 레스토랑을 선택하지 않고, 비공개 재고를 읽지 않으며, 비공개 서비스 영역 폴리곤을 테스트하지 않고, 고객 의도에 따라 결과를 순위화하지 않습니다. 이러한 역할은 대상이 존재한 후에 시작됩니다. 지도에 장소 표시하기는 성공적인 해석 뒤 주소를 마커로 바꾸는 단계를 설명합니다.
지오코딩 vs 장소 검색은 어떻게 다른가요?
장소 검색은 레스토랑, 매장, 역, 랜드마크 및 기타 관심 지점처럼 이름이 있는 지리 엔터티를 발견합니다. Mapbox는 현재 Geocoding API에서 제품 경계를 명확히 나눕니다. 이 API는 정방향과 역지오코딩을 수행하며, Geocoding v6 API는 더 이상 관심 지점 데이터를 제공하지 않습니다 (Mapbox, 2026). Mapbox는 관심 지점 검색을 Search Box API로 안내하며, 이 API는 주소, 장소, 관심 지점에 대한 대화형 및 단독 쿼리와 카테고리 검색을 지원합니다 (Mapbox, 2026). 엔드포인트 제품군은 한 공급업체의 것입니다. 역할은 여전히 두 개입니다.
Google의 현재 Places API도 장소 검색 내부에서 같은 분리를 합니다. Text Search (New)는 텍스트 문자열에 대해 장소를 반환하고, 문서 예시에 “shoe stores near Ottawa”와 “123 Main Street”가 포함되어 있어 주소 형태 문자열이 장소 검색 호출에 들어갈 수 있습니다 (Google, 2026). Nearby Search (New)는 하나 이상의 place type을 받아 지정된 영역 안의 일치 장소를 반환합니다 (Google, 2026). 따라서 문자열이 주소라면 Text Search가 지오코딩처럼 보일 수 있고, 영역이 원이라면 Nearby Search가 공간 쿼리처럼 보일 수 있습니다. 그래도 결과는 그 공급업체 인덱스의 후보 집합입니다. 영업 상태, 재고, 권한, 이동 시간은 이후 검사입니다. 같은 Text Search 페이지는 장소로 표현되지 않은 우편 주소 형식 등 모호한 쿼리를 위한 서비스가 아니라고도 설명합니다.
왼쪽 패널은 하나의 주소가 어디에 있는지 묻고 단일 위치 정체성을 표시합니다. 이 패널의 주소와 좌표는 Kaleidr forward-geocode 참조의 샘플과 일치하며, 오른쪽의 카페 이름, 거리, 별점은 예시 라벨이지 실시간 장소 검색 응답이 아닙니다. 하단은 “coffee near 20 W 34th St”를 주소 지오코딩 후 커피 검색으로 이어지는 과정으로 보여 줍니다. 오른쪽의 핵심 문구는 결과를 후보 집합이라고 부르며, 이는 적격성과 순위화 이전에 멈추는 올바른 지점입니다.
| 지오코딩 | 장소 검색 | |
|---|---|---|
| 핵심 역할 | 하나의 위치 해석 | 후보 장소 발견 |
| 일반 입력 | 주소, 좌표, 장소 식별자 | 텍스트, 카테고리, 근처 영역 |
| 일반 출력 | 해당 위치에 대한 하나 또는 여러 해석 | 인덱스에서 나온 순위 후보 목록 |
| 다음 단계 | 지도, 공간 쿼리 또는 경로 | 필터, 보강, 순위화 또는 경로 계산 |
| 비공개 재고 | 아니요 | 아니요 |
앵커가 주소이고 대상이 카테고리라면 견고한 애플리케이션은 둘 다 사용합니다. “20 W 34th St”를 지오코딩하고, 해석된 지점 근처에서 커피를 검색한 뒤, 도보 시간을 계산하고 적격 상태가 유지된 장소만 순위화합니다. 근처 장소 지도는 두 번째 단계의 발견 화면입니다. 공급업체의 순서는 검색 편의입니다. 제품의 순서는 이후의 의사결정입니다.
공간 쿼리는 무엇을 검증하나요?
공간 쿼리는 애플리케이션이 이미 보유한 레코드를 지오메트리 간의 관계로 필터링합니다. 일반적인 관계는 일정 거리 내, 폴리곤 내부, 교차, 포함, 최근접 이웃입니다. 레코드와 지오메트리는 쿼리 전에 이미 존재합니다. 쿼리는 그 레코드 중 어떤 것이 관계를 만족하는지 묻습니다. 장소 검색 API는 다른 질문에 답합니다. 후보 집합이 호출자 테이블이 아니라 공급업체 인덱스에서 오기 때문입니다.
패널은 일정 거리 내, 폴리곤 내부, 영역과 교차하는 경로, 최근접 요소를 보여 줍니다. 1km 반경, 서비스 영역 외곽선, 거리 배지는 예시 지오메트리이며 측정된 서비스 영역이 아닙니다. 최근접 패널은 한 요소를 제외된 것으로 표시합니다. 이 제외는 이후 적격성 검사 예시입니다. 거리 술어 자체만으로 장소가 영업 중인지 테스트하지 않습니다.
PostGIS는 ST_DWithin을 두 지오메트리가 지정된 거리 안에 있는지를 테스트하는 함수로 정의하며, 이 호출에는 지오메트리에서 사용 가능한 공간 인덱스를 활용하는 경계 상자 비교가 포함됩니다 (PostGIS, 2026). geography 타입에서는 거리가 미터 단위입니다. 따라서 geography 열이 있는 매장 테이블은 “5km 이내”를 언어 모델이 해석해야 할 문장이 아니라 술어로 유지할 수 있습니다.
SELECT store_id, name
FROM stores
WHERE ST_DWithin(stores.geog, user_location, 5000);
포함 여부도 같은 종류의 술어입니다. ST_Within은 첫 번째 지오메트리의 모든 점이 두 번째 안에 있고 내부가 한 점을 공유할 때 true를 반환하며, 사용 가능한 공간 인덱스도 활용합니다 (PostGIS, 2026). ST_Within(A, B)는 ST_Contains(B, A)의 역입니다. “이 주소가 서비스 영역 안에 있나요?”라는 배송 질문은 지오코딩, 포함 테스트, 운영 규칙의 순서입니다. 벡터 인덱스는 폴리곤을 대체하지 않으며, 공개 장소 검색도 회사가 직접 그린 서비스 영역 지오메트리를 대체하지 않습니다.
인덱스에 대한 메모는 아키텍처 제약이지 튜닝 각주가 아닙니다. 인덱스를 사용할 수 없는 거리 표현식은 같은 테이블의 ST_DWithin보다 훨씬 많은 행을 비교합니다. 위치 인식 도우미의 실용적 규칙은 모델이 집합을 보기 전에 지리적으로 필터링하는 것입니다. 큰 카탈로그 중 지오메트리를 만족할 수 있는 비율이 작다면 언어 모델에는 그 일부와 나머지가 제외된 이유를 전달해야 합니다. 나머지까지 보내면 술어가 이미 제외한 레코드에 컨텍스트를 낭비하게 됩니다.
벡터 검색은 무엇을 일치시키나요?
벡터 검색은 벡터 공간에서 쿼리에 가까운 임베딩을 가진 레코드를 가져옵니다. 이 작업에 흔히 쓰이는 Postgres 확장 pgvector는 기본적으로 정확한 최근접 이웃 검색을 수행하며, 근사 검색을 위해 HNSW 또는 IVFFlat 인덱스를 추가할 수 있습니다 (pgvector, 2026). 같은 문서는 L2 거리, 내적, 코사인 거리 및 기타 측정값을 나열합니다. 정확 검색이 재현율의 기준선입니다. 근사 인덱스는 재현율 일부를 속도와 바꾸며, 인덱스가 생성된 뒤에는 쿼리가 다른 이웃을 반환할 수 있습니다. 이 특성은 정확 검색을 사용한 시제품과 인덱스를 사용하는 프로덕션 쿼리를 비교할 때 중요합니다.
벡터 검색은 요청의 단어와 레코드의 단어가 다를 때 비용을 지불할 가치가 있습니다. “조도가 낮은 아늑한 와인 바”라는 설명은 문자열이 일치하지 않아도 “첫 만남에 적합한 조용한 장소”에 유용한 이웃이 될 수 있습니다. 라이선스가 텍스트 임베딩을 허용하는 경우 장소 설명, 편의시설 메모, 목적지 소개문이 일반적인 입력입니다. 알려진 브랜드, 매장 번호, 공항 코드, 명시적 카테고리는 일반적으로 키워드 또는 구조화 검색이 더 적합합니다. 임베딩은 운영해야 할 시스템을 하나 추가하므로, 의미상 누락이 실제로 있을 때 추가해야 합니다.
벡터 유사도에는 지리적 거리, 경로 시간, 서비스 영역 포함 여부, 현재 재고, 영업시간, 권한, 임베딩된 텍스트가 아직 사실인지 여부가 기록되지 않습니다. 임베딩 공간에서 가까운 이웃이 호출자로부터 수백 마일 떨어져 있을 수 있습니다. 길 건너의 장소가 의미적으로는 낮은 일치도이지만 운영상 올바른 답일 수도 있습니다. 두 결과는 충돌하지 않습니다. 서로 다른 공간에서 나온 결과이며, 파이프라인은 어떤 공간이 후보를 거절할 수 있는지 명시해야 합니다.
지리적 거리와 벡터 거리는 왜 다른가요?
두 시스템 모두 “거리”라는 단어를 쓰기 때문에 대상이 바뀌는 것이 가려집니다. 지리적 거리는 지구 위 또는 경로를 따른 분리입니다. 직선 길이, 도보, 자동차 이동, 포함 결과가 이에 해당합니다. 벡터 거리는 임베딩 공간에서의 분리입니다. 코사인 거리, 유클리드 거리 또는 내적 점수가 이에 해당합니다. 벡터 거리가 작다고 두 장소가 지리적으로 가깝다는 뜻은 아닙니다. 도보 거리가 짧다고 두 설명의 의미가 같아지는 것도 아닙니다.
왼쪽 패널은 물리적 분리를 측정하고 두 라벨 장소 사이의 샘플 도보 이동을 보여 줍니다. km와 분 배지는 예시 라벨이며 계산된 경로가 아닙니다. 오른쪽 패널은 임베딩 다이어그램에 단어를 놓고 coffee가 train에서 의미상 멀다고 표시합니다. 코사인 표시는 두 공간을 설명하는 예시이며 Kaleidr 인덱스에서 측정한 임베딩이 아닙니다. 중앙 라벨이 그림의 핵심입니다. 같은 “거리”라는 단어가 두 양을 모두 가리킵니다.
이 명칭 충돌은 제품 문구에도 나타납니다. 화면의 “가장 가까운”이 임베딩 인덱스에서 가장 가까운 항목, 직선거리 미터 기준 가장 가까운 항목, 또는 우회 시간이 가장 적은 항목을 의미할 수 있습니다. 세 순서는 자주 달라지므로 인터페이스는 어떤 양인지 이름을 붙여야 합니다. 순위 결정는 둘 이상을 사용할 수 있지만 코사인 score를 km 값에 더해 그 합을 하나의 거리처럼 다뤄서는 안 됩니다.
하이브리드 파이프라인은 작업 순서를 어떻게 정해야 하나요?
프로덕션 위치 검색은 보통 파이프라인입니다. 요청이 대상, 카테고리, 지리적 제한, 비즈니스 규칙, 선호를 섞기 때문입니다. 한 가지 실용적인 순서는 요청 해석, 앵커 해석, 후보 검색, 공간 필터 적용, 비즈니스 적격성 적용, 그다음 적격 집합 안에서만 의미 유사도 사용입니다. 경로 계산과 기타 보강은 살아남은 후보에 실행합니다. 순위은 그 후보를 정렬합니다. 설명과 지도 액션은 필터가 사용한 것과 같은 식별자를 사용합니다. 공간 컨텍스트 엔지니어링은 이 파이프라인 중 무엇이 언어 모델에 도달할 수 있는지에 대한 짝이 되는 질문입니다.
단계에는 각 단계를 담당하는 방법이 표시되어 있습니다. 지오코딩, 장소 검색, 공간 쿼리, 비즈니스 데이터, 벡터 검색, 그리고 보강, 순위, 지도 액션입니다. 장소 이름, 별점, 점수 막대, “100K+” 퍼널, “top 3–5” 주장은 예시 라벨입니다. 이 그림은 작업 순서를 설명하는 참조 스케치이며, Kaleidr benchmark나 request 형식이 아닙니다. 비즈니스 필터 열의 “현재 영업 중”, 최소 평점 같은 샘플 규칙은 공개 장소 인덱스가 아니라 host 데이터에 속합니다.
순서는 재현율을 바꿉니다. 임베딩 인덱스 전체를 먼저 검색한 뒤 짧은 의미 목록에 지리 조건을 적용하면, 그 짧은 목록에 들어오지 못한 유효한 로컬 장소를 놓칠 수 있습니다. 먼저 엄격한 지리 조건과 엄격한 비즈니스 규칙으로 후보 집합을 제한하고, 그 집합 안에서 의미에 따라 순위하면 경계를 유지할 수 있습니다. 데이터베이스가 두 필터를 하나의 쿼리에서 적용할 수 있어도 원칙은 같습니다. 의미 유사도가 필수 지리 제한을 지워서는 안 됩니다.
pgvector의 filtering 설명이 실무 경고입니다. 근사 인덱스에서는 필터가 index scan 뒤에 적용되며, 문서의 예시는 기본 HNSW ef_search가 40일 때 행의 10%에 해당하는 조건으로 평균 약 4개 행만 남는 상황을 보여 줍니다. 이 부족 문제를 위해 문서가 소개하는 iterative index scans는 충분한 행이 남을 때까지 계속됩니다. 팀은 보기 좋은 쿼리가 곧 프로덕션 쿼리라고 가정하지 말고 현실적인 데이터에서 filtered 재현율을 테스트해야 합니다.
왜 엄격한 필터를 유사도보다 먼저 실행해야 하나요?
검색은 어떤 후보가 고려 대상에 들어갈 수 있는지를 묻습니다. 순위은 유효한 후보를 어떤 순서로 보여 줄지를 묻습니다. 둘을 섞으면 문을 닫았거나 권한이 없거나 재고가 없는 장소가 편리하거나 의미적으로 가깝다는 이유로 이길 수 있습니다. Kaleidr의 장소 순위 가이드는 권한, 가용성, 필수 기능, 서비스 영역을 약한 패널티가 아니라 scoring 이전의 필터로 둡니다 (Kaleidr, 2026). 패널티는 큰 편의성 항목에 질 수 있습니다. 필터는 그렇지 않습니다.
왼쪽 열은 네 개의 boolean gate를 나열하고 잘못된 후보를 제거하는 것으로 끝납니다. 오른쪽 열은 조용함, 가족 친화적, 업무 친화적에 대한 샘플 유사도 점수를 보여 주며 통과한 장소만 순위화합니다. 사진과 세 점수는 예시 라벨이며, 측정된 평가나 Kaleidr 점수가 아닙니다. 화살표는 순서를 나타냅니다. 적격성, 그다음 유사도입니다.
엄격한 gate는 boolean으로 유지됩니다. 권한 있음, 재고 있음, 도착 시 영업 중, 서비스 영역 내부는 조건이지 가중치가 아닙니다. 의미 신호는 점수로 유지할 수 있으며 gate가 남긴 장소에 적용합니다. 같은 분리는 필수 접근성 규칙이나 tenant 경계에도 적용됩니다. 필수 사실이 unknown이면 unknown으로 남아야 합니다. 사용할 수 없는 조회를 false로 처리하면 재고 조회 실패를 자신 있게 “품절”로 바꾸게 되며, 이는 다른 종류의 더 나쁜 오류입니다.
왜 “가는 길” 검색은 반경 검색이 아닌가요?
“내 근처”와 “집에 가는 길”은 서로 다른 지오메트리를 설명합니다. 출발점 주변의 반경은 시작점에서 일정 거리 안의 장소를 반환하며, 진행 방향과 반대인 장소도 포함합니다. route-corridor 쿼리는 경로 계산 서비스가 이미 계획한 이동에 우회가 적게 추가되는 장소를 반환합니다. 질문이 실제로 방사형이라면 직선거리는 정당한 필터입니다. 결정이 여정에 의존하면 직선거리는 잘못된 양입니다. 직선으로 2km가 자동차로는 긴 경로일 수 있고, 직선거리가 더 길어도 실제 이동은 더 짧을 수 있습니다.
왼쪽 패널은 단순 반경이며 1마일 링 안팎의 샘플 약국을 보여 줍니다. 오른쪽 패널은 직장에서 집까지의 샘플 경로를 따라가며 약국에 우회 시간을 붙입니다. 마일 값, 우회 시간, 장소 이름은 예시 라벨이며 실시간 경로가 아닙니다. 그림의 핵심은 관계입니다. 낮은 경로 deviation은 출발점 주변의 원과 같은 술어가 아닙니다.
경로 계산 서비스가 우회를 계산하고 순위 결정가 그 결과를 받아야 합니다. 언어 모델이 시간을 추정하면 서비스가 방금 반환한 경로와 충돌하는 경우가 있습니다. 경로 호출은 해석과 후보 선택 뒤에 위치합니다. 경로 호출은 장소 검색이 아니며, 경로가 없으면 지도에 추측선을 그리지 말고 보이는 실패로 남겨야 합니다.
Kaleidr는 이 파이프라인의 어디에 들어가나요?
Kaleidr의 공개 Platform API는 비공개 비즈니스 인덱스가 아니라 검색 상자 또는 From/To 필드를 위한 forward-geocode 엔드포인트를 제공합니다. GET /retrieval/geocode/forward는 장소 이름, 번지수를 포함한 도로명 주소, 또는 입력된 위도와 경도로 q를 받으며, 함께 사용하는 선택적 near_lat와 near_lng, limit, 이동 mode도 받습니다 (Kaleidr, 2026). 같은 참조는 호출자가 이미 가진 좌표 사이의 경로도 문서화하며 driving, walking, cycling, transit 프로필을 지원합니다. 계획할 수 없는 경로는 경로 대신 body에 오류가 포함된 성공 HTTP 상태로 돌아옵니다. 결과에는 호출자가 전달해야 하는 attribution이 포함되며, 도로명 주소 결과에는 데이터 업데이트를 넘어 안정적으로 유지되는 식별자가 포함될 수 있습니다. 빈 results 목록은 내부 조회 실패를 포함해 표시할 것이 없음을 의미하므로, 주소가 잘못되었다는 증거가 아닙니다.
문서화된 파라미터에는 고객의 비공개 카탈로그가 포함되지 않습니다. 공개 지오코딩이 같은 지도에 올라가 있다고 해서 재고 시스템이 되지는 않습니다. 비공개 매장이나 재고가 필요한 호출자는 해당 시스템을 직접 읽은 뒤 안정적인 식별자로 해석된 장소와 연결해야 합니다. geocode 응답은 공개 대상이고, 비즈니스 레코드는 비즈니스 레코드로 남습니다.
Place detail에는 현재의 후속 경로가 있으며, 새 통합을 오래된 경로에 구축해서는 안 됩니다. 엔드포인트 참조는 GET /retrieval/poi/enrich를 deprecated로 표시하고 새 작업을 POST /spot으로 안내합니다. 이 호출은 특정 지점에 무엇이 있는지 답하고 설명 콘텐츠와 사진을 추가할 수 있습니다. deprecated 경로는 2027-01-15 이후 제거될 수 있습니다.
보강은 여전히 비공개 적격성을 결정하지 않습니다. 공개 소스의 영업시간, 사진, 카테고리는 해당 소스가 요구하는 attribution을 포함한 공개 사실입니다. 재고, 계정 권한, 고객이 그린 서비스 영역은 그것을 소유한 시스템에 남습니다. 비즈니스 데이터에 기반한 Spatial AI는 이 경계에 대한 가이드입니다.
왼쪽 열은 주소와 이름 있는 장소를 비공개 매장, 재고, 서비스 영역과 분리합니다. 가운데 열은 Kaleidr 정방향 지오코딩, place-detail 단계, host 자체 공간 데이터베이스와 비즈니스 시스템을 표시합니다. place-detail 상자는 현재 POST /spot으로 문서화된 역할입니다. 오래된 enrich 엔드포인트는 deprecated 전신이며, 새 통합의 시작점이 아닙니다. 오른쪽 열은 검색 이후를 보여 줍니다. 알려진 좌표 사이의 경로, 적격 장소 순위, 설명, 지도 액션입니다. 그림의 경고는 엔드포인트 참조와 일치합니다. 공개 geocode 또는 place API는 호출자의 비공개 위치, 재고, 서비스 영역을 인덱싱하지 않습니다.
조직별 데이터는 지도가 아니라 플랜 경계를 따릅니다. Kaleidr 계정 문서에서는 조직 자체의 비즈니스 데이터를 AI 응답용으로 업로드하는 기능이 Enterprise 전용이며, 응답이 업로드한 데이터를 활용하도록 하는 key scope도 Enterprise 전용이라고 설명합니다 (Kaleidr, 2026). 현재 공개 엔드포인트 참조에는 범용 벡터 검색 엔드포인트가 문서화되어 있지 않습니다. 자체 설명에 대한 의미 검색이 필요한 팀은 해당 인덱스를 host 또는 Enterprise 설계의 일부로 취급하고, 이 글에서 인용하지 않은 경로를 호출하기보다 현재 계약을 확인해야 합니다. map-aware AI 도우미 구축 방법은 검증된 장소 식별자 이후의 지도 액션을 다룹니다.
팀은 무엇을 따로 측정해야 하나요?
각 계층은 서로 다른 방식으로 실패하며, 단일 관련도 점수는 어느 계층이 실패했는지 숨깁니다. 지오코딩은 모호한 주소, 누락된 호수나 단위, 뒤바뀐 좌표, 도로 수준에 그친 매치에서 실패합니다. 장소 검색은 공급업체의 커버리지, 카테고리, 최신성이 제품과 맞지 않을 때 실패합니다. 공간 쿼리는 잘못된 지오메트리, 맞지 않는 좌표 참조, 운영 현실과 어긋난 폴리곤에서 실패합니다.
벡터 검색은 약한 임베딩, 오래된 텍스트, 필터 뒤 너무 적은 결과를 반환하는 근사 인덱스에서 실패합니다. 비즈니스 데이터는 재고가 unknown이거나, 레코드 권한이 없거나, 영업시간이 오래된 경우 실패합니다. 유용한 로그는 계층을 이름으로 기록합니다. “Search failed”만으로는 부족합니다.
각 계층을 그 역할에 맞춰 평가한 다음 결정을 평가합니다. 지오코딩에는 매치 품질과 안정적인 식별자가 필요합니다. 장소 검색에는 후보 재현율, 카테고리 precision, 오래된 장소 비율이 필요합니다. 공간 쿼리에는 기하학적 정확성과 쿼리가 인덱스를 사용했다는 증거가 필요합니다. 벡터 검색에는 의미 관련성과 exact-search 기준 대비 filtered 재현율이 필요합니다. end-to-end 검사는 적격 장소를 가져왔는지, no-result가 정직한 결과였는지, 액션이 필터가 승인한 식별자를 사용했는지 확인합니다. 권한 실패나 포함 실패가 평균 click-through rate 안에 묻혀서는 안 됩니다.
스택은 어디서 시작해야 하나요?
사용자가 요구한 조건을 증명할 수 있는 방법을 선택합니다. 지오코딩은 대상이 어디 있는지 증명합니다. 장소 검색은 해당 인덱스에서 어떤 알려진 장소가 텍스트, 카테고리 또는 영역과 일치하는지 증명합니다. 공간 쿼리는 애플리케이션이 보유한 레코드에 대한 기하학적 관계를 증명합니다. 벡터 검색은 의미 유사성을 증명하며, 엄격한 필터가 남긴 집합 안에서만 사용합니다. 비즈니스 시스템은 현재 사실을 증명합니다. 경로 계산 서비스는 여정을 증명합니다. 순위 결정는 남은 것을 정렬합니다. 언어 모델은 그 결과를 설명해야 하며, 거리, 포함 테스트, 재고 수량의 정보원이 되어서는 안 됩니다.
공개 장소 발견이 역할이라면 공개 장소 데이터가 올바른 출처입니다. 비공개 매장, 재고, 적격성은 그것을 소유한 시스템에 남고, 안정적인 식별자가 공급업체의 place, 재고 위치, 지도 마커를 연결합니다. 의미 유사성이 지리적 경계를 지울 수 없고, 반경은 “가는 길” 질문에 답하지 못합니다. 조직별 데이터에서 검색을 실행해야 한다면 Kaleidr Enterprise를 살펴보고, 위에서 인용한 forward-geocode, spot, 경로 계약은 Platform API 엔드포인트를 확인하세요.
참고: Kaleidr는 창작 및 개발 워크플로 전반에서 이미지 생성, 콘텐츠 개선, 리서치에 AI 지원 도구를 사용합니다.
자주 묻는 질문
지오코딩과 장소 검색의 차이는 무엇인가요?
지오코딩은 주소, 좌표 또는 알려진 장소 참조를 지리적 정체성으로 해석합니다. 장소 검색은 텍스트, 카테고리 또는 근처 영역과 일치하는 비즈니스, 랜드마크, 역 및 기타 이름 있는 장소를 발견합니다. 하나는 대상을 반환하고, 다른 하나는 후보를 반환합니다.
관심 지점 검색은 지오코딩과 같은가요?
아니요. 일부 공급업체 API는 주소와 장소 쿼리를 모두 받을 수 있습니다. 이와 달리 Mapbox의 Geocoding v6 API는 더 이상 관심 지점 데이터를 전혀 제공하지 않습니다. 관심 지점 검색은 후보를 발견하고, 지오코딩은 위치를 해석합니다.
공간 쿼리란 무엇인가요?
공간 쿼리는 일정 거리 내, 폴리곤 내부, 교차, 최근접 이웃 같은 기하학적 관계로 지리 레코드를 필터링합니다. 레코드와 지오메트리는 이미 애플리케이션에 속합니다. 술어는 결정적입니다.
벡터 검색이란 무엇인가요?
벡터 검색은 query 임베딩에 가까운 임베딩을 가진 레코드를 가져옵니다. 의미와 원문 텍스트에 정확히 일치하지 않는 표현을 다룰 때 유용합니다. 그러나 거리, 포함 여부, 적격성을 증명하지는 않습니다.
벡터 검색이 공간 쿼리를 대체할 수 있나요?
아니요. 임베딩 공간의 유사성은 지리적 거리, 포함, 경로 적합성, 서비스 영역 소속을 증명하지 않습니다. 지리적 사실에는 공간 술어를 사용하고, 그 술어가 허용한 집합 안에서 의미 관련성을 위해 벡터 검색을 사용하세요.
벡터 검색 전에 지리 조건으로 집합을 필터링해야 하나요?
네, 지리가 엄격한 제한이라면 그래야 합니다. 글로벌 임베딩 인덱스를 먼저 검색한 다음 짧은 목록에서 위치를 확인하면 그 목록에 들어오지 못한 유효한 로컬 장소를 놓칠 수 있습니다. 구현은 데이터베이스와 인덱스가 정합니다. 경계 자체는 바뀌지 않습니다.
근처 검색 전에 지오코딩해야 하나요?
네, 앵커가 주소나 다른 미해석 위치라면 그렇습니다. 앵커를 해석한 뒤 그 지점 주변에서 place 검색 또는 공간 쿼리를 실행합니다. 앵커 없는 카테고리 검색은 이미 장소 검색 질문입니다.
제품은 Places API와 자체 데이터베이스 중 무엇을 써야 하나요?
커버리지, 라이선스, attribution이 제품에 맞는 경우 공개 발견에는 Places API를 사용합니다. 자사 매장, 재고, 비공개 시설, 적격성, 현재 비즈니스 상태에는 제품 자체 데이터베이스를 사용합니다. 공개 place 레코드로 매장을 식별할 수는 있지만, 그 매장이 오늘 무엇을 보유하는지에 대한 권위 있는 출처로 사용해서는 안 됩니다.
하이브리드 위치 검색이란 무엇인가요?
하이브리드 위치 검색은 하나의 결정을 위해 이러한 방법 중 둘 이상을 조합합니다. 일반적인 흐름은 앵커를 해석하고, 장소 후보를 가져오고, 공간 술어와 비즈니스 규칙을 적용한 뒤, 적격 집합 안에서 의미 선호를 순위화합니다. 언어 모델은 남은 후보를 설명합니다.
Kaleidr는 공개 벡터 검색 엔드포인트를 문서화하나요?
여기서 인용한 Platform API 엔드포인트 참조에는 범용 벡터 검색 엔드포인트가 문서화되어 있지 않습니다. 이 글에서 사용하는 문서화된 검색 surface는 정방향 지오코딩, 한 지점에 무엇이 있는지 확인하는 POST /spot, 그리고 이미 알고 있는 좌표 사이의 경로 호출입니다. 제품 계획에 의미 인덱스를 포함하기 전에 현재 Enterprise 계약을 확인하세요.
References
- Google Maps Platform. Geocoding API overview. The service accepts an address, coordinates, or a Place ID, and converts an address into coordinates and a Place ID, or coordinates or a Place ID into an address. Accessed October 27, 2026. https://developers.google.com/maps/documentation/geocoding/overview
- Google Maps Platform. Geocoding API v4 overview. Documents forward geocoding, reverse geocoding, place geocoding, and destination search, and separates generally available, preview, and experimental channels. Accessed October 27, 2026. https://developers.google.com/maps/documentation/geocoding/geocoding-v4-overview
- Mapbox. Geocoding API. Forward and reverse geocoding. The Geocoding v6 API no longer provides point-of-interest data and directs that job to the Search Box API. Accessed October 27, 2026. https://docs.mapbox.com/api/search/geocoding/
- Mapbox. Search Box API. Interactive and stand-alone search for addresses, places, and points of interest, including category search. Accessed October 27, 2026. https://docs.mapbox.com/api/search/search-box/
- Google Maps Platform. Text Search (New). Returns places for a text string. Documented examples include "shoe stores near Ottawa" and "123 Main Street." Accessed October 27, 2026. https://developers.google.com/maps/documentation/places/web-service/text-search
- Google Maps Platform. Nearby Search (New). Takes one or more place types and returns matching places within a specified area. Accessed October 27, 2026. https://developers.google.com/maps/documentation/places/web-service/nearby-search
- PostGIS. ST_DWithin. Tests whether two geometries are within a given distance. The call includes a bounding-box comparison that uses available spatial indexes. Geography distance is in meters. Accessed October 27, 2026. https://postgis.net/docs/ST_DWithin.html
- PostGIS. ST_Within. Tests whether every point of one geometry lies in another and the interiors share a point. The function uses available spatial indexes. Accessed October 27, 2026. https://postgis.net/docs/ST_Within.html
- pgvector. pgvector. Exact and approximate nearest-neighbor search in Postgres, including HNSW and IVFFlat indexes, cosine and other distances, and iterative scans when a filter leaves too few approximate results. Accessed October 27, 2026. https://github.com/pgvector/pgvector
- Kaleidr Developer Docs. Platform API endpoints. Documents forward geocoding for a search box or From/To field,
POST /spotas the successor to the deprecated POI enrich endpoint, and a route call between known coordinates. Accessed October 27, 2026. https://docs.kaleidr.com/platform-api/endpoints - Kaleidr. Place Ranking API for Customer Intent. Hard filters such as authorization, availability, required capability, and service area run before scoring. Accessed October 27, 2026. https://kaleidr.com/blog/place-ranking-api
- Kaleidr Developer Docs. How Kaleidr works. Uploading an organization's own business data for AI answers is Enterprise only, as is the key scope that lets answers draw on that data. Accessed October 27, 2026. https://docs.kaleidr.com/concepts/how-kaleidr-works
- Kaleidr. Plot Places on a Map. A related guide for turning resolved places into markers. Accessed October 27, 2026. https://kaleidr.com/blog/plot-places-on-a-map
- Kaleidr. How to Build a Nearby Places Map for Near Me Search. A related guide for nearby discovery. Accessed October 27, 2026. https://kaleidr.com/blog/how-to-build-a-nearby-places-map-for-near-me-search
- Kaleidr. Spatial Context Engineering for Map-Aware AI. A related guide for what reaches the model after retrieval. Accessed October 27, 2026. https://kaleidr.com/blog/spatial-context-engineering
- Kaleidr. Grounded Spatial AI for Business Data. A related guide for keeping business facts in the systems that own them. Accessed October 27, 2026. https://kaleidr.com/blog/grounded-spatial-ai-business-data
- Kaleidr. Map-Aware AI Assistant: How to Build One. A related guide for map actions around a validated place. Accessed October 27, 2026. https://kaleidr.com/blog/how-to-build-a-map-aware-ai-assistant
References in BibTeX
@misc{google_geocoding_overview_2026,
title = {Geocoding API overview},
author = {{Google Maps Platform}},
year = {2026},
url = {https://developers.google.com/maps/documentation/geocoding/overview}
}
@misc{google_geocoding_v4_overview_2026,
title = {Geocoding API v4 overview},
author = {{Google Maps Platform}},
year = {2026},
url = {https://developers.google.com/maps/documentation/geocoding/geocoding-v4-overview}
}
@misc{mapbox_geocoding_api_2026,
title = {Geocoding API},
author = {{Mapbox}},
year = {2026},
url = {https://docs.mapbox.com/api/search/geocoding/}
}
@misc{mapbox_search_box_api_2026,
title = {Search Box API},
author = {{Mapbox}},
year = {2026},
url = {https://docs.mapbox.com/api/search/search-box/}
}
@misc{google_places_text_search_2026,
title = {Text Search (New)},
author = {{Google Maps Platform}},
year = {2026},
url = {https://developers.google.com/maps/documentation/places/web-service/text-search}
}
@misc{google_places_nearby_search_2026,
title = {Nearby Search (New)},
author = {{Google Maps Platform}},
year = {2026},
url = {https://developers.google.com/maps/documentation/places/web-service/nearby-search}
}
@misc{postgis_st_dwithin_2026,
title = {ST_DWithin},
author = {{PostGIS}},
year = {2026},
url = {https://postgis.net/docs/ST_DWithin.html}
}
@misc{postgis_st_within_2026,
title = {ST_Within},
author = {{PostGIS}},
year = {2026},
url = {https://postgis.net/docs/ST_Within.html}
}
@misc{pgvector_2026,
title = {pgvector},
author = {{pgvector}},
year = {2026},
url = {https://github.com/pgvector/pgvector}
}
@misc{kaleidr_platform_api_endpoints_2026,
title = {Platform API endpoints},
author = {{Kaleidr}},
year = {2026},
url = {https://docs.kaleidr.com/platform-api/endpoints}
}
@misc{kaleidr_place_ranking_api_2026,
title = {Place Ranking API for Customer Intent},
author = {{Kaleidr}},
year = {2026},
url = {https://kaleidr.com/blog/place-ranking-api}
}
@misc{kaleidr_how_kaleidr_works_2026,
title = {How Kaleidr works},
author = {{Kaleidr}},
year = {2026},
url = {https://docs.kaleidr.com/concepts/how-kaleidr-works}
}