# Grounding met Google Search in de Gemini API

[[TOC]]

## Wat is grounding

Grounding verbindt Gemini met externe kennisbronnen om antwoorden te onderbouwen met actuele informatie. Zonder grounding antwoordt Gemini op basis van trainingsdata, met een vaste kennisafsnijdatum. Met Google Search grounding kan het model real-time zoeken en verse informatie ophalen.

Dit lost twee problemen op: hallucinaties (het model verzint iets dat plausibel klinkt maar onjuist is) en verouderde informatie (het model weet niets van recente gebeurtenissen).

:::info title="Tool-naam is veranderd"
Verouderde modellen (Gemini 1.5) gebruikten de tool `google_search_retrieval` met een `dynamic_retrieval_config`. Voor alle huidige modellen (Gemini 2.5 en de Gemini 3-familie) gebruik je de eenvoudigere `google_search`-tool. Werk je nog met oude voorbeelden, dan zijn die hoogstwaarschijnlijk gebaseerd op de verouderde aanpak.
:::

## SDK installeren

De moderne aanpak gebruikt de `google-genai` SDK. De oudere `google-generativeai` SDK is uitgefaseerd, vermijd die voor nieuwe projecten.

```bash
pip install google-genai
```

## Google Search grounding inschakelen

```python
from google import genai
from google.genai import types
import os

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

grounding_tool = types.Tool(google_search=types.GoogleSearch())

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Wat is de huidige Bitcoin-koers en wat zijn de laatste ontwikkelingen?",
    config=types.GenerateContentConfig(tools=[grounding_tool]),
)

print(response.text)
```

Het model beslist zelf of een zoekopdracht het antwoord verbetert. Voor feitenvragen over recente gebeurtenissen zoekt het bijna altijd; voor uitleg over stabiele concepten vaak niet.

## Grounding metadata verwerken

De `grounding_metadata` bevat welke bronnen het model gebruikte. In de Python-SDK lees je deze velden in snake_case uit.

```python
def format_response_with_sources(response) -> str:
    text = response.text
    output = [text, "", "Bronnen:"]

    candidate = response.candidates[0]
    meta = candidate.grounding_metadata

    if meta and meta.grounding_chunks:
        for i, chunk in enumerate(meta.grounding_chunks, 1):
            if chunk.web:
                output.append(f"{i}. [{chunk.web.title}]({chunk.web.uri})")

    return "
".join(output)


response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Wat zijn de nieuwste AI-modellen van Google?",
    config=types.GenerateContentConfig(
        tools=[types.Tool(google_search=types.GoogleSearch())]
    ),
)

print(format_response_with_sources(response))
```

Belangrijke velden in `grounding_metadata`:

- `web_search_queries`: de zoekopdrachten die het model uitvoerde.
- `grounding_chunks`: de webbronnen met `web.title` en `web.uri`.
- `grounding_supports`: koppelt tekstsegmenten van het antwoord aan de bron-chunks via indexen, zo bouw je precieze inline-citaties.
- `search_entry_point`: kant-en-klare HTML en CSS voor de verplichte Google-zoeksuggesties.

:::warn title="Zoeksuggesties tonen is verplicht"
De servicevoorwaarden voor Grounding with Google Search verplichten je om de `search_entry_point` (de Google Search Suggestions-chips) ongewijzigd te tonen zodra je een gegrond antwoord weergeeft aan eindgebruikers. Het veld `search_entry_point.rendered_content` levert de conforme HTML en CSS. Sla je deze stap over, dan voldoe je niet aan de voorwaarden.
:::

## Inline-citaties bouwen

Wil je per zin de juiste bron tonen, gebruik dan `grounding_supports`. Elk support-object verwijst met `grounding_chunk_indices` naar de bronnen in `grounding_chunks` en met `segment` naar het tekstdeel.

```python
def add_inline_citations(response) -> str:
    candidate = response.candidates[0]
    meta = candidate.grounding_metadata
    text = response.text

    if not meta or not meta.grounding_supports:
        return text

    supports = sorted(
        meta.grounding_supports,
        key=lambda s: s.segment.end_index,
        reverse=True,
    )

    for support in supports:
        end = support.segment.end_index
        refs = "".join(
            f"[{idx + 1}]" for idx in support.grounding_chunk_indices
        )
        text = text[:end] + refs + text[end:]

    return text
```

## Grounding via de REST API

```bash
curl -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Wat is het weer in Amsterdam vandaag?"}]}
    ],
    "tools": [
      {"google_search": {}}
    ]
  }'
```

## Grounding combineren met een system instruction

