Google Maps

Visão geral

O Google Maps é a plataforma de mapas e localização do Google, que oferece geocodificação, rotas, pesquisa de lugares, imagens de satélite e tiles de mapas personalizáveis. Com a integração no SquadOS, seus agentes podem converter endereços em coordenadas, calcular distâncias e durações entre múltiplos pontos, buscar estabelecimentos próximos e recuperar detalhes ricos de lugares — tudo via API, sem abrir o browser.

• Site oficial: https://maps.google.com/
• Documentação na Composio: docs.composio.dev/toolkits/google_maps

Autenticação

Esta ferramenta utiliza OAuth 2.0 (OAUTH2) ou chave de API (API_KEY) para conectar.

Você vai precisar dos seguintes campos (para conexão via chave de API):

Campo	Obrigatório	Descrição
api_key	Sim	Chave de API do Google Maps Platform gerada no Google Cloud Console, com as APIs necessárias habilitadas.

Nota

A conexão via OAuth 2.0 é a opção recomendada — não exige geração de chave e oferece escopos granulares. Para autenticação por chave de API, gere a chave no Google Cloud Console e restrinja-a às APIs do Maps Platform que pretende usar.

Como obter a credencial

OAuth 2.0 (recomendado)

A Composio disponibiliza um app OAuth gerenciado para o Google Maps. Para usar suas próprias credenciais OAuth (white-label):

1. Acesse o Google Cloud Console e crie ou selecione um projeto.
2. Em APIs e Serviços → Credenciais, clique em Criar credenciais → ID do cliente OAuth.
3. Configure a tela de consentimento (tipo Externo para usuários gerais).
4. Anote o Client ID e o Client Secret gerados.
5. Siga o guia completo em composio.dev/auth/googleapps para configurar o redirect URL da Composio.

Chave de API

1. Acesse o Google Cloud Console e selecione seu projeto.
2. Em APIs e Serviços → Credenciais, clique em Criar credenciais → Chave de API.
3. Copie a chave gerada.
4. Em APIs e Serviços → Biblioteca, habilite as APIs do Maps Platform que seus agentes precisam (ex.: Maps JavaScript API, Places API, Routes API, Geocoding API).
5. (Recomendado) Restrinja a chave por IP ou referenciador HTTP para limitar o uso indevido.

Dica

Habilite apenas as APIs que você realmente vai usar. Cada API tem cota e cobrança separadas. Se receber erro “Google Maps API has not been used in project”, acesse o Console e habilite a API específica indicada na mensagem.

Como conectar no SquadOS

1. Acesse Ferramentas no menu lateral (/admin/tools).
2. Abra a aba Disponíveis e procure por Google Maps.
3. Clique no card para abrir o modal de detalhes e em Conectar.
4. Você é levado para a página de conexão segura hospedada pela Composio, onde autoriza o acesso via OAuth 2.0 ou informa a chave de API obtida acima.
5. Ao concluir, você volta para o SquadOS com a conta conectada e a ferramenta disponível para os agentes. (Detalhes do fluxo em Ferramentas da Organização.)

Perguntas frequentes

Como configuro credenciais OAuth personalizadas para o Google Maps?

Consulte o guia passo a passo em composio.dev/auth/googleapps para criar e configurar suas próprias credenciais OAuth do Google com a Composio.

Por que vejo “App is blocked” ao conectar o Google Maps?

O cliente OAuth está solicitando escopos que o Google ainda não verificou para aquele cliente. Isso ocorre normalmente ao adicionar escopos extras além dos padrões. Remova os escopos adicionais da sua configuração de autenticação, ou crie seu próprio app OAuth e submeta os escopos para verificação. Veja composio.dev/auth/googleapps.

Por que recebo o erro “Google Maps API has not been used in project”?

Ao usar credenciais OAuth personalizadas, a Google Maps API precisa estar habilitada no projeto do Google Cloud que possui essas credenciais. Habilite-a em APIs e Serviços no Cloud Console, aguarde alguns minutos e tente novamente.

Por que recebo “Error 400: invalid_scope”?

Os escopos solicitados estão inválidos ou formatados incorretamente na URL de autorização. Verifique os valores de escopo na documentação de escopos OAuth do Google.

Por que a tela de consentimento OAuth mostra “Composio” em vez do meu app?

