Entity SEO & Python

Google Knowledge Graph Search API com Python: Como Mapear o Entity ID (MID) e a Autoridade de Marca no Google

Cayo Galotti
18 de Setembro de 2026
11 min de leitura
Entity SEO & Python
Knowledge Graph API com Python
Cayo Galotti Especialista Google

O Google opera com base no paradigma de coisas, não de palavras soltas. Desde a introdução do Knowledge Graph em 2012 e o avanço dos sistemas neurais, a busca deixou de ser apenas a correspondência de cadeias de caracteres em documentos HTML. O motor de busca compreende conceitos, pessoas, corporações e marcas como entidades conectadas em uma rede semântica estruturada.

Com o surgimento de respostas geradas diretamente na página de resultados, como no caso do Google AI Overviews, o reconhecimento de entidade tornou-se um pré-requisito fundamental. Se o Google não compreende com precisão qual nó do grafo a sua empresa representa, ele terá dificuldade para correlacionar sua experiência com as intenções de busca dos usuários.

A forma mais direta de validar se os sistemas do Google já indexaram sua marca como uma entidade independente é consultar a Google Knowledge Graph Search API. Neste guia técnico, você verá como usar Python para extrair o identificador único da sua marca (o Machine ID ou MID), analisar a métrica de relevância resultScore e aplicar esse aprendizado no seu schema markup para reconciliação semântica.

A virada semântica do Google: de palavras-chave a nós no Knowledge Graph

Um grafo de conhecimento organiza informações no formato de triplas semânticas, compostas por sujeito, predicado e objeto. Por exemplo:

  • Sujeito: Google LLC
  • Predicado: fundador
  • Objeto: Larry Page

Cada sujeito e cada objeto nessa relação não é uma simples palavra. Trata-se de uma entidade singular, associada a uma série de atributos (endereço, data de fundação, setor econômico) e conexões com outras entidades.

Quando um usuário pesquisa por uma marca no Google, o buscador consulta seu índice semântico para verificar se existe um nó correspondente àquela consulta. A existência desse nó viabiliza a exibição de painéis de conhecimento (Knowledge Panels), alimenta caixas de resposta direta e ancora a síntese de respostas gerativas.

Complementando o trabalho de auditoria de Entity SEO com a Natural Language API, a Knowledge Graph Search API nos permite enxergar o lado oposto da moeda: não o texto que você escreve no seu site, mas o que o Google já gravou no seu repositório de entidades globais.

O que é o Entity ID (MID) e como ele funciona

Para evitar ambiguidades causadas por homônimos, o Google atribui a cada entidade um código de máquina imutável chamado Machine ID, comumente abreviado como MID.

Existem dois formatos principais de MIDs no Knowledge Graph:

  1. Prefixados por /m/: herdados do Freebase, a base de conhecimento aberta adquirida pelo Google em 2010 (por exemplo, /m/045c7b para Google).
  2. Prefixados por /g/: gerados internamente pelo Knowledge Vault do Google nos anos subsequentes à descontinuação do Freebase (por exemplo, /g/11b6w3y_2x).

Pense no MID como a chave primária da sua marca no banco de dados semântico do Google.

Se a sua empresa se chama “Ápice”, há centenas de empresas homônimas no mundo, além do sentido genérico da palavra. O MID /g/... único da sua organização impede que o algoritmo confunda sua empresa de software com uma clínica médica de mesmo nome ou com um termo astronômico.

Anatomia da Google Knowledge Graph Search API

A Google Knowledge Graph Search API expõe um endpoint REST público que permite buscar entidades registradas no grafo com base em consultas de texto.

O endpoint padrão da API é:

https://kgsearch.googleapis.com/v1/entities:search

Os principais parâmetros aceitos na requisição são:

  • query: o termo de busca (o nome da sua marca, concorrente ou tópico).
  • types: uma lista de tipos do vocabulário Schema.org para filtrar os nós (por exemplo, Organization, Corporation, LocalBusiness, Person).
  • limit: quantidade máxima de nós a retornar (padrão de 10, máximo de 500).
  • languages: código do idioma (como pt ou en).
  • key: a chave de autenticação do Google Cloud.

A resposta da API vem formatada como um objeto JSON-LD que segue as convenções do Schema.org. O nó raiz é do tipo ItemList, contendo uma lista de itemListElement. Cada item contém dois blocos cruciais:

  1. result: o nó da entidade com seu @id (o MID), name, tipos atribuídos (@type), description e detailedDescription com links para fontes primárias como Wikipedia.
  2. resultScore: um valor numérico de ponto flutuante que reflete a força de associação e a proeminência dessa entidade em relação à consulta enviada.

Configurando o acesso no Google Cloud Console

