Merge pull request #92 from markmcd/maps-grnd

Maps grounding examples

Author: markmcd

javascript/grounding.js

@@ -0,0 +1,73 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { GoogleGenAI } from "@google/genai";
+
+// Ensure the API key is set in your environment variables
+if (!process.env.GEMINI_API_KEY) {
+  throw new Error("GEMINI_API_KEY environment variable not set.");
+}
+
+// Define the thinking model centrally
+const MODEL_ID = "gemini-2.5-flash";
+
+const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
+
+export async function groundingWithMaps() {
+  // [START grounding_maps]
+  /**
+   * Generates text using Google Maps as a grounding tool.
+   */
+
+  const prompt =
+    "What are the best Italian restaurants within a 15-minute walk from here?";
+
+  const locationContext = {
+    latLng: {
+      latitude: 34.050481,
+      longitude: -118.248526,
+    },
+  };
+
+  const response = await ai.models.generateContent({
+    model: MODEL_ID,
+    contents: prompt,
+    config: {
+      tools: [{ googleMaps: {} }],
+      toolConfig: {
+        retrievalConfig: locationContext,
+      },
+    },
+  });
+
+  console.log(response.text);
+
+  const grounding = response.candidates[0]?.groundingMetadata;
+  if (grounding?.groundingChunks) {
+    console.log("-".repeat(40));
+    console.log("Sources:");
+    for (const chunk of grounding.groundingChunks) {
+      if (chunk.maps) {
+        console.log(`- [${chunk.maps.title}](${chunk.maps.uri})`);
+      }
+    }
+  }
+
+  return response;
+  // [END grounding_maps]
+}
+

javascript/grounding.test.js

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import assert from "node:assert";
+import { test, describe } from "node:test";
+
+import {
+  groundingWithMaps
+} from "./grounding.js"; 
+
+describe("grounding", { timeout: 300000 }, () => {
+  test("groundingWithMaps", async () => {
+    const result = await groundingWithMaps();
+    assert.ok(
+        result?.text?.length > 0,
+        "Test failed: No result or empty result"
+    );
+    // TODO: test for grounding data in response
+  });
+});
+

javascript/package-lock.json

@@ -11,7 +11,7 @@
   "description": "",
   "type": "module",
   "dependencies": {
-    "@google/genai": "^0.9.0"
+    "@google/genai": "^1.24.0"
   },
   "devDependencies": {
     "prettier": "^3.5.3"

javascript/package.json

@@ -0,0 +1,68 @@
+# -*- coding: utf-8 -*-
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from absl.testing import absltest
+
+MODEL_ID = "gemini-2.5-flash"
+
+
+class GroundingUnitTests(absltest.TestCase):
+
+    def test_grounding_maps(self):
+        # [START grounding_maps]
+        """Generates text using Google Maps as a grounding tool."""
+        from google import genai
+        from google.genai.types import GenerateContentConfig, GoogleMaps, LatLng, RetrievalConfig, Tool, ToolConfig
+
+        client = genai.Client()
+
+        maps_tool = Tool(
+            google_maps=GoogleMaps()
+        )
+
+        location_context = RetrievalConfig(
+            lat_lng=LatLng(latitude=34.050481, longitude=-118.248526)
+        )
+
+        prompt = "What are the best Italian restaurants within a 15-minute walk from here?"
+        
+        response = client.models.generate_content(
+            model=MODEL_ID,
+            contents=prompt,
+            config=GenerateContentConfig(
+                tools=[maps_tool],
+                tool_config=ToolConfig(retrieval_config=location_context),
+            )
+        )
+
+        # Display the text output.
+        print(response.text)
+
+        # Display the grounding sources.
+        if grounding := response.candidates[0].grounding_metadata:
+          if grounding.grounding_chunks:
+            print('-' * 40)
+            print("Sources:")
+            for chunk in grounding.grounding_chunks:
+              print(f'- [{chunk.maps.title}]({chunk.maps.uri})')
+
+          if widget_token := grounding.google_maps_widget_context_token:
+            print('-' * 40)
+            print(f'Maps token: {widget_token[:14]}...')
+        # [END grounding_maps]
+
+if __name__ == "__main__":
+    absltest.main()
+

python/grounding.py

@@ -0,0 +1,23 @@
+set -eu
+
+echo "[START grounding_maps]"
+# [START grounding_maps]
+curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent' \
+  -H 'Content-Type: application/json' \
+  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
+  -d '{
+  "contents": [{
+    "role": "user",
+    "parts": [{
+      "text": "What are the best Italian restaurants within a 15-minute walk from here?"
+    }]
+  }],
+  "tools": [{"googleMaps": {}}],
+  "toolConfig": {
+    "retrievalConfig": {
+      "latLng": {"latitude": 34.050481, "longitude": -118.248526}
+    }
+  }
+}'
+
+# [END grounding_maps]