Por padrão, a tela de consentimento usa o app OAuth da Composio. Para exibir o nome e logotipo do seu app, crie seu próprio app OAuth e configure um redirect URL personalizado. Veja White-labeling authentication.

Por que recebo erros 401 nas chamadas de ferramentas?

O token de acesso do usuário não é mais válido. Causas comuns: o usuário revogou o acesso, alterou senha ou 2FA, uma política do Workspace admin mudou, ou o limite de tokens de atualização do Google (~50 por conta) foi excedido. Reconectar a conta normalmente resolve.

Ações disponíveis

Autocompletar Previsões de Lugar

GOOGLE_MAPS_AUTOCOMPLETE

Retorna previsões de lugares e consultas para um texto de entrada. Use para implementar funcionalidade de autocomplete enquanto o usuário digita em buscas de lugares. Retorna até cinco previsões ordenadas por relevância.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
input	string	Sim	Texto para buscar previsões de lugares. Pode ser palavras completas, substrings, nomes de lugares, endereços ou plus codes. Não pode estar vazio.
origin	object	Não	Ponto de latitude/longitude para cálculos de distância.
regionCode	string	Não	Código de região no formato ccTLD para formatação das respostas (ex.: us, br).
inputOffset	integer	Não	Deslocamento Unicode baseado em zero da posição do cursor na string de entrada.
languageCode	string	Não	Idioma preferido para os resultados usando códigos IETF BCP-47 (ex.: en-US, es-ES).
locationBias	object	Não	Área para viesar os resultados da busca.
sessionToken	string	Não	String gerada pelo usuário agrupando chamadas em sessões para fins de cobrança.
includedRegionCodes	array	Não	Até 15 códigos de país de dois caracteres (ISO 3166-1 Alpha-2) para restringir os resultados. Previsões de consulta não ficam disponíveis quando este campo está definido.
locationRestriction	object	Não	Área para restringir os resultados da busca.
includedPrimaryTypes	array	Não	Restringe os resultados a até cinco tipos primários especificados (ex.: restaurant, cafe).
includeQueryPredictions	boolean	Não	Inclui previsões de consulta na resposta para buscas de texto (padrão: false).
includePureServiceAreaBusinesses	boolean	Não	Inclui empresas sem localização física (padrão: false).

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Calcular Matriz de Rotas

GOOGLE_MAPS_COMPUTE_ROUTE_MATRIX

Calcula matriz de distância e duração de viagem entre múltiplas origens e destinos usando a Routes API moderna; suporta autenticação OAuth2 e vários modos de transporte. A matriz é limitada a 625 elementos (ex.: 25×25); divida conjuntos maiores em lotes para evitar erros RESOURCE_EXHAUSTED. Os elementos da resposta podem ser retornados fora da ordem de entrada — sempre use originIndex e destinationIndex para mapear os resultados. Use apenas elementos onde condition='ROUTE_EXISTS'; a matriz pode estar incompleta.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
units	string (METRIC | IMPERIAL)	Não	Sistema de unidades (ex.: METRIC para quilômetros, IMPERIAL para milhas) para exibição de distâncias. distanceMeters nas respostas é sempre em metros, independentemente desta configuração; units afeta apenas a saída de texto legível.
origins	array	Sim	Lista de localizações de origem. Cada uma pode ser especificada como endereço ou coordenadas de latitude/longitude.
fieldMask	string	Não	Lista separada por vírgulas de campos da resposta a incluir (ex.: originIndex,destinationIndex,duration,distanceMeters). Use * para todos os campos.
travelMode	string (DRIVE | BICYCLE | WALK | TWO_WHEELER | TRANSIT)	Não	Modo de transporte para o cálculo da matriz de rotas.
destinations	array	Sim	Lista de localizações de destino. Cada uma pode ser especificada como endereço ou coordenadas de latitude/longitude.
languageCode	string	Não	Código de idioma BCP-47 (ex.: en-US, es) para informações textuais.
routingPreference	string (ROUTING_PREFERENCE_UNSPECIFIED | TRAFFIC_UNAWARE | TRAFFIC_AWARE | TRAFFIC_AWARE_OPTIMAL)	Não	Especifica fatores a considerar no cálculo da rota.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Matriz de Distâncias (Legada)

GOOGLE_MAPS_DISTANCE_MATRIX_API

