Geocodificação vs. busca de lugares

Geocodificação vs. busca de lugares é a primeira divisão em uma consulta de localização: uma chamada resolve um objeto geográfico, e a outra descobre lugares candidatos. Um endereço, uma coordenada ou um identificador de lugar pertence à geocodificação. Uma solicitação por empresas, pontos de referência ou outros lugares nomeados pertence à busca de lugares. Depois, uma consulta espacial testa a geometria que a aplicação já possui, e a busca vetorial compara significado sem provar que um registro está perto ou é elegível.

O que cada consulta de localização responde?

Cada método responde a uma pergunta diferente, e um menu de fornecedor que os reúna em uma única família de produtos não apaga essa diferença. A geocodificação resolve identidade. A busca de lugares descobre candidatos em um índice do provedor ou privado. Uma consulta espacial aplica uma relação geométrica aos registros que a aplicação já armazena. A busca vetorial recupera registros cujos embeddings são próximos em significado. Uma decisão de produção muitas vezes precisa de mais de uma dessas respostas, em uma ordem definida pela própria pergunta.

Os quatro cartões separam resolver, descobrir, filtrar geografia e comparar significado. Cada cartão combina uma entrada com uma saída: um endereço com uma coordenada, uma categoria com pontos de interesse, uma relação geométrica com registros correspondentes e um conceito com vizinhos semânticos. O endereço, a coordenada, a consulta de café e a contagem de lugares dentro do polígono são rótulos de exemplo na figura. Esses rótulos não vêm de uma consulta ao vivo em um índice da Kaleidr.

A tabela é a regra de seleção. Uma equipe que começa pelo nome do endpoint, em vez da pergunta, pedirá a um geocodificador uma recomendação ou a um índice vetorial um teste de contenção. Os dois erros produzem uma resposta confiante para uma pergunta que o sistema nunca executou. O restante deste guia mantém os quatro trabalhos separados e depois mostra onde um pipeline precisa reuni-los.

Qual consulta combina com a pergunta?

As primeiras palavras da solicitação normalmente indicam o método. “Onde fica este endereço?” começa com geocodificação. “Quais lugares correspondem a este texto ou categoria?” começa com busca de lugares. “Quais dos nossos registros satisfazem esta relação geográfica?” começa com uma consulta espacial. “Quais registros significam algo parecido com isto?” é o caso de busca vetorial, e somente depois que os limites geográficos e de negócio rígidos estiverem definidos. Uma solicitação que mistura essas perguntas precisa de um híbrido, não de um único vencedor.

A árvore começa com a pergunta que o solicitante está tentando responder e depois se ramifica para resolver um endereço, descobrir empresas, filtrar geograficamente os próprios registros do solicitante ou encontrar registros com significado semelhante. Uma quinta faixa na parte inferior combina os quatro métodos quando uma única consulta não basta. O endereço de exemplo, os cartões de cafés, o raio de um quilômetro e a frase citada sobre um encontro são rótulos da figura. As marcas de seleção descrevem o trabalho de cada método, não uma pontuação de qualidade medida.

Um híbrido é o caso normal para um assistente de mapas com IA, não uma exceção reservada para uma versão futura. “Café perto de 20 W 34th St” ainda exige que o endereço seja resolvido antes de executar uma busca próxima. “Um café tranquilo perto do hotel, aberto depois das nove” acrescenta um filtro de negócio e uma preferência semântica sobre essa resolução. As seções de pipeline abaixo mantêm essas etapas em uma ordem que um revisor consegue testar.

O que a geocodificação resolve?

A geocodificação converte uma localização textual em uma representação geográfica, e a geocodificação reversa converte uma coordenada ou um identificador de lugar de volta em um endereço legível. A visão geral da Geocoding API do Google define o serviço como aceitando um endereço, latitude e longitude ou um Place ID, e convertendo um endereço em coordenadas e um Place ID, ou coordenadas ou um Place ID em um endereço (Google, 2026). A mesma visão geral usa “1600 Amphitheatre Parkway, Mountain View, CA” como exemplo de geocodificação direta e lista entregas e retiradas entre os usos da geocodificação reversa. A saída de uma chamada bem-sucedida é um objeto que o mapa pode posicionar, não um conjunto classificado de empresas.