```python
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Geef een analyse van de huidige stand van de AI-industrie.",
    config=types.GenerateContentConfig(
        system_instruction=(
            "Je bent een nieuwsanalist. Gebruik altijd actuele data. "
            "Geef bij elk feit de bron aan met [Bron N]. "
            "Onderscheid duidelijk tussen feiten en interpretaties."
        ),
        tools=[types.Tool(google_search=types.GoogleSearch())],
    ),
)

print(response.text)
```

## Grounding voor factcheck-toepassingen

```python
import json

def factcheck_claim(claim: str) -> dict:
    response = client.models.generate_content(
        model="gemini-2.5-flash",
        contents=(
            "Controleer de juistheid van deze bewering via actuele bronnen:
"
            f"\"{claim}\"

"
            "Geef JSON met keys: verdict, onderbouwing, nuances.
"
            "verdict is een van: WAAR, ONWAAR, GEDEELTELIJK_WAAR, ONVERIFIEERBAAR."
        ),
        config=types.GenerateContentConfig(
            tools=[types.Tool(google_search=types.GoogleSearch())],
            response_mime_type="application/json",
        ),
    )

    try:
        result = json.loads(response.text)
    except json.JSONDecodeError:
        result = {"verdict": "ONVERIFIEERBAAR", "onderbouwing": response.text}

    meta = response.candidates[0].grounding_metadata
    if meta and meta.grounding_chunks:
        result["bronnen"] = [
            chunk.web.uri for chunk in meta.grounding_chunks if chunk.web
        ]

    return result
```

:::tip title="Combineer JSON-output met grounding"
Met `response_mime_type="application/json"` dwing je geldige JSON af terwijl grounding actief blijft. Zo krijg je een gestructureerd resultaat en de bronlijst in een. Houd je prompt strak: vraag expliciet om de keys die je verwacht.
:::

## Beschikbaarheid en kosten

De prijs verschilt per modelgeneratie. Controleer altijd de actuele [Gemini API-prijzen](https://ai.google.dev/gemini-api/docs/pricing), want Google past tiers en bedragen regelmatig aan.

| Aspect | Gemini 2.5-familie | Gemini 3-familie |
|---|---|---|
| Tool | `google_search` | `google_search` |
| Gratis quotum | beperkt aantal requests per dag op de gratis tier | circa 5.000 gegronde prompts per maand, gedeeld over de Gemini 3-modellen |
| Betaald tarief | ongeveer $35 per 1.000 gegronde prompts | ongeveer $14 per 1.000 gegronde prompts |

Let op: een enkele API-call kan meerdere zoekopdrachten naar Google Search veroorzaken. De facturering volgt de prompts of queries zoals beschreven in de prijsdocumentatie, dus monitor je verbruik bij hoog volume.

:::faq
### Welke tool gebruik ik: google_search of google_search_retrieval?
Voor alle huidige modellen (Gemini 2.5 en de Gemini 3-familie) gebruik je `google_search`. De tool `google_search_retrieval` met `dynamic_retrieval_config` hoort bij verouderde modellen zoals Gemini 1.5 en wordt voor nieuwe projecten afgeraden.

### Zoekt Gemini altijd als grounding ingeschakeld is?
Nee. Het model besluit zelf of een zoekopdracht het antwoord verbetert. Voor feitenvragen over recente gebeurtenissen zoekt het bijna altijd; voor uitleg over stabiele concepten soms niet. Je betaalt alleen wanneer er daadwerkelijk gezocht wordt.

### Moet ik de Google-zoeksuggesties verplicht tonen?
Ja. De servicevoorwaarden vereisen dat je de `search_entry_point` met de zoeksuggesties ongewijzigd toont bij elk gegrond antwoord dat je aan eindgebruikers laat zien. Het veld levert daarvoor kant-en-klare HTML en CSS.

### Kan ik grounding combineren met function calling?
Ja, je kunt meerdere tools tegelijk meesturen. Het model beslist per beurt welke tool het gebruikt. Dat is handig wanneer je zowel real-time webinformatie als eigen bedrijfsdata wilt raadplegen.

### Zijn de bronnen altijd betrouwbaar?
Grounding gebruikt Google Search-resultaten, die niet altijd van hoge kwaliteit zijn. Behandel gegronde antwoorden als beter onderbouwd dan niet-gegronde, maar niet als feitelijk zeker. Valideer kritieke informatie altijd zelf via de meegeleverde bronlinks.

### Werkt grounding ook voor niet-Engelse queries?
Ja. Google Search werkt voor alle grote talen. Nederlandse queries leveren Nederlandse en internationale resultaten op.
:::