DESCONTINUADA: API legada que calcula distância e tempo de viagem para uma matriz de origens e destinos. Esta API funciona apenas com chaves de API (sem suporte a OAuth2). Use a ação moderna “Calcular Matriz de Rotas” (GOOGLE_MAPS_COMPUTE_ROUTE_MATRIX), que suporta autenticação OAuth2. Suporta diferentes modos de transporte e opções como horários de partida/chegada. Limitada a 100 elementos por requisição (elementos = contagem de origens × destinos); divida conjuntos grandes em lotes.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
key	string	Não	Chave de API da sua aplicação. Essa chave identifica sua aplicação para fins de gerenciamento de cota.
mode	string (driving | walking | bicycling | transit)	Não	Especifica o modo de transporte a usar.
avoid	string (tolls | highways | ferries | indoor)	Não	Indica que a rota calculada deve evitar as características especificadas. Múltiplos valores podem ser separados por pipe, ex.: tolls|highways.
units	string (metric | imperial)	Não	Especifica o sistema de unidades para exibição dos resultados. O padrão é métrico.
region	string	Não	Código de região, especificado como valor ccTLD de dois caracteres. Ajuda a influenciar os resultados com base na região.
origins	string	Sim	Ponto de partida para cálculo de distância e tempo de viagem. Pode fornecer um ou mais locais separados pelo caractere pipe (|), no formato de ID de lugar (prefixado com place_id:), endereço, coordenadas de latitude/longitude, plus code ou polyline codificada (prefixada com enc: e dois pontos).
language	string	Não	Idioma para retornar os resultados.
arrival_time	integer	Não	Horário de chegada desejado para rotas de trânsito, em segundos desde meia-noite de 1º de janeiro de 1970 UTC. Não pode ser usado junto com departure_time.
destinations	string	Sim	Um ou mais locais para usar como ponto final no cálculo de distância e tempo de viagem. Aceita os mesmos formatos que origins.
transit_mode	string (bus | subway | train | tram | rail)	Não	Especifica um ou mais modos de trânsito preferidos. Só pode ser usado para rotas de trânsito. Múltiplos valores podem ser separados por pipe, ex.: bus|train.
traffic_model	string (best_guess | pessimistic | optimistic)	Não	Especifica as premissas para calcular tempo no trânsito. Só é usado se a requisição inclui departure_time e o modo é driving.
departure_time	string	Não	Horário de partida desejado. Pode ser especificado como inteiro em segundos desde meia-noite de 1º de janeiro de 1970 UTC, ou como a string now. Obrigatório para duration_in_traffic.
transit_routing_preference	string (less_walking | fewer_transfers)	Não	Especifica preferências para rotas de trânsito. Só pode ser usado para rotas de trânsito.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Geocodificar Endereço

GOOGLE_MAPS_GEOCODE_ADDRESS

DESCONTINUADA: API legada para converter endereços em coordenadas geográficas (latitude e longitude). Esta API funciona melhor com autenticação por chave de API. Para conexões OAuth sem chave de API, pode ser necessário fornecer o parâmetro key ou usar a ação mais nova “Busca por Texto” (GOOGLE_MAPS_TEXT_SEARCH). Use quando precisar geocodificar um endereço ou localização para obter suas coordenadas precisas de latitude/longitude.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
key	string	Não	Chave de API da sua aplicação. Obrigatório ao usar autenticação por chave de API. Se não fornecida, tentará usar autenticação OAuth (requer cabeçalho X-Goog-User-Project com ID do projeto).
bounds	string	Não	Caixa delimitadora do viewport dentro do qual viesar os resultados de geocodificação. Formato: southwest_lat,southwest_lng|northeast_lat,northeast_lng. Influencia, mas não restringe totalmente, os resultados.
region	string	Não	Código de região especificado como valor ccTLD de dois caracteres. Influencia, mas não restringe totalmente, os resultados.
address	string	Não	Endereço a geocodificar, no formato usado pelo serviço postal nacional do país em questão. Evite elementos adicionais como nomes comerciais e números de unidade/suíte/andar. Se address e components forem fornecidos, address tem precedência.
language	string	Não	Idioma para retornar os resultados.
components	string	Não	Filtros de componente separados por pipe (|). Cada filtro é um par componente:valor. Exemplos: country:US ou postal_code:94043|country:US.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Geocodificar Endereço por Consulta

GOOGLE_MAPS_GEOCODE_ADDRESS_WITH_QUERY