A fronteira do produto está mudando, mas o trabalho de recuperação ainda é o que precisa ser nomeado. A visão geral da Geocoding API v4 do Google lista geocodificação direta, geocodificação reversa, geocodificação de lugares e um método de busca de destino que aceita um endereço, um Place ID ou coordenadas (Google, 2026). Essa visão geral também separa canais generally available, preview e experimental e orienta os solicitantes a usar o canal experimental para recursos de destino que não estão no caminho geralmente disponível. Uma consulta de destino pode enriquecer uma localização que a aplicação já resolveu. Uma consulta de destino não se transforma em um índice de descoberta de lugares, e um canal experimental não é promessa de que todos os campos estão prontos para um contrato de produção.

A geocodificação é a ferramenta certa quando a aplicação precisa plotar um endereço, normalizá-lo antes de armazenar, centralizar um mapa, fazer geocodificação reversa de uma localização de dispositivo ou resolver um ponto de entrega antes de uma consulta posterior. Geocodificação não escolhe o melhor restaurante próximo, não lê inventário privado, não testa um polígono privado de área de serviço e não ranqueia resultados pela intenção do cliente. Esses trabalhos só começam depois que um objeto existe. Plotar lugares em um mapa aborda a etapa de endereço para marcador que vem depois de uma resolução bem-sucedida.

Geocodificação vs. busca de lugares: em que diferem?

A busca de lugares descobre entidades geográficas nomeadas: restaurantes, lojas, estações, pontos de referência e outros pontos de interesse. A Mapbox traça explicitamente a linha de produto na Geocoding API atual. Essa API realiza geocodificação direta e reversa, e a Geocoding v6 API não fornece mais dados de pontos de interesse (Mapbox, 2026). A Mapbox direciona a busca de pontos de interesse para a Search Box API, que aceita consultas interativas e independentes para endereços, lugares e pontos de interesse, incluindo busca por categoria (Mapbox, 2026). A família de endpoints é de um fornecedor. Os trabalhos continuam sendo dois.

A Places API atual do Google faz a mesma separação dentro da própria busca de lugares. Text Search (New) retorna lugares para uma string de texto, e os exemplos documentados incluem “shoe stores near Ottawa” e “123 Main Street”, de modo que uma string com formato de endereço pode entrar em uma chamada de busca de lugares (Google, 2026). Nearby Search (New) recebe um ou mais tipos de lugar e retorna lugares correspondentes dentro de uma área especificada (Google, 2026). Portanto, Text Search pode parecer geocodificação quando a string é um endereço, e Nearby Search pode parecer uma consulta espacial quando a área é um círculo. O resultado continua sendo um conjunto de candidatos do índice desse provedor. Estado de abertura, inventário, autorização e tempo de viagem continuam sendo testes posteriores. A mesma página de Text Search também diz que o serviço não se destina a consultas ambíguas, incluindo formatos de endereço postal que não são representados como lugares.

O painel esquerdo pergunta onde fica um endereço e mostra uma única identidade de localização. O endereço e a coordenada desse painel correspondem ao exemplo da referência de forward geocode da Kaleidr, e os nomes de cafés, distâncias e avaliações por estrelas à direita são rótulos de exemplo, não uma resposta de busca de lugares ao vivo. O rodapé percorre “coffee near 20 W 34th St” geocodificando o endereço e depois buscando café. A conclusão do lado direito chama o resultado de conjunto de candidatos, que é o ponto correto de parada antes da elegibilidade e do ranking.

Uma aplicação robusta usa ambas quando a âncora é um endereço e o alvo é uma categoria. Geocodifique “20 W 34th St”, depois busque café perto do ponto resolvido, calcule o tempo a pé e ranqueie apenas os lugares que continuam elegíveis. Um mapa de lugares próximos é a superfície de descoberta para essa segunda etapa. A ordem do provedor é uma conveniência de recuperação. A ordem do produto é uma decisão posterior.

O que uma consulta espacial testa?

Uma consulta espacial filtra registros que a aplicação já possui usando uma relação entre geometrias. Relações comuns são dentro de uma distância, dentro de um polígono, intersecta, contém e vizinho mais próximo. Os registros e sua geometria existem antes da consulta. A consulta pergunta quais desses registros satisfazem a relação. Uma API de busca de lugares responde a outra pergunta, porque o conjunto de candidatos vem do índice do provedor em vez da tabela do solicitante.