Para consumir a API, você precisará de uma chave de API criada em um projeto no Google Cloud Console:

  1. Acesse o Console do Google Cloud e crie um novo projeto ou selecione um existente.
  2. No menu lateral, acesse “APIs e Serviços” e depois “Biblioteca”.
  3. Digite “Knowledge Graph Search API” no campo de busca e clique em “Ativar”.
  4. Vá para a aba “Credenciais”, clique em “Criar Credenciais” e selecione “Chave de API”.
  5. Restrinja a chave para permitir chamadas exclusivamente para a “Knowledge Graph Search API” para garantir a segurança operacional.

Defina a chave no seu ambiente de execução:

export GOOGLE_KG_API_KEY="sua_chave_aqui"

Script Python: mapeamento automatizado de MIDs e resultScore

O script a seguir implementa a consulta ao endpoint, faz o tratamento dos dados e extrai os campos estruturais em um formato tabular limpo.

import os
from typing import Any, Dict, List, Optional
import pandas as pd
import requests

API_KEY = os.getenv("GOOGLE_KG_API_KEY")
ENDPOINT = "https://kgsearch.googleapis.com/v1/entities:search"

def query_knowledge_graph(
    query: str,
    api_key: str,
    types: Optional[List[str]] = None,
    limit: int = 5,
    languages: str = "pt"
) -> List[Dict[str, Any]]:
    """Consulta a Google Knowledge Graph Search API e retorna entidades estruturadas."""
    params = {
        "query": query,
        "key": api_key,
        "limit": limit,
        "languages": languages,
        "indent": True
    }
    if types:
        params["types"] = types

    response = requests.get(ENDPOINT, params=params, timeout=10)
    response.raise_for_status()
    payload = response.json()

    results = []
    for item in payload.get("itemListElement", []):
        entity = item.get("result", {})
        score = item.get("resultScore", 0.0)

        raw_id = entity.get("@id", "")
        # O ID retornado costuma vir como 'kg:/m/...' ou 'kg:/g/...'
        mid = raw_id.replace("kg:", "") if raw_id.startswith("kg:") else raw_id

        entity_types = entity.get("@type", [])
        if isinstance(entity_types, str):
            entity_types = [entity_types]

        detailed = entity.get("detailedDescription", {})

        results.append({
            "query": query,
            "mid": mid,
            "name": entity.get("name", ""),
            "types": ", ".join(entity_types),
            "result_score": round(score, 2),
            "description": entity.get("description", ""),
            "article_url": detailed.get("url", entity.get("url", ""))
        })

    return results

if __name__ == "__main__":
    if not API_KEY:
        raise ValueError("Defina a variavel GOOGLE_KG_API_KEY no ambiente.")

    # Exemplo: busca por uma entidade de marca
    marca = "Nubank"
    dados = query_knowledge_graph(query=marca, api_key=API_KEY, limit=3)

    df = pd.DataFrame(dados)
    print(df[["mid", "name", "types", "result_score", "description"]])

Ao executar o código com uma marca consolidada, a resposta revela o MID exato e a categorização que o Google mantém internamente.

Analisando e comparando autoridade de entidades em lote

Quando você gerencia uma carteira de marcas ou deseja avaliar o posicionamento da sua empresa contra os principais concorrentes do setor, a comparação em lote revela a hierarquia semântica atribuída pelo buscador.

def batch_entity_audit(brands: List[str], api_key: str) -> pd.DataFrame:
    """Executa a auditoria de presenca e score para uma lista de marcas."""
    records = []
    
    for brand in brands:
        data = query_knowledge_graph(query=brand, api_key=api_key, limit=1)
        if data:
            records.append(data[0])
        else:
            records.append({
                "query": brand,
                "mid": "Nao mapeado",
                "name": brand,
                "types": "N/A",
                "result_score": 0.0,
                "description": "Nenhum no identificado",
                "article_url": ""
            })
            
    df = pd.DataFrame(records)
    return df.sort_values(by="result_score", ascending=False).reset_index(drop=True)

# Exemplo de comparacao de ecossistema
concorrentes = ["Mercado Livre", "Magazine Luiza", "Shopee", "Sua Empresa Nova"]
tabela_comparativa = batch_entity_audit(concorrentes, API_KEY)
print(tabela_comparativa[["name", "mid", "result_score", "types"]])

Esse relatório permite checar se a sua marca já foi indexada com os tipos adequados (como Organization, Corporation ou Brand) e quantificar a distância do seu resultScore em relação aos players tradicionais da sua vertical.

Como interpretar o resultScore na prática de SEO

O resultScore retornado pela API não é uma nota de 0 a 100 fixa. Trata-se de um índice de confiança relacional não delimitado superiormente.