Converte um endereço textual em coordenadas geográficas usando a API v4beta moderna. Os resultados podem corresponder a múltiplos lugares — sempre verifique formattedAddress, region e addressComponents antes de usar as coordenadas retornadas.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
region_code	string	Não	Código de região especificado como valor ccTLD de dois caracteres (ex.: US, FR). Afeta os resultados com base na lei aplicável.
address_query	string	Sim	Endereço não estruturado a geocodificar. Deve ser uma única string com o endereço completo (ex.: 1600 Amphitheatre Parkway Mountain View CA). Inclua cidade, estado/região e país quando possível — strings incompletas ou ambíguas podem retornar zero resultados ou correspondências incorretas.
language_code	string	Não	Idioma para retornar os resultados (ex.: en, es, fr).

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Geocodificar Destinos

GOOGLE_MAPS_GEOCODE_DESTINATIONS

Realiza lookup de destino e retorna informações detalhadas, incluindo lugar principal, lugares contidos, sub-destinos, marcos, entradas e pontos de navegação. Use quando precisar de dados abrangentes de destino para um endereço, ID de lugar ou coordenadas geográficas.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
place	string	Não	Nome do recurso no formato places/{placeId} para recuperar destino pelo ID de lugar.
regionCode	string	Não	Código de região ccTLD de dois caracteres para formatação/filtragem (ex.: US, UK).
travelModes	array	Não	Filtra pontos de navegação por modo de transporte. Valores suportados: DRIVE, WALK.
addressQuery	object	Não	Consulta de endereço em formato não estruturado ou estruturado.
languageCode	string	Não	Código de idioma preferido para os resultados (ex.: en, es, fr).
locationQuery	object	Não	Consulta de localização usando coordenadas geográficas.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Geocodificação Reversa de Localização

GOOGLE_MAPS_GEOCODE_LOCATION

Converte coordenadas geográficas (latitude e longitude) em endereços legíveis por humanos usando geocodificação reversa. Um único par de coordenadas pode retornar múltiplos resultados; verifique formattedAddress, region e addressComponents antes de confirmar um resultado.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
types	array	Não	Conjunto de tags de tipo para restringir os resultados; resultados sem os tipos especificados são removidos.
latitude	number	Sim	Coordenada de latitude em graus, intervalo [-90.0, +90.0].
longitude	number	Sim	Coordenada de longitude em graus, intervalo [-180.0, +180.0].
regionCode	string	Não	Código de região especificado como valor ccTLD de dois caracteres, afetando os resultados com base na lei aplicável.
languageCode	string	Não	Código de idioma para retornar os resultados (formato BCP-47).

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Geocodificar Lugar por ID

GOOGLE_MAPS_GEOCODE_PLACE

Realiza lookup de geocodificação usando um identificador de lugar para recuperar endereço e coordenadas. Use quando precisar de informações geográficas detalhadas para um ID de lugar específico do Google.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
place_id	string	Sim	Identificador de lugar a geocodificar. Deve estar no formato places/{placeId} ou apenas o ID do lugar (ex.: ChIJj61dQgK6j4AR4GeTYWZsKWw). Identificador único de um lugar no banco de dados do Google Places.
regionCode	string	Não	Código de região especificado como valor ccTLD de dois caracteres, afetando os resultados com base na lei aplicável e formatação de endereço.
languageCode	string	Não	Código de idioma para retornar os resultados (formato BCP-47). O padrão é en se não especificado.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

API de Geocodificação

GOOGLE_MAPS_GEOCODING_API