Os painéis são dentro de uma distância, dentro de um polígono, uma rota que intersecta uma zona e o elemento mais próximo. O raio de um quilômetro, o contorno da área de serviço e o selo de distância são geometrias de exemplo, não uma área de serviço medida. O painel de mais próximo também marca um elemento como excluído. Essa exclusão é um exemplo de uma verificação posterior de elegibilidade. O predicado de distância por si só não testa se um lugar está aberto.

O PostGIS define ST_DWithin como um teste para saber se duas geometrias estão dentro de uma determinada distância, e a chamada inclui uma comparação de bounding box que usa quaisquer índices espaciais disponíveis nas geometrias (PostGIS, 2026). Para o tipo geography, a distância é em metros. Assim, uma tabela de lojas com uma coluna geography pode manter “dentro de cinco quilômetros” como predicado em vez de como frase para um modelo de linguagem interpretar.

SELECT store_id, name
FROM stores
WHERE ST_DWithin(stores.geog, user_location, 5000);

Contenção pertence à mesma classe de predicado. ST_Within retorna true quando todos os pontos da primeira geometria estão na segunda e os interiores compartilham um ponto, e a função também usa os índices espaciais disponíveis (PostGIS, 2026). ST_Within(A, B) é o inverso de ST_Contains(B, A). Uma pergunta de entrega como “este endereço fica dentro da área de serviço?” consiste em uma geocodificação, depois um teste de contenção e depois a regra operacional. Um índice vetorial não substitui o polígono, e uma busca pública de lugares não substitui a geometria da área de serviço desenhada pela empresa.

A observação sobre o índice é uma restrição de arquitetura, não uma nota de tuning. Uma expressão de distância que não pode usar um índice comparará muito mais linhas do que ST_DWithin na mesma tabela. A regra prática para um assistente sensível à localização é filtrar geograficamente antes que qualquer modelo veja o conjunto. Se apenas uma pequena parte de um grande catálogo puder satisfazer a geometria, o modelo de linguagem deve receber essa parte, junto com o motivo pelo qual as outras foram descartadas. Enviar o restante gasta contexto com registros que o predicado já excluiu.

O que a busca vetorial compara?

A busca vetorial recupera registros cujos embeddings estão próximos da consulta em um espaço vetorial. pgvector, a extensão do Postgres comumente usada para esse trabalho, executa busca exata de vizinhos mais próximos por padrão e pode adicionar um índice HNSW ou IVFFlat para busca aproximada (pgvector, 2026). A mesma documentação lista distância L2, produto interno, distância cosseno e outras medidas. A busca exata é a linha de base de recall. Um índice aproximado troca parte desse recall por velocidade, e as consultas podem retornar vizinhos diferentes depois que o índice existe. Essa propriedade importa quando uma equipe compara um protótipo que usava busca exata com uma consulta de produção que usa o índice.

A busca vetorial justifica seu custo quando as palavras da solicitação não são as palavras do registro. Uma descrição que diz “bar de vinhos intimista com iluminação baixa” pode ser um vizinho útil para “lugar tranquilo para uma primeira reunião”, mesmo que as strings não correspondam. Descrições de lugares, notas de comodidades e textos de destino são entradas comuns, quando a licença permite transformar o texto em embedding. Uma marca conhecida, um número de loja, um código de aeroporto ou uma categoria explícita geralmente é um trabalho melhor para busca por palavra-chave ou estruturada. Embeddings acrescentam um sistema para operar e devem ser adicionados quando a falha semântica for real.

A similaridade vetorial não registra distância geográfica, tempo de rota, contenção em área de serviço, inventário atual, horário, autorização ou se o texto incorporado ainda é verdadeiro. Um vizinho próximo no espaço de embeddings pode estar a centenas de quilômetros do solicitante. Um lugar do outro lado da rua pode ser uma correspondência semântica ruim e ainda ser a resposta operacional correta. Os dois resultados não estão em conflito. Eles vêm de espaços diferentes, e o pipeline precisa dizer qual espaço pode rejeitar um candidato.

Por que distância geográfica e distância vetorial são diferentes?

