Embasamento com o Google Maps

O embasamento com o Google Maps conecta os recursos generativos do Gemini aos dados ricos, factuais e atualizados do Google Maps. Com esse recurso, os desenvolvedores podem incorporar facilmente funcionalidades com reconhecimento de local aos aplicativos. Quando uma consulta do usuário tem um contexto relacionado a dados do Maps, o modelo do Gemini usa o Google Maps para fornecer respostas factuais, atualizadas e relevantes para o local ou a área geral especificada pelo usuário.

  • Respostas precisas e com reconhecimento de local: aproveite os dados extensos e atuais do Google Maps para consultas geograficamente específicas.
  • Personalização aprimorada:personalize recomendações e informações com base nos locais fornecidos pelo usuário.
  • Informações contextuais e widgets:tokens contextuais para renderizar widgets interativos do Google Maps ao lado do conteúdo gerado.

Primeiros passos

Este exemplo demonstra como integrar o embasamento com o Google Maps ao seu aplicativo para fornecer respostas precisas e com reconhecimento de local às consultas do usuário. O comando pede recomendações locais com uma localização opcional do usuário, permitindo que o modelo do Gemini use os dados do Google Maps.

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="What are the best Italian restaurants within a 15-minute walk from here?",
    tools=[{
        "type": "google_maps",
        "latitude": 34.050481,
        "longitude": -118.248526
    }]
)

# Print the model's text response and annotations
for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
                if content_block.annotations:
                    print("\nSources:")
                    for annotation in content_block.annotations:
                        if annotation.type == "place_citation":
                            print(f"  - {annotation.name}: {annotation.url}")

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    input: "What are the best Italian restaurants within a 15-minute walk from here?",
    tools: [{
      type: "google_maps",
      latitude: 34.050481,
      longitude: -118.248526
    }]
  });

  // Print the model's text response and annotations
  for (const step of interaction.steps) {
    if (step.type === 'model_output') {
      for (const contentBlock of step.content) {
        if (contentBlock.type === 'text') {
          console.log(contentBlock.text);
          if (contentBlock.annotations) {
            console.log("\nSources:");
            for (const annotation of contentBlock.annotations) {
              if (annotation.type === 'place_citation') {
                console.log(`  - ${annotation.name}: ${annotation.url}`);
              }
            }
          }
        }
      }
    }
  }
}

main();

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "What are the best Italian restaurants within a 15-minute walk from here?",
    "tools": [{
      "type": "google_maps",
      "latitude": 34.050481,
      "longitude": -118.248526
    }]
  }'

Como funciona o embasamento com o Google Maps

O embasamento com o Google Maps integra a API Gemini ao ecossistema do Google Geo usando a API Maps como fonte de embasamento. Quando a consulta de um usuário contém contexto geográfico, o modelo do Gemini pode invocar a ferramenta de embasamento com o Google Maps. Em seguida, o modelo pode gerar respostas baseadas em dados do Google Maps relevantes para o local fornecido.

O processo geralmente envolve:

  1. Consulta do usuário:um usuário envia uma consulta ao seu aplicativo, possivelmente incluindo contexto geográfico (por exemplo, "cafés perto de mim", "museus em São Francisco").
  2. Invocação de ferramenta:o modelo do Gemini, reconhecendo a intenção geográfica, invoca a ferramenta de embasamento com o Google Maps. Essa ferramenta pode ser fornecida com o latitude e o longitude do usuário. A ferramenta é de pesquisa textual e funciona de maneira semelhante à pesquisa no Maps. Consultas locais ("perto de mim") usam as coordenadas, enquanto consultas específicas ou não locais provavelmente não são influenciadas pela localização explícita.
  3. Recuperação de dados:o serviço de embasamento com o Google Maps consulta o Google Maps para obter informações relevantes (por exemplo, lugares, avaliações, fotos, endereços, horário de funcionamento).
  4. Geração embasada:os dados recuperados do Maps são usados para informar a resposta do modelo do Gemini, garantindo precisão e relevância factuais.
  5. Resposta e anotações:o modelo retorna uma resposta de texto com anotações inline que vinculam a fontes do Google Maps, permitindo que os desenvolvedores mostrem citações e renderizem um widget contextual do Google Maps, se quiserem.

Por que e quando usar o Embasamento com o Google Maps

O embasamento com o Google Maps é ideal para aplicativos que exigem informações precisas, atualizadas e específicas de um local. Ele melhora a experiência do usuário ao fornecer conteúdo relevante e personalizado com base no extenso banco de dados do Google Maps de mais de 250 milhões de lugares no mundo todo.