Converte endereços em coordenadas geográficas (latitude e longitude) e vice-versa (geocodificação reversa), ou obtém um endereço para um ID de lugar. Usa a Geocoding API v4 (v4beta), que suporta autenticação OAuth2. Exatamente um dos campos address, latlng ou place_id deve ser fornecido por requisição; omitir todos os três ou misturar combinações incompatíveis não produzirá resultados úteis.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
key	string	Não	Chave de API da sua aplicação. Se não fornecida, será extraída dos metadados da conexão.
bounds	string	Não	Caixa delimitadora do viewport para viesar os resultados (ex.: 34.172684,-118.604794|34.236144,-118.500938). Influencia, mas não restringe totalmente, os resultados.
latlng	string	Não	Coordenadas de latitude e longitude para geocodificação reversa (ex.: 40.714224,-73.961452).
region	string	Não	Código de região especificado como valor ccTLD de dois caracteres. Influencia, mas não restringe totalmente, os resultados.
address	string	Não	Endereço ou plus code a geocodificar.
language	string	Não	Idioma para retornar os resultados.
place_id	string	Não	ID de lugar para obter o endereço legível correspondente.
components	string	Não	Filtro de componentes separado por pipe (|). Ex.: postal_code:94043|country:US. Fornecer apenas components sem address pode retornar ZERO_RESULTS para algumas consultas.
result_type	string	Não	Filtro de um ou mais tipos de endereço, separados por pipe (|). Ex.: street_address|locality.
location_type	string	Não	Filtro de um ou mais tipos de localização, separados por pipe (|). Ex.: ROOFTOP|RANGE_INTERPOLATED.
extra_computations	array	Não	Especifica funcionalidades adicionais na resposta. Permite múltiplos valores.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Geolocalizar Dispositivo

GOOGLE_MAPS_GEOLOCATE

Determina a localização com base em torres de celular e pontos de acesso WiFi. Use quando precisar encontrar a localização geográfica de um dispositivo usando dados de infraestrutura de rede.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
carrier	string	Não	Nome da operadora.
radioType	string (gsm | cdma | wcdma | lte | nr)	Não	Tipo de rádio. Padrão: gsm.
cellTowers	array	Não	Array de objetos de torres de celular.
considerIp	boolean	Não	Se deve recorrer à geolocalização por IP caso os sinais WiFi e de torres de celular estejam ausentes. Padrão: true.
wifiAccessPoints	array	Não	Array de objetos de pontos de acesso WiFi (mínimo de 2 necessários para sucesso).
homeMobileCountryCode	integer	Não	Código de país móvel da rede doméstica do dispositivo. Intervalo: 0–999.
homeMobileNetworkCode	integer	Não	MNC para GSM/WCDMA/LTE/NR (0–999); SID para CDMA (0–32767).

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter Tile de Mapa 2D

GOOGLE_MAPS_GET2D_TILE

Recupera uma imagem de tile de mapa 2D nas coordenadas especificadas para criar visualizações de mapa personalizadas. Use quando precisar baixar imagens individuais de tiles de mapa para visualizações de roadmap, satélite ou terreno. Requer um token de sessão válido do endpoint createSession.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
x	integer	Sim	Coordenada de coluna do tile. Intervalo válido: [0, (2^zoom)-1].
y	integer	Sim	Coordenada de linha do tile. Intervalo válido: [0, (2^zoom)-1].
z	integer	Sim	Nível de zoom de 0 (mundo inteiro) a 22 (altamente detalhado).
key	string	Não	Chave de API do Google para autenticação. Se não fornecida, será extraída dos metadados da conexão. Necessária se não usar token Bearer.
session	string	Sim	UUID de token de sessão obtido do endpoint /v1/createSession. Válido por aproximadamente duas semanas. Reutilize entre múltiplas requisições de tile; cada chamada createSession consome cota.
orientation	integer	Não	Parâmetro de rotação em graus no sentido anti-horário. Valores válidos: 0, 90, 180 ou 270.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter Raiz de Tiles 3D

GOOGLE_MAPS_GET3D_TILES_ROOT

Recupera a configuração raiz do tileset 3D para renderização fotorrealista de mapas 3D. Use quando precisar inicializar um renderizador 3D com os tiles fotorrealistas do Google seguindo a especificação OGC 3D Tiles. A Map Tiles API é cobrada por requisição; armazene em cache a resposta raiz no lado do cliente e evite chamadas repetidas.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
key	string	Não	Sua chave de API do Google Maps com a Map Tiles API habilitada. Se não fornecida, será extraída dos metadados da conexão.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter Direções

GOOGLE_MAPS_GET_DIRECTION