Os dois sistemas usam a palavra distância, e a palavra esconde uma mudança de assunto. Distância geográfica é a separação sobre a Terra ou ao longo de um caminho: uma distância em linha reta, uma caminhada, uma viagem de carro ou um resultado de contenção. Distância vetorial é a separação em um espaço de embeddings: distância cosseno, distância euclidiana ou uma pontuação de produto interno. Uma pequena distância vetorial não coloca dois locais geograficamente próximos. Uma caminhada curta não faz duas descrições significarem a mesma coisa.

O painel esquerdo mede a separação física e mostra uma caminhada de exemplo entre dois lugares identificados. Os selos de quilômetros e minutos são rótulos de exemplo, não uma viagem roteada. O painel direito posiciona palavras em um diagrama de embeddings e marca coffee como distante em significado de train. Essa indicação de cosseno ilustra os dois espaços, não é um embedding medido em um índice da Kaleidr. O rótulo central resume o ponto da figura: a mesma palavra, distância, nomeia as duas quantidades.

A colisão de nomes aparece no texto do produto. Uma tela que diz “mais próximo” pode significar mais próximo no índice de embeddings, mais próximo em metros em linha reta ou menos minutos de desvio. Essas três ordens discordam com frequência suficiente para que a interface deva nomear a quantidade. Um ranker pode usar mais de uma delas. Um ranker não deve somar uma pontuação cosseno a um valor em quilômetros e tratar a soma como uma única distância.

Como um pipeline híbrido deve ordenar o trabalho?

Uma busca de localização em produção geralmente é um pipeline, porque a solicitação mistura um objeto, uma categoria, um limite geográfico, uma regra de negócio e uma preferência. Uma ordem viável é interpretar a solicitação, resolver a âncora, recuperar candidatos, aplicar o filtro espacial, aplicar a elegibilidade de negócio e só então usar similaridade semântica dentro do conjunto elegível. Routing e outros enriquecimentos rodam sobre os sobreviventes. O ranking ordena esses sobreviventes. A explicação e a ação no mapa usam os mesmos identificadores que os filtros usaram. Engenharia de contexto espacial é a pergunta complementar sobre o que, desse pipeline, pode chegar ao modelo de linguagem.

As etapas são rotuladas com o método responsável por cada uma: geocodificação, busca de lugares, consulta espacial, dados de negócio e busca vetorial, seguidos por enriquecimento, ranking e ação no mapa. Os nomes dos lugares, avaliações por estrelas, barras de pontuação, o funil “100K+” e a afirmação “top 3–5” são rótulos ilustrativos. A figura é um esboço de referência da ordem do trabalho, não um benchmark da Kaleidr nem um formato de solicitação. A coluna de filtros de negócio mostra regras de exemplo como aberto agora e avaliação mínima, que pertencem aos dados do host e não ao índice público de lugares.

A ordem altera o recall. Buscar primeiro em todo o índice de embeddings e depois testar a geografia em uma lista semântica curta pode perder um lugar local válido que nunca entrou nessa lista. Restringir primeiro o conjunto de candidatos com a geografia rígida e as regras de negócio rígidas e só depois ranquear por significado dentro desse conjunto preserva a fronteira. Quando o banco de dados pode aplicar ambos os filtros em uma única consulta, o mesmo princípio vale: similaridade semântica não pode apagar um limite geográfico obrigatório.

As próprias notas de filtragem do pgvector são o alerta prático. Com um índice aproximado, o filtro é aplicado depois da varredura do índice, e o exemplo da documentação é uma condição que corresponde a 10% das linhas com o ef_search padrão do HNSW igual a 40, deixando em média cerca de quatro linhas. Varreduras iterativas de índice, introduzidas na documentação para essa insuficiência, continuam até que restem linhas suficientes. Uma equipe deve testar recall filtrado com dados realistas em vez de presumir que a consulta elegante é a consulta de produção.

Por que filtros rígidos devem rodar antes da similaridade?

A recuperação pergunta quais candidatos podem entrar em consideração. O ranking pergunta em que ordem os candidatos válidos devem aparecer. Misturar os dois permite que um lugar fechado, não autorizado ou sem estoque vença porque é conveniente ou semanticamente próximo. O guia de ranking de lugares da Kaleidr mantém autorização, disponibilidade, capacidade necessária e área de serviço como filtros antes da pontuação, em vez de penalidades fracas (Kaleidr, 2026). Uma penalidade pode perder para um termo grande de conveniência. Um filtro não.