Use o embasamento com o Google Maps quando o aplicativo precisar:

  • Fornecer respostas completas e precisas para perguntas específicas de uma região.
  • Crie planejadores de viagens e guias locais de conversa.
  • Recomendar pontos de interesse com base na localização e nas preferências do usuário, como restaurantes ou lojas.
  • Crie experiências com reconhecimento de local para serviços de redes sociais, varejo ou entrega de comida.

O embasamento com o Google Maps é excelente em casos de uso em que a proximidade e os dados factuais atuais são essenciais, como encontrar o "melhor café perto de mim" ou receber rotas.

Casos de uso

O embasamento com o Google Maps oferece suporte a vários casos de uso com reconhecimento de local.

Como responder a perguntas específicas sobre um lugar

Faça perguntas detalhadas sobre um lugar específico para receber respostas com base nas avaliações dos usuários do Google e em outros dados do Maps.

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Is there a cafe near the corner of 1st and Main that has outdoor seating?",
    tools=[{
        "type": "google_maps",
        "latitude": 34.050481,
        "longitude": -118.248526
    }]
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
                if content_block.annotations:
                    print("\nSources:")
                    for annotation in content_block.annotations:
                        if annotation.type == "place_citation":
                            print(f"  - {annotation.name}: {annotation.url}")

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    input: "Is there a cafe near the corner of 1st and Main that has outdoor seating?",
    tools: [{
      type: "google_maps",
      latitude: 34.050481,
      longitude: -118.248526
    }]
  });

  for (const step of interaction.steps) {
    if (step.type === 'model_output') {
      for (const contentBlock of step.content) {
        if (contentBlock.type === 'text') {
          console.log(contentBlock.text);
          if (contentBlock.annotations) {
            console.log("\nSources:");
            for (const annotation of contentBlock.annotations) {
              if (annotation.type === 'place_citation') {
                console.log(`  - ${annotation.name}: ${annotation.url}`);
              }
            }
          }
        }
      }
    }
  }
}

main();

Fornecer personalização com base no local

Receber recomendações personalizadas de acordo com as preferências de um usuário e uma área geográfica específica.

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Which family-friendly restaurants near here have the best playground reviews?",
    tools=[{
        "type": "google_maps",
        "latitude": 30.2672,
        "longitude": -97.7431
    }]
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
                if content_block.annotations:
                    print("\nSources:")
                    for annotation in content_block.annotations:
                        if annotation.type == "place_citation":
                            print(f"  - {annotation.name}: {annotation.url}")

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    input: "Which family-friendly restaurants near here have the best playground reviews?",
    tools: [{
      type: "google_maps",
      latitude: 30.2672,
      longitude: -97.7431
    }]
  });

  for (const step of interaction.steps) {
    if (step.type === 'model_output') {
      for (const contentBlock of step.content) {
        if (contentBlock.type === 'text') {
          console.log(contentBlock.text);
          if (contentBlock.annotations) {
            console.log("\nSources:");
            for (const annotation of contentBlock.annotations) {
              if (annotation.type === 'place_citation') {
                console.log(`  - ${annotation.name}: ${annotation.url}`);
              }
            }
          }
        }
      }
    }
  }
}

main();

Ajuda com o planejamento de itinerários

Gere planos de vários dias com rotas e informações sobre vários locais, perfeito para aplicativos de viagens.

Python

from google import genai

client = genai.Client()

prompt = "Plan a day in San Francisco for me. I want to see the Golden Gate Bridge, visit a museum, and have a nice dinner."

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input=prompt,
    tools=[{
        "type": "google_maps",
        "latitude": 37.78193,
        "longitude": -122.40476,
        "enable_widget": True
    }]
)
# ... code to process response and widget token

JavaScript

const interaction = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: 'Plan a day in San Francisco for me. I want to see the Golden Gate Bridge, visit a museum, and have a nice dinner.',
    tools: [{
      type: "google_maps",
      latitude: 37.78193,
      longitude: -122.40476,
      enableWidget: true
    }],
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "Plan a day in San Francisco for me. I want to see the Golden Gate Bridge, visit a museum, and have a nice dinner.",
    "tools": [{
      "type": "google_maps",
      "latitude": 37.78193,
      "longitude": -122.40476,
      "enable_widget": true
    }]
  }'

Requisitos de uso do serviço

Esta seção descreve os requisitos de uso do serviço para o Grounding com o Google Maps.