Busca direções detalhadas entre uma origem e um destino, suportando waypoints intermediários e vários modos de transporte. Usa automaticamente a Routes API moderna com OAuth2 quando disponível, com fallback para a API legada com chave de API se fornecida.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
mode	string (driving | walking | bicycling | transit)	Não	Modo de transporte para calcular as direções.
avoid	string	Não	Especifica características a evitar na rota gerada. Múltiplos valores podem ser combinados com pipe (ex.: tolls|highways). Opções válidas: tolls, highways, ferries.
units	string (metric | imperial)	Não	Sistema de unidades para exibição de distâncias. Padrão: imperial.
origin	string	Sim	Ponto de partida para as direções. Pode ser um endereço textual (ex.: 123 Main St, Los Angeles, CA), nome de lugar (ex.: Disneyland) ou coordenadas de latitude/longitude (ex.: 34.0522,-118.2437).
language	string	Não	Código de idioma para retornar os resultados, ex.: en para inglês, es para espanhol. Padrão: en.
waypoints	string	Não	String separada por pipe (|) de locais intermediários (endereços, nomes de lugares ou coordenadas) a visitar entre a origem e o destino. Ex.: Anaheim, CA|Long Beach, CA ou Hollywood Bowl|Getty Center.
destination	string	Sim	Ponto de chegada para as direções. Pode ser um endereço textual (ex.: 456 Park Ave, New York, NY), nome de lugar (ex.: Universal Studios Hollywood) ou coordenadas (ex.: 40.7128,-74.0060).

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter Detalhes de Lugar

GOOGLE_MAPS_GET_PLACE_DETAILS

Recupera detalhes abrangentes de um lugar usando seu nome de recurso (formato places/{place_id}). Use quando precisar de informações detalhadas sobre um lugar específico.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
name	string	Sim	ID de lugar do Google APENAS — um código alfanumérico (NÃO um nome comercial, endereço ou consulta de busca). Aceita places/{place_id} ou apenas o place_id. IDs de lugar normalmente começam com ChIJ seguido de caracteres alfanuméricos. Para encontrar um ID de lugar a partir de um nome comercial, use primeiro TEXT_SEARCH ou NEARBY_SEARCH.
fieldMask	string	Não	Lista separada por vírgulas de campos a retornar (sem espaços). Use * para todos os campos (não recomendado por desempenho/custo). Campos comuns: id, displayName, formattedAddress, location, types, rating, photos, reviews, regularOpeningHours, nationalPhoneNumber, internationalPhoneNumber, websiteUri, googleMapsUri.
regionCode	string	Não	Código de país/região Unicode (formato CLDR) para nomes de exibição específicos por região. Ex.: US, GB, FR, JP.
languageCode	string	Não	Código de idioma preferido para os detalhes do lugar (formato BCP-47). Ex.: en, es, fr, ja.
sessionToken	string	Não	String base64 URL-safe (máx. 36 caracteres) para cobrança de sessão do Autocomplete.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter Rota

GOOGLE_MAPS_GET_ROUTE

Calcula uma ou mais rotas entre dois locais especificados. Usa vários modos de transporte e preferências; os endereços devem ser resolvíveis pelo Google Maps. O campo duration na resposta é uma string com sufixo s (ex.: "4557s"); analise antes de exibir.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
units	string (METRIC | IMPERIAL)	Não	Sistema de unidades para exibição de distâncias. routes.distanceMeters na resposta é sempre em metros; units afeta apenas a formatação de distância legível em outros campos.
fieldMask	string	Não	Lista separada por vírgulas de campos do objeto Route a incluir na resposta. Se não especificado, um fieldMask padrão é usado com base no travelMode. Inclua explicitamente todos os campos necessários, como routes.legs.steps e routes.polyline.encodedPolyline.
travelMode	string (DRIVE | BICYCLE | WALK | TWO_WHEELER | TRANSIT)	Não	Modo de transporte para a rota.
languageCode	string	Não	Código de idioma BCP-47 (ex.: en-US, es) para informações textuais como instruções de navegação.
origin_address	string	Sim	Ponto de partida para o cálculo da rota. Pode ser um endereço (ex.: 1600 Amphitheatre Parkway, Mountain View, CA) ou coordenadas como latitude,longitude (ex.: 48.8566,2.3522).
routingPreference	string (ROUTING_PREFERENCE_UNSPECIFIED | TRAFFIC_UNAWARE | TRAFFIC_AWARE | TRAFFIC_AWARE_OPTIMAL)	Não	Preferência de roteamento. Não pode ser definida quando travelMode for WALK, BICYCLE ou TRANSIT.
destination_address	string	Sim	Ponto de destino para o cálculo da rota. Pode ser um endereço ou coordenadas como latitude,longitude.
computeAlternativeRoutes	boolean	Não	Calcula e retorna rotas alternativas se verdadeiro.
routeModifiers_avoidTolls	boolean	Não	Tenta evitar estradas com pedágio se verdadeiro.
routeModifiers_avoidFerries	boolean	Não	Tenta evitar balsas se verdadeiro.
routeModifiers_avoidHighways	boolean	Não	Tenta evitar rodovias se verdadeiro.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Buscar Vídeo Aéreo