Fatores que afetam o resultScore:

  • Proeminência da entidade na web aberta (volume de citações consistentes em fontes autorizadas).
  • Ambiguidade da palavra pesquisada. Se a marca tem o nome idêntico a um substantivo comum, o score tende a ser diluído ou dividido entre diferentes nós.
  • Frequência de buscas pelo nome da marca como termo de navegação direta.
  • Conexões com outros nós de peso no grafo, como executivos notáveis, patentes, produtos e localização geográfica.

Um resultScore elevado indica que o Google tem alta certeza de que a consulta refere-se àquela organização específica. Isso reduz o risco de canibalização semântica e fortalece as chances de inclusão em caixas de resposta gerativa.

Reconciliação semântica: inserindo o MID no schema markup JSON-LD

Descobrir o seu MID tem utilidade prática imediata para a arquitetura técnica do seu site. Você pode utilizá-lo para fechar o ciclo de reconciliação de dados via Schema.org.

Muitas empresas utilizam apenas URLs de redes sociais no atributo sameAs. Embora isso seja válido, apontar para o próprio nó de entidade no Google consolida a correspondência inequívoca entre o seu domínio e o Knowledge Graph.

A URL oficial que referencia um MID no Google segue o padrão:

https://www.google.com/search?kgmid=/g/seu_codigo_aqui

Veja como estruturar o bloco de organização no seu layout, conforme detalhado no artigo sobre implementação de schema markup em JSON-LD:

{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Nome da Sua Empresa",
  "url": "https://suaempresa.com.br",
  "logo": "https://suaempresa.com.br/assets/logo.png",
  "sameAs": [
    "https://www.google.com/search?kgmid=/g/11b6w3y_2x",
    "https://www.wikidata.org/wiki/Q12345678",
    "https://www.linkedin.com/company/suaempresa",
    "https://twitter.com/suaempresa"
  ]
}

Ao declarar o seu kgmid no sameAs, você fornece uma instrução explícita ao rastreador do Google, conectando seu HTML diretamente à memória relacional do buscador.

Diagnóstico e resolução: quando a marca não possui MID no Google

Se o retorno da API para a sua marca for vazio ou retornar apenas nós não relacionados, significa que o Google ainda não isolou sua empresa como uma entidade autônoma.

Para acelerar a criação desse nó no Knowledge Graph, siga estas etapas práticas:

  1. Registre e verifique um Perfil da Empresa no Google (antigo Google Meu Negócio), garantindo que dados como Razão Social, Nome Fantasia, CNPJ, site oficial e categoria estejam perfeitamente alinhados.
  2. Crie uma página de entidade no Wikidata. O Wikidata é uma das fontes de dados mais consultadas pelos sistemas de extração de conhecimento do Google. Mantenha referências externas válidas na página (como matérias na imprensa e registros comerciais).
  3. Mantenha coerência estrita de NAP (Name, Address, Phone) em todas as bases públicas, incluindo Crunchbase, perfis setoriais, LinkedIn e diretórios de tecnologia.
  4. Conecte dados de entidades internas no seu site, assegurando que o rodapé e a página “Sobre Nós” utilizem os mesmos dados declarados no schema Organization.

Com essas bases consolidadas, o algoritmo de extração do Google constrói a tripla semântica necessária para formalizar o novo nó no grafo.

Monitoramento contínuo e impacto no Google AI Overviews

O reconhecimento no Knowledge Graph é determinante para o desempenho em buscas gerativas. Conforme abordado no guia de estratégias de Generative Engine Optimization (GEO) e no rastreamento de citações no Google AI Overviews, os modelos neurais que sintetizam respostas dependem de grounding em entidades conhecidas para evitar alucinações.

Marcas com nós validados e pontuações de relevância consistentes na Knowledge Graph Search API têm probabilidade superior de serem citadas como referências fidedignas nas respostas gerativas da SERP.

Integrando este script Python com rotinas de pipelines automatizados com Search Console API e BigQuery, você pode salvar o histórico de resultScore da sua empresa mês a mês. Isso permite correlacionar o ganho de autoridade semântica com campanhas de relações públicas, menções na mídia e crescimento de buscas pela marca.

Próximos passos para consolidar sua marca como entidade

O SEO moderno transcende o ajuste pontual de tags de título e a contagem de links externos. A mecânica de indexação atual opera sobre relações de confiança entre entidades computáveis.

Auditar seu MID via Python dá clareza sobre como os algoritmos do Google categorizam seu negócio hoje. Com esses dados em mãos, você pode implementar a marcação semântica correta, eliminar ambiguidades de nomenclatura e posicionar sua empresa como autoridade referenciada na busca tradicional e nas experiências com inteligência artificial.