Google Places API para verificar negócios
Campos do Google Places API permitem verificar negócios
Você pode estar analisando uma proposta cujas consultas ao bureau de crédito e ao cadastro empresarial deixaram uma pergunta prática em aberto: o negócio aparece no endereço informado? A Text Search (New) recebe o nome do negócio e o endereço declarado e retorna os locais correspondentes.
Informe na máscara de campos da solicitação quais dados você precisa. O resultado acrescenta um registro de local à proposta, não um registro da empresa. Ele não vincula o local a um número de registro, administrador ou contas, por isso as consultas ao cadastro empresarial e ao bureau continuam fazendo parte do fluxo.
Os campos estão distribuídos em quatro faixas de cobrança da Text Search. A tabela mostra cada campo e o dado que ele contém:
| Plano Text Search | Campos e dados |
|---|---|
| Essentials (IDs Only) |
|
| Pro |
|
| Enterprise |
|
| Enterprise + Atmosphere |
|
Cada solicitação é cobrada pela SKU aplicável de maior valor, então os campos escolhidos definem a faixa de cobrança daquela solicitação.
Crédito para PMEs: verifique se o negócio está em funcionamento
Em uma proposta de crédito para PME, compare o nome e o endereço informados com um local do Google para avaliar se o negócio funciona naquele endereço. Nos dados do Google, OPERATIONAL indica que o negócio está em funcionamento no local, mas não necessariamente aberto naquele momento. CLOSED_PERMANENTLY levanta a dúvida sobre a permanência do negócio no endereço informado na proposta. Se houver um movedPlaceId, consulte o local com esse ID. Considere essas informações junto com as consultas ao cadastro empresarial e ao bureau.
Compare o setor declarado com primaryType e types para avaliar se a descrição do local corresponde à proposta. Se o negócio foi declarado como restaurante e aparece como restaurant, as informações são compatíveis. Se foi declarado como atacadista e aparece como loja de roupas, ou se o local não tem um tipo principal, encaminhe o caso para análise humana. Essa comparação pode embasar um encaminhamento, mas não deve determinar automaticamente uma conclusão sobre o negócio.
Para negócios declarados como varejistas, compare regularOpeningHours com o horário esperado para esse tipo de estabelecimento. A ausência de horários ou horários incomuns para um varejista são pontos que merecem análise. Um local aberto 24 horas aparece como um período que começa no dia 0, à hora 0. Para avaliar a atividade pública, userRatingCount mostra o número de avaliações, e rating indica a nota dada pelos avaliadores, em uma escala de 1.0 a 5.0. Com três avaliações, há pouca informação pública para considerar. Com oitocentas, o volume de opiniões públicas é bem maior, qualquer que seja a nota.
Cadastro BNPL: verifique o lojista antes de começar
Antes de ativar o BNPL na loja de um lojista, consulte o status do local para saber se a loja está em funcionamento, ainda não abriu ou está temporariamente fechada. Cada status pode embasar uma decisão diferente no cadastro:
| Status do local | O que indica | Decisão no cadastro |
|---|---|---|
OPERATIONAL | A loja está em funcionamento | Proceed |
FUTURE_OPENING com openingDate | A loja ainda não abriu. A data indica quando abrirá | Aguardar a data de abertura |
CLOSED_TEMPORARILY | A loja está temporariamente fechada | Hold the application |
Se consumerAlert estiver preenchido, o Google detectou atividade suspeita nas avaliações do negócio ou uma violação de políticas. Considere esse alerta ao analisar a nota da loja.
Compare websiteUri e nationalPhoneNumber da loja com os dados informados pelo lojista no cadastro. Use essa comparação para avaliar se as informações correspondem e quanto peso dar às avaliações.
Verificações de fraude e KYB ajudam a diferenciar tipos de endereço comercial
Quando um endereço retorna apenas tipos como street_address, premise ou subpremise, sem establishment, os dados do Google não mostram um negócio em funcionamento naquele local, a menos que a empresa atenda clientes nos próprios endereços deles. Para uma loja declarada, coworking_space, business_center ou shipping_service podem indicar um escritório virtual ou serviço de caixa postal. Uma loja declarada em um apartment_building ou housing_complex aparece em um endereço residencial, uma divergência diferente. Considere o registro do local na análise de fraude. O cadastro da empresa e sua titularidade ainda precisam ser verificados no registro empresarial e em outras consultas.
Uma empresa de limpeza ou um encanador pode atender clientes nos endereços deles e não ter um local físico no Google Maps. Na regra de KYB, trate um negócio com pureServiceAreaBusiness preenchido como uma empresa que atende em uma área de serviço. Verifique esse campo antes de encaminhar um endereço sem establishment, para não tratar como loja um negócio que não precisa ter um ponto de atendimento físico.
Cobrança: use as informações para planejar visitas e monitorar a carteira
No monitoramento da carteira, guarde o ID do local obtido no cadastro e use-o para consultar o status atual do negócio e verificar se ele mudou de endereço. O processamento em lote permite analisar a carteira e também é usado na pré-análise de carteiras de clientes. O resultado mostra uma situação atual, não uma tendência das avaliações. Para identificar uma tendência, seria necessário guardar avaliações anteriores, o que os termos não permitem.
Antes de visitar uma empresa com pagamentos em atraso, verifique se ela continua em funcionamento no endereço e se mudou de local. businessStatus ajuda a avaliar se a visita ainda faz sentido, movedPlaceId indica qual local consultar em seguida e currentOpeningHours ajuda a planejar a visita para os próximos sete dias. Se a regra do Places não resolver o caso, o encaminhamento pode continuar na gestão de casos, com análise humana ou tarefas de consulta a dados externos.
A tabela de decisão fictícia a seguir não é uma resposta do Places. Os resultados são exemplos de decisões que um credor poderia definir, não recomendações. A tabela segue a ordem da primeira correspondência:
| Linha | Condição | Resultado do credor |
|---|---|---|
| 1 | businessStatus é CLOSED_PERMANENTLY | Decline |
| 2 | businessStatus é CLOSED_TEMPORARILY ou FUTURE_OPENING | Refer: pausado ou ainda não inaugurado |
| 3 | pureServiceAreaBusiness é true | Continue para a próxima verificação |
| 4 | Nenhum local encontrado ou nenhum establishment em types | Refer: não há atividade comercial no endereço |
| 5 | rating ou userRatingCount não foi informado | Refer: não há atividade pública no Google |
| 6 | userRatingCount é inferior a 10 | Refer: pouca atividade pública |
| 7 | primaryType é diferente do setor declarado | Refer: categoria incompatível |
| 8 | Qualquer outro valor | Continue para a próxima verificação |
A linha para valores ausentes fica acima da linha de contagem de avaliações porque um campo sem valor pode indicar que ele não foi solicitado, que o Google não tinha essa informação ou que a chamada expirou. Um teste separado do mecanismo de tabela de decisão, em 03/10/2026, mostrou o risco: uma linha que aprovava valores de comprometimento de renda entre 0 e 35 também aprovou um solicitante que não havia informado esse dado. Uma comparação numérica pode interpretar uma contagem ausente como zero e encaminhar a solicitação para uma regra destinada a uma contagem baixa. A linha 3 vem antes das linhas 4 a 7 para que um encanador sem loja e sem avaliações não seja encaminhado para análise por não ter nenhum dos dois.
Chave do Google Places API para Places API (New)
A chave do Google Places API é uma sequência alfanumérica exclusiva que associa cada solicitação a um projeto do Google Cloud e à conta de cobrança correspondente. Antes de usá-la, ative o faturamento do projeto e habilite o Places API (New).
- Use um projeto do Google Cloud com o faturamento ativado.
- No console do Google Cloud, habilite o Places API (New) para o projeto ou execute
gcloud services enable "places.googleapis.com". Aguarde alguns minutos antes da primeira solicitação. - Na página Keys & Credentials do Google Maps Platform, selecione Create credentials e depois API key. Em API restrictions, mantenha Places API (New) selecionado e desmarque os demais. Selecionar uma API nessa página não a habilita.
- Adicione uma restrição para o aplicativo, como os endereços IP dos servidores que usam a chave. Uma chave sem restrições pode chamar qualquer serviço do Google Maps Platform, e o titular da conta paga pelo uso indevido.
- Envie a chave por HTTPS no cabeçalho
X-Goog-Api-Keye informe os campos que serão retornados emX-Goog-FieldMask, como no exemplo abaixo.
curl -X POST -d '{
"textQuery" : "Bar Italia, 22 Frith Street, London"
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.id,places.displayName,places.businessStatus,places.primaryType' \
'https://places.googleapis.com/v1/places:searchText'
Em 30 de outubro de 2026, uma chamada sem chave retornou HTTP 403, com o status PERMISSION_DENIED: “Method doesn't allow unregistered callers (callers without established identity). Please use API Key or other form of API consumer identity to call this API.” Inclua o cabeçalho da chave. Uma chave expirada retornou HTTP 400, com o status INVALID_ARGUMENT e o motivo API_KEY_INVALID: “API key expired. Please renew the API key.”
Places API (New) é separado do Places API (Legacy). Habilite o serviço para o projeto e adicione-o à chave. Se um aplicativo usar os dois, o Google recomenda uma chave separada para cada um. Places API (New) retorna somente JSON, e Text Search (New) exige uma máscara de campos.
Os termos do Google definem como configurar o Places API
Os termos do Maps Platform do Google estabelecem um limite geral para o armazenamento de informações sobre locais. Eles dizem:
“Customer will not cache Google Maps Content except as expressly permitted under the Maps Service Specific Terms.”
Os termos específicos do serviço permitem guardar o ID do local e armazenar temporariamente latitude e longitude por até 30 dias corridos. Depois desse prazo, as coordenadas devem ser excluídas. Os termos também restringem o uso de conteúdo do Google Maps para aprimorar modelos de aprendizado de máquina ou inteligência artificial e o uso de conteúdo do Places API com mapas que não sejam do Google. É permitido usar o conteúdo sem um mapa.
Há também uma restrição de crédito separada, aplicável a decisões sobre pessoas que envolvam o Places Aggregate API, outro produto. Seu jurídico pode avaliar como essa cláusula se aplica ao uso do Places API. Os termos dizem:
“directly or indirectly results in any decisions, scoring, or assessments” about an individual relating to credit.
No Decisimo, salve a chave do Places em Credentials e faça a fonte de dados usar essa chave. Configure Text Search (New) como uma fonte de dados JSON com método POST e uma field mask. A primeira chamada pode usar campos Pro para as verificações iniciais de fraude e existência. Para as solicitações aprovadas nessa etapa, uma segunda chamada pode pedir campos Enterprise e usar o place ID da primeira chamada para consultar os detalhes. O cache vem desativado. Se você ativá-lo para uma etapa de decisão, o destino precisa ser de propriedade do cliente. As fontes da mesma etapa são executadas em paralelo. Se uma fonte de dados levar mais de 15 segundos, ela expira e o mecanismo continua o processamento.
O AI Assistant pode sugerir uma configuração de fonte de dados com base na descrição de uma API e pedir a chave para Credentials. Uma pessoa aplica a sugestão para preencher o formulário, mas essa ação não salva a configuração. As escolhas de campos e o uso de cache ainda precisam seguir os termos.
Perguntas frequentes
Que dados de precisão o Google publica sobre status, tipos e horários de funcionamento?
O Google não publica dados de precisão ou cobertura por país para status de funcionamento, tipos ou horários, nem explica quanto tempo uma informação de fechamento leva para aparecer em businessStatus. As informações disponíveis aqui não mostram que notas, contagens de avaliações ou concorrentes próximos prevejam pagamentos ou perdas.
Uma divergência de tipo deve levar à recusa de uma proposta?
Não. Trate a divergência como motivo para uma pessoa analisar o caso, não como uma conclusão sobre o negócio.
E se o Google não retornar um tipo principal?
Considere a ausência do tipo um ponto para análise. O local pode não ter um tipo principal disponível, então a falta dessa informação, por si só, não determina o resultado da proposta.
O que a quantidade de avaliações acrescenta à nota?
Ela mostra quanto volume de atividade pública está por trás da nota. Uma nota 5.0 com três avaliações e uma nota 4.2 com oitocentas avaliações representam volumes bem diferentes de opiniões públicas.