GOOGLE_MAPS_LOOKUP_AERIAL_VIDEO

Busca um vídeo de vista aérea por endereço ou ID de vídeo. Retorna metadados do vídeo incluindo estado e URIs para reprodução. Use quando precisar recuperar um vídeo aéreo renderizado anteriormente ou verificar o status de uma requisição de renderização. Receber um vídeo é um evento cobrado.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
address	string	Não	Endereço postal nos EUA. videoId ou address deve ser fornecido, mas não ambos.
videoId	string	Não	ID retornado pelo videos.renderVideo. videoId ou address deve ser fornecido, mas não ambos.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Incorporar Google Maps

GOOGLE_MAPS_MAPS_EMBED_API

Gera uma URL de mapa do Google incorporável e código HTML de iframe. Use quando precisar exibir um mapa (lugar, visualização, direções, street view, busca) em uma página web sem JavaScript. Esta API funciona apenas com chaves de API (sem suporte a OAuth2). Gera URLs de incorporação e não faz chamadas diretas de API. As URLs de incorporação geradas são acessíveis publicamente; evite passar consultas de localização sensíveis ou internas.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
mode	string (place | view | directions | streetview | search)	Sim	Modo do mapa incorporado.
api_key	string	Não	Chave de API do Google Maps. Necessária se não fornecida via metadados da conexão. A Maps Embed API suporta apenas autenticação por chave de API, não OAuth.
view_params	object	Não	Parâmetros para o modo view.
place_params	object	Não	Parâmetros para o modo place.
search_params	object	Não	Parâmetros para o modo search.
directions_params	object	Não	Parâmetros para o modo directions.
streetview_params	object	Não	Parâmetros para o modo streetview.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Busca por Proximidade

GOOGLE_MAPS_NEARBY_SEARCH

Busca lugares (ex.: restaurantes, parques) dentro de uma área circular especificada, com opções para filtrar por tipos de lugar e personalizar os campos retornados e o número de resultados.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
radius	number	Sim	Raio da área de busca circular em metros.
latitude	number	Sim	Coordenada de latitude do centro da busca em graus decimais.
fieldMask	string	Não	Lista separada por vírgulas de campos de lugar para a resposta. Campos são automaticamente prefixados com places. se ausente. Use * para todos os campos (não recomendado para produção).
longitude	number	Sim	Coordenada de longitude do centro da busca em graus decimais.
excludedTypes	array	Não	Lista de tipos de lugar da Tabela A a excluir. Resultados que correspondam a qualquer um desses tipos são omitidos. Até 50 tipos permitidos.
includedTypes	array	Não	Lista de tipos de lugar da Tabela A a incluir. Os resultados corresponderão a pelo menos um desses tipos. Até 50 tipos permitidos. Tipos comuns: restaurant, cafe, bank, atm, hospital, pharmacy, school, park, gym, hotel, airport, gas_station.
maxResultCount	integer	Não	Número máximo de resultados a retornar. Intervalo válido: 1–20.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter Foto de Lugar

GOOGLE_MAPS_PLACE_PHOTO

Recupera conteúdo fotográfico de alta qualidade do banco de dados do Google Maps Places. Use quando precisar baixar uma foto de lugar usando uma photo_reference obtida de requisições de Detalhes de Lugar, Busca por Proximidade ou Busca por Texto. As imagens são dimensionadas proporcionalmente para caber nas dimensões especificadas.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
maxwidth	integer	Não	Largura máxima desejada da imagem em pixels (1–1600). A imagem será dimensionada proporcionalmente. Deve especificar maxwidth, maxheight ou ambos.
maxheight	integer	Não	Altura máxima desejada da imagem em pixels (1–1600). A imagem será dimensionada proporcionalmente. Deve especificar maxwidth, maxheight ou ambos.
photo_reference	string	Sim	Identificador de string que identifica exclusivamente uma foto. Pode ser: (1) nome completo do recurso de foto no formato places/{place_id}/photos/{photo} da nova Places API, ou (2) apenas a string de referência de foto da API legada. Obtida de Detalhes de Lugar, Busca por Proximidade ou Busca por Texto. Referências de fotos não podem ser armazenadas em cache e podem expirar ao longo do tempo.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Renderizar Vídeo Aéreo