A coluna esquerda lista quatro gates booleanos e termina removendo candidatos inválidos. A coluna direita mostra pontuações de similaridade de exemplo para tranquilo, adequado para famílias e adequado para trabalho, e ranqueia apenas os lugares aprovados. As fotografias e as três pontuações são rótulos de exemplo, não avaliações medidas nem uma pontuação da Kaleidr. A seta mostra a ordem: elegibilidade, depois similaridade.

Gates rígidos continuam booleanos. Autorizado, em estoque, aberto na chegada e dentro da área de serviço são condições, não pesos. Sinais semânticos podem continuar como pontuações e se aplicam aos lugares mantidos pelos gates. A mesma separação cobre uma regra obrigatória de acessibilidade ou uma fronteira de tenant. Um fato obrigatório que seja desconhecido deve continuar desconhecido. Tratar uma consulta indisponível como false transforma uma leitura ausente de inventário em um confiante “sem estoque”, que é um erro diferente e pior.

Por que a busca “no caminho” não é um raio?

“Perto de mim” e “no caminho de casa” descrevem geometrias diferentes. Um raio em torno da origem retorna lugares dentro de uma distância do ponto de partida, incluindo lugares na direção errada. Uma consulta de corredor de rota retorna lugares que acrescentam pouco desvio a uma viagem que o serviço de routing já planejou. Distância em linha reta é um filtro legítimo quando a pergunta é realmente radial. É a quantidade errada quando a decisão depende da jornada. Dois quilômetros em linha reta podem ser uma viagem longa de carro, e uma distância em linha reta maior pode resultar no trajeto mais curto.

O painel esquerdo é um raio simples e mostra farmácias de exemplo dentro e fora de um anel de uma milha. O painel direito segue uma rota de exemplo do trabalho para casa e rotula farmácias com minutos de desvio. Os valores em milhas, os minutos de desvio e os nomes dos lugares são rótulos de exemplo, não uma rota ao vivo. O ponto da figura é a relação: baixo desvio de rota não é o mesmo predicado que um círculo em torno da origem.

O serviço de routing deve calcular o desvio, e o ranker deve receber esse resultado. Um modelo de linguagem que estime os minutos às vezes contradirá a rota que o serviço acabou de retornar. A chamada de rota vem depois da resolução e depois da seleção de candidatos. A chamada de rota não é uma busca de lugares, e um caminho ausente deve permanecer uma falha visível em vez de uma linha adivinhada no mapa.

Onde a Kaleidr se encaixa neste pipeline?

A Platform API pública da Kaleidr expõe um endpoint de forward geocode criado para uma caixa de busca ou um campo From/To, não para um índice privado de negócios. GET /retrieval/geocode/forward aceita q como nome de lugar, endereço com número ou latitude e longitude digitadas, além de near_lat e near_lng opcionais usados juntos, limit e um mode de viagem (Kaleidr, 2026). A mesma referência documenta uma rota entre coordenadas que o solicitante já possui, com perfis de direção, caminhada, bicicleta e transporte público, e uma rota que não pode ser planejada retorna um status HTTP bem-sucedido com um erro no corpo em vez de um caminho. Os resultados carregam atribuição que o solicitante deve repassar, e um resultado de endereço pode incluir um identificador que permanece estável entre atualizações de dados. Uma lista results vazia significa que não há nada para mostrar, inclusive no caso de uma falha interna de consulta, portanto uma lista vazia não prova que o endereço seja inválido.

Os parâmetros documentados não incluem o catálogo privado de um cliente. Geocodificação pública não se torna um sistema de inventário por estar montada no mesmo mapa. Um solicitante que precisa de lojas privadas ou inventário precisa ler esses sistemas diretamente e depois uni-los a um lugar resolvido com um identificador estável. A resposta de geocode é o objeto público, e o registro de negócio continua sendo o registro de negócio.

Detalhe de lugar tem um sucessor atual, e o caminho antigo não deve ser a base de uma nova integração. A referência de endpoints marca GET /retrieval/poi/enrich como deprecated e direciona novos trabalhos para POST /spot, que responde o que existe em um ponto e pode acrescentar conteúdo descritivo e fotos. A rota deprecated pode ser removida após 2027-01-15.

