---
name: ck-gkg
description: >
  Queries and explores Google Knowledge Graph for entity information and relationships.
  Activate when user says 'look up entity', 'knowledge graph search', 'get entity details',
  'find information about a person or organization', or 'Google Knowledge Graph'.
  Accepts entity names, types, and relationship queries.
---

## Overview
Interfaces with the Google Knowledge Graph Search API to retrieve structured entity data including descriptions, types, images, and related entities for people, places, organizations, and concepts.

## When to Use
- Retrieving structured factual data about a named entity (person, org, place, concept)
- Enriching application data with authoritative entity metadata
- Verifying entity existence and canonical identifiers (MID)
- Building entity-linked features (auto-complete, entity cards, disambiguation)
- Cross-referencing entities across data sources using Knowledge Graph IDs

## Don't Use When
- Task needs real-time news or current events (Knowledge Graph has limited freshness)
- Searching for web pages rather than entities (use a web search API)
- Querying proprietary or internal data — KG only covers public knowledge
- Deep relationship traversal across many hops (use a graph database instead)

## Steps / Instructions

### 1. Set Up API Access

Required: Google Cloud project with Knowledge Graph Search API enabled.

```bash
# Environment variable (never hardcode)
export GOOGLE_API_KEY="your-key-here"
```

Enable API in Google Cloud Console:
```
APIs & Services → Library → Knowledge Graph Search API → Enable
```

### 2. Basic Entity Search

```python
import requests
import os

def search_knowledge_graph(query: str, types: list[str] | None = None, limit: int = 5):
    url = "https://kgsearch.googleapis.com/v1/entities:search"
    params = {
        "query": query,
        "key": os.environ["GOOGLE_API_KEY"],
        "limit": limit,
        "indent": True,
    }
    if types:
        params["types"] = types  # e.g., ["Person", "Organization"]

    response = requests.get(url, params=params)
    response.raise_for_status()
    return response.json()

# Usage
results = search_knowledge_graph("Python programming language", types=["SoftwareApplication"])
```

### 3. Parse the Response

```python
def extract_entities(kg_response: dict) -> list[dict]:
    entities = []
    for item in kg_response.get("itemListElement", []):
        result = item.get("result", {})
        entities.append({
            "name": result.get("name"),
            "description": result.get("description"),
            "detailed_description": result.get("detailedDescription", {}).get("articleBody"),
            "types": result.get("@type", []),
            "mid": result.get("@id"),           # Google MID: /m/05z1_
            "url": result.get("url"),
            "image": result.get("image", {}).get("url"),
            "score": item.get("resultScore"),
        })
    return entities
```

### 4. Entity Type Filters

Common KG entity types:
```
Person          — individuals, public figures
Organization    — companies, nonprofits, governments
Place           — cities, countries, landmarks
Event           — historical or recurring events
CreativeWork    — books, films, music, software
Thing           — generic fallback type
```

### 5. Handle Multi-Entity Disambiguation

```python
def disambiguate_entity(name: str, context_hint: str) -> dict | None:
    results = search_knowledge_graph(name, limit=10)
    entities = extract_entities(results)

    # Score by context relevance
    for entity in entities:
        desc = (entity.get("description") or "").lower()
        if context_hint.lower() in desc:
            return entity

    # Fall back to highest-scored result
    return entities[0] if entities else None
```

### 6. Rate Limits and Caching

- Free tier: 100,000 requests/day
- Cache responses for repeated entity lookups
- Use MID as cache key for stable entity references

```python
from functools import lru_cache

@lru_cache(maxsize=500)
def cached_entity_lookup(query: str) -> str:
    results = search_knowledge_graph(query, limit=1)
    return str(results)
```

## Notes
- API key must be restricted to Knowledge Graph API in Google Cloud Console
- MID identifiers are stable — use them for entity cross-referencing
- Knowledge Graph data is Wikipedia/Wikidata-sourced; verify critical facts
- Response scores are relative within a single query, not absolute quality metrics