GOOGLE_MAPS_RENDER_AERIAL_VIDEO

Inicia a renderização de um vídeo de vista aérea para um endereço postal nos EUA. Retorna um ID de vídeo que pode ser usado com lookupVideo para recuperar o vídeo após a conclusão da renderização. A renderização normalmente leva até algumas horas.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
address	string	Sim	Endereço postal nos EUA para o qual renderizar o vídeo aéreo. Deve ser um endereço válido nos EUA com rua, cidade, estado e CEP.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Busca por Texto

GOOGLE_MAPS_TEXT_SEARCH

Busca lugares no Google Maps usando uma consulta textual (ex.: “restaurantes em Londres”, “Torre Eiffel”). Os resultados podem incluir lugares com CLOSED_PERMANENTLY ou TEMPORARILY_CLOSED — filtre por businessStatus=OPERATIONAL. Inclua cidade/região e tipo de negócio no textQuery para evitar resultados vazios ou irrelevantes. Deduplique usando id ou formattedAddress, não apenas name. Limite a ~1 req/s; OVER_QUERY_LIMIT (HTTP 429) requer backoff exponencial.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
fieldMask	string	Não	Lista separada por vírgulas de campos de lugar a retornar. O prefixo places. é opcional e será adicionado automaticamente. Use * para todos os campos (não recomendado por desempenho/custo). Aliases comuns são suportados: name→displayName, address→formattedAddress, url/website→websiteUri.
textQuery	string	Sim	Consulta de texto para buscar lugares. Correspondida com nome, endereço e categoria do lugar. Consultas subespecificadas (sem cidade, região ou tipo de negócio) retornam resultados vazios ou irrelevantes.
maxResultCount	integer	Não	Número máximo de resultados de lugar a retornar (deve ser 1–20).

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Criar Sessão de Tiles

GOOGLE_MAPS_TILES_CREATE_SESSION

Cria um token de sessão necessário para acessar tiles 2D e imagens do Street View. Use quando precisar inicializar renderização de mapas baseada em tiles ou exibição de Street View. O token de sessão é válido por aproximadamente duas semanas e deve ser incluído em todas as requisições de tile subsequentes. Cada chamada consome cota — armazene em cache e reutilize o token retornado em todas as requisições de tile dentro do seu período de validade, em vez de criar uma nova sessão por requisição.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
scale	string (scaleFactor1x | scaleFactor2x | scaleFactor4x)	Não	Fator de escala de rótulos para displays de alta resolução. Valores válidos: scaleFactor1x (padrão), scaleFactor2x (resolução 2x) ou scaleFactor4x (resolução 4x).
region	string	Sim	Código de região CLDR de dois caracteres representando a localização do usuário (ex.: US, GB, FR). Ajuda o Google Maps a fornecer conteúdo específico para a região.
styles	array	Não	Objetos de estilo JSON para personalizar a aparência do mapa (apenas roadmap). Permite estilização personalizada de recursos como estradas, edifícios e marcos.
highDpi	boolean	Não	Habilita tiles de alta resolução para displays de alta DPI. Funciona apenas com fatores de escala 2x ou 4x.
mapType	string (roadmap | satellite | terrain | streetview)	Sim	Tipo de mapa base. Valores válidos: roadmap para mapa de estradas padrão, satellite para imagens de satélite, terrain para mapas de terreno, ou streetview para imagens do Street View.
overlay	boolean	Não	Renderiza camadas do mapa separadamente (true) ou combinadas em uma única imagem (false).
language	string	Sim	Tag de idioma IETF especificando o idioma de exibição para rótulos e informações do mapa (ex.: en-US, es-ES, fr-FR).
layerTypes	array	Não	Opções de sobreposição para o mapa. Valores válidos: layerRoadmap (sobreposição de estradas), layerStreetview (sobreposição do Street View), layerTraffic (camada de tráfego). O tipo de mapa terrain requer layerRoadmap.
imageFormat	string (jpeg | png)	Não	Formato de saída para imagens de tiles. Valores válidos: jpeg ou png. Se omitido, o formato será selecionado automaticamente pela API.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.