Enriquecimento ainda não decide elegibilidade privada. Horários, fotos e uma categoria de uma fonte pública são fatos públicos, com a atribuição exigida por essa fonte. Estoque, permissão de conta e uma área de serviço desenhada pelo cliente ficam nos sistemas que os possuem. Spatial AI fundamentada em dados de negócio é o guia para essa fronteira.

A coluna esquerda separa endereços e lugares nomeados de lojas privadas, inventário e áreas de serviço. A coluna central nomeia o forward geocoding da Kaleidr, uma etapa de detalhe de lugar e o próprio banco de dados espacial e os sistemas de negócio do host. A caixa de detalhe de lugar é o trabalho agora documentado como POST /spot. O endpoint antigo de enrich é o predecessor deprecated, não a integração com que se deve começar. A coluna direita mostra o que acontece após a recuperação: uma rota entre coordenadas conhecidas, um ranking de lugares elegíveis, uma explicação e uma ação no mapa. O aviso na figura corresponde à referência de endpoints. Uma API pública de geocode ou de lugares não indexa as localizações privadas, o inventário ou as áreas de serviço do solicitante.

Dados específicos da organização seguem a fronteira do plano, não o mapa. A documentação de conta da Kaleidr diz que carregar os próprios dados de negócio de uma organização para respostas de IA é exclusivo do Enterprise, e que o scope de chave que permite que respostas usem esses dados carregados também é exclusivo do Enterprise (Kaleidr, 2026). A referência pública atual de endpoints não documenta um endpoint de busca vetorial de uso geral. Uma equipe que precisa de recuperação semântica sobre suas próprias descrições deve tratar esse índice como parte do design do host ou do Enterprise e confirmar o contrato atual em vez de chamar um caminho que este artigo não cita. Como construir um assistente de IA sensível ao mapa aborda as ações no mapa que seguem um identificador de lugar validado.

O que uma equipe deve medir separadamente?

Cada camada falha à sua maneira, e uma única pontuação de relevância esconderá qual camada falhou. A geocodificação falha em um endereço ambíguo, uma unidade ausente, uma coordenada invertida ou uma correspondência apenas em nível de rua. A busca de lugares falha quando cobertura, categoria ou atualidade do provedor não correspondem ao produto. Uma consulta espacial falha em uma geometria inválida, uma referência de coordenadas incompatível ou um polígono que já não corresponde à operação.

A busca vetorial falha em um embedding fraco, um texto desatualizado ou um índice aproximado que retorna pouco demais após um filtro. Dados de negócio falham quando o inventário é desconhecido, o registro não está autorizado ou os horários estão desatualizados. Um log útil nomeia a camada. “Search failed” não.

Avalie a camada pelo seu trabalho e depois avalie a decisão. Geocodificação quer qualidade de correspondência e identificadores estáveis. Busca de lugares quer recall de candidatos, precisão de categoria e uma taxa de lugares desatualizados. Consultas espaciais querem correção geométrica e evidência de que a consulta usou o índice. Busca vetorial quer relevância semântica e recall filtrado contra uma linha de base de busca exata. A verificação ponta a ponta pergunta se um lugar elegível foi recuperado, se nenhum resultado foi o desfecho honesto e se a ação usou o identificador aprovado pelos filtros. Uma falha de autorização ou contenção não deve desaparecer dentro de uma taxa média de cliques.

Onde o stack deve começar?

Escolha o método que pode provar a cláusula pedida pelo usuário. Geocodificação prova onde um objeto está. Busca de lugares prova quais lugares conhecidos correspondem a texto, categoria ou área naquele índice. Uma consulta espacial prova uma relação geométrica sobre registros mantidos pela aplicação. Busca vetorial prova similaridade de significado, e apenas dentro do conjunto mantido pelos filtros rígidos. Sistemas de negócio provam o fato atual. Um serviço de routing prova a jornada. Um ranker ordena o que resta. O modelo de linguagem explica esse resultado e não deve ser a fonte da distância, do teste de contenção ou da contagem de estoque.