Informar o usuário sobre o uso de fontes do Google Maps

Com cada resultado do Google Maps Grounded, você recebe anotações de origem nos blocos de conteúdo da etapa model_output que apoiam cada resposta. Os seguintes metadados são retornados:

  • URL de origem
  • nome

Ao apresentar resultados do embasamento com o Google Maps, especifique as fontes associadas do Google Maps e informe aos usuários o seguinte:

  • As fontes do Google Maps precisam aparecer imediatamente após o conteúdo gerado que elas embasam. Esse conteúdo gerado também é chamado de Resultado Embasado do Google Maps.
  • As fontes do Google Maps precisam estar visíveis em uma interação do usuário.

Mostrar fontes do Google Maps com links do Google Maps

Para cada anotação de origem, uma prévia do link precisa ser gerada seguindo estes requisitos:

  • Atribua cada fonte ao Google Maps seguindo as diretrizes de atribuição de texto do Google Maps.
  • Mostre o nome da fonte fornecido na resposta.
  • Vincule à fonte usando o url da anotação.

Diretrizes de atribuição de texto do Google Maps

Ao atribuir fontes ao Google Maps em texto, siga estas diretrizes:

  • Não modifique o texto do Google Maps de forma alguma:
    • Não mude a capitalização de Google Maps.
    • Não quebre o Google Maps em várias linhas.
    • Não localize o Google Maps para outro idioma.
    • Impeça que os navegadores traduzam o Google Maps usando o atributo HTML translate="no".

Para mais informações sobre alguns dos nossos provedores de dados do Google Maps e os termos de licença deles, consulte os avisos legais do Google Maps e do Google Earth.

Práticas recomendadas

  • Forneça a localização do usuário:para receber respostas mais relevantes e personalizadas, sempre inclua latitude e longitude na configuração da ferramenta google_maps quando a localização do usuário for conhecida.
  • Renderizar o widget contextual do Google Maps:o widget contextual é renderizado usando o token de contexto, google_maps_widget_context_token, que é retornado na resposta da API Gemini e pode ser usado para renderizar conteúdo visual do Google Maps.
  • Informe os usuários finais:deixe claro que os dados do Google Maps estão sendo usados para responder às consultas, principalmente quando a ferramenta está ativada.
  • Desativar quando não for necessário:o embasamento com o Google Maps fica desativado por padrão. Ative essa opção ("tools": [{"type": "google_maps"}]) somente quando uma consulta tiver um contexto geográfico claro para otimizar o desempenho e o custo.

Limitações

  • No momento, o embasamento com o Google Maps só aceita comandos e respostas em inglês.
  • A ferramenta pode não estar disponível em todas as regiões.
  • Os resultados podem variar de acordo com a precisão da localização e os dados disponíveis do Maps.
  • Escopo geográfico:o embasamento com o Google Maps está disponível no mundo todo.
  • Estado padrão:a ferramenta de embasamento com o Google Maps fica desativada por padrão. É necessário ativar explicitamente nas solicitações de API.

Preços e limites de taxa

O preço do embasamento com o Google Maps é baseado em consultas. A taxa atual é de US$25 / 1.000 comandos fundamentados. O nível sem custo financeiro também tem até 500 solicitações por dia disponíveis. Uma solicitação só é contabilizada na cota quando um comando retorna pelo menos um resultado embasado do Google Maps (ou seja, resultados que contêm pelo menos uma fonte do Google Maps). Se várias consultas forem enviadas ao Google Maps em uma única solicitação, isso será contabilizado como uma solicitação para o limite de taxa.

Para informações detalhadas sobre preços, consulte a página de preços da API Gemini.

Modelos compatíveis

Os seguintes modelos são compatíveis com o embasamento com o Google Maps:

Modelo Embasamento com o Google Maps
Pré-lançamento do Gemini 3.1 Pro ✔️
Gemini 3.1 Flash-Lite ✔️
Pré-lançamento do Gemini 3.1 Flash-Lite ✔️
Pré-lançamento do Gemini 3 Flash ✔️
Gemini 2.5 Pro ✔️
Gemini 2.5 Flash ✔️
Gemini 2.5 Flash-Lite ✔️
Gemini 2.0 Flash ✔️

Combinações de ferramentas compatíveis

Os modelos do Gemini 3 permitem combinar ferramentas integradas (como o embasamento com o Google Maps) e personalizadas (chamada de função). Saiba mais na página de combinações de ferramentas.

A seguir