Dados públicos de lugares são a fonte certa quando o trabalho é descoberta pública. Lojas privadas, inventário e elegibilidade ficam nos sistemas que os possuem, com identificadores estáveis unindo o lugar do provedor, a localização do inventário e o marcador do mapa. Similaridade semântica não apaga uma fronteira geográfica, e um raio não responde a uma pergunta “no caminho”. Explore Kaleidr Enterprise quando a recuperação precisar rodar sobre dados específicos da organização e leia os endpoints da Platform API para os contratos de forward geocode, spot e route citados acima.

Observação: a Kaleidr usa ferramentas assistidas por IA para criação de imagens, refinamento de conteúdo e pesquisa em seus fluxos criativos e de desenvolvimento.

Perguntas frequentes

Qual é a diferença entre geocodificação e busca de lugares?

A geocodificação resolve um endereço, uma coordenada ou uma referência conhecida de lugar em uma identidade geográfica. A busca de lugares descobre empresas, pontos de referência, estações e outros lugares nomeados que correspondem a texto, categoria ou área próxima. Uma retorna um objeto. A outra retorna candidatos.

Busca de pontos de interesse é o mesmo que geocodificação?

Não. Algumas APIs de fornecedores podem aceitar tanto um endereço quanto uma consulta de lugar. Em contraste, a Geocoding v6 API da Mapbox não fornece mais nenhum dado de ponto de interesse. A busca de pontos de interesse descobre candidatos. A geocodificação resolve uma localização.

O que é uma consulta espacial?

Uma consulta espacial filtra registros geográficos por uma relação geométrica como dentro de uma distância, dentro de um polígono, intersecta ou vizinho mais próximo. Os registros e sua geometria já pertencem à aplicação. O predicado é determinístico.

O que é busca vetorial?

Busca vetorial recupera registros cujos embeddings estão próximos do embedding da consulta. O método é útil para significado e para formulações que não correspondem ao texto de origem. Ele não prova distância, contenção ou elegibilidade.

Busca vetorial pode substituir uma consulta espacial?

Não. Similaridade em um espaço de embeddings não prova distância geográfica, contenção, adequação de rota ou pertencimento a área de serviço. Use um predicado espacial para verdade geográfica e busca vetorial para relevância semântica dentro do conjunto permitido por esse predicado.

A geografia deve filtrar o conjunto antes da busca vetorial?

Sim, quando a geografia é um limite rígido. Buscar em um índice global de embeddings e depois verificar localização em uma lista curta pode descartar lugares locais válidos que nunca entraram nessa lista. O banco de dados e o índice decidem a implementação. A fronteira não muda.

Uma equipe deve geocodificar antes de uma busca próxima?

Sim, quando a âncora é um endereço ou outra localização não resolvida. Resolva a âncora e depois execute recuperação de lugares ou uma consulta espacial ao redor do ponto resolvido. Uma busca por categoria sem âncora já é uma pergunta de busca de lugares.

Um produto deve usar uma Places API ou seu próprio banco de dados?

Use uma Places API para descoberta pública quando cobertura, licença e atribuição servirem ao produto. Use o banco de dados próprio do produto para lojas first-party, inventário, instalações privadas, elegibilidade e estado atual do negócio. Um registro público de lugar pode identificar uma loja. Não deve ser a autoridade sobre o que essa loja tem hoje.

O que é busca híbrida de localização?

Busca híbrida de localização combina dois ou mais desses métodos para uma decisão. Uma cadeia típica resolve uma âncora, recupera lugares candidatos, aplica um predicado espacial e uma regra de negócio e depois ranqueia qualquer preferência semântica dentro do conjunto elegível. O modelo de linguagem explica os sobreviventes.

A Kaleidr documenta um endpoint público de busca vetorial?

A referência de endpoints da Platform API citada aqui não documenta um endpoint de busca vetorial de uso geral. As superfícies de recuperação documentadas usadas neste artigo são forward geocoding, POST /spot para o que existe em um ponto e a chamada de route entre coordenadas já disponíveis. Confirme o contrato Enterprise atual antes de incorporar um índice semântico ao plano do produto.

References

1. 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
2. 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
3. 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/
4. 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/
5. 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
6. 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
7. 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
8. 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
9. 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
10. Kaleidr Developer Docs. Platform API endpoints. Documents forward geocoding for a search box or From/To field, POST /spot as 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
11. 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
12. 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
13. 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
14. 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
15. 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
16. 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
17. 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}
}