Google Knowledge Graph Search API

This quickstart introduces you to the Google Knowledge Graph Search API. In this quickstart, use the API to search or look up entities in Google Knowledge Graph.

If you're planning a new project, build your application with Cloud Knowledge Graph Advanced edition to take advantage of new features and service improvements. The Basic edition remains available, but doesn't support new features, high QPS, or additional security and compliance standards.

Search Cloud Knowledge Graph entities

The following samples show how to search an entity against the knowledge graph.

Advanced

REST

To search the knowledge graph for the Advanced edition, call the projects.locations.cloudKnowledgeGraphEntities.search method.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: Your Google Cloud project ID.
  • LOCATION: Knowledge Graph location.
    • Options: global - Global Endpoint
  • SEARCH_QUERY: The literal query string for search.
  • LANGUAGES: (Optional) The list of language codes (defined in ISO 693) to run the query with. The default value is en if not specified.
  • TYPES: (Optional) Restricts returned entities with these types, as defined by `https://schema.org`. If multiple types are specified, returned entities will contain one or more of these types. The default value is empty, which will return entities with no type restrictions. Refer to the Schema.org full hierarchy for supported types.
  • LIMIT: (Optional) Limits the number of entities to be returned. The default is 20.

HTTP method and URL:

GET https://enterpriseknowledgegraph.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cloudKnowledgeGraphEntities:Search?query=SEARCH_QUERY&limit=LIMIT

To send your request, choose one of these options:

curl

Execute the following command:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://enterpriseknowledgegraph.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cloudKnowledgeGraphEntities:Search?query=SEARCH_QUERY&limit=LIMIT"

PowerShell

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://enterpriseknowledgegraph.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cloudKnowledgeGraphEntities:Search?query=SEARCH_QUERY&limit=LIMIT" | Select-Object -Expand Content

The response contains a list of entities, presented in JSON-LD format and compatible with schema.org schemas with limited external extensions.

Refer to Entity Response Structure for more information about the response structure.

The following JSON-LD example shows how the response body is structured:

{
  "@context": {
    "@vocab": "http://schema.org/"
  },
  "@type": "ItemList",
  "itemListElement": [
    {
      "result": {
        "@id": "c-07xuup16g",
        "name": "Stanford University",
        "description": "Private university in Stanford, California",
        "detailedDescription": {
          "articleBody": "Stanford University, officially Leland Stanford Junior University, is a private research university in Stanford, California. The campus occupies 8,180 acres, among the largest in the United States, and enrolls over 17,000 students. ",
          "url": "https://en.wikipedia.org/wiki/Stanford_University",
          "license": "https://en.wikipedia.org/wiki/Wikipedia:Text_of_Creative_Commons_Attribution-ShareAlike_3.0_Unported_License"
        },
        "url": "http://www.stanford.edu/",
        "image": {
          "contentUrl": "https://encrypted-tbn1.gstatic.com/images?q=tbn:ANd9GcTfPPf-ker0y_892m1wu8-U89furQgQ67foDFncY3r9sREpeWxV",
          "url": "https://es.wikipedia.org/wiki/Archivo:Logo_of_Stanford_University.png"
        },
        "identifier": [
          {
            "@type": "PropertyValue",
            "propertyID": "googleKgMID",
            "value": "/m/06pwq"
          },
          {
            "@type": "PropertyValue",
            "propertyID": "googlePlaceID",
            "value": "ChIJneqLZyq7j4ARf2j8RBrwzSk"
          },
          {
            "@type": "PropertyValue",
            "propertyID": "wikidataQID",
            "value": "Q41506"
          }
        ],
        "@type": [
          "Place",
          "Organization",
          "MovieTheater",
          "Corporation",
          "EducationalOrganization",
          "Thing",
          "CollegeOrUniversity"
        ]
      }
    }
  ]
}

Python

For more information, see the Enterprise Knowledge Graph Python API reference documentation.

To authenticate to Enterprise Knowledge Graph, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.


from __future__ import annotations

from collections.abc import Sequence

from google.cloud import enterpriseknowledgegraph as ekg

# TODO(developer): Uncomment these variables before running the sample.
# project_id = 'YOUR_PROJECT_ID'
# location = 'YOUR_GRAPH_LOCATION'      # Values: 'global'
# search_query = 'YOUR_SEARCH_QUERY'
# languages = ['en']                    # Optional: List of ISO 639-1 Codes
# types = ['']                          # Optional: List of schema.org types to return
# limit = 20                            # Optional: Number of entities to return


def search_sample(
    project_id: str,
    location: str,
    search_query: str,
    languages: Sequence[str] = None,
    types: Sequence[str] = None,
    limit: int = 20,
):
    # Create a client
    client = ekg.EnterpriseKnowledgeGraphServiceClient()

    # The full resource name of the location
    # e.g. projects/{project_id}/locations/{location}
    parent = client.common_location_path(project=project_id, location=location)

    # Initialize request argument(s)
    request = ekg.SearchRequest(
        parent=parent,
        query=search_query,
        languages=languages,
        types=types,
        limit=limit,
    )

    # Make the request
    response = client.search(request=request)

    print(f"Search Query: {search_query}\n")

    # Extract and print date from response
    for item in response.item_list_element:
        result = item.get("result")

        print(f"Name: {result.get('name')}")
        print(f"- Description: {result.get('description')}")
        print(f"- Types: {result.get('@type')}\n")

        detailed_description = result.get("detailedDescription")

        if detailed_description:
            print("- Detailed Description:")
            print(f"\t- Article Body: {detailed_description.get('articleBody')}")
            print(f"\t- URL: {detailed_description.get('url')}")
            print(f"\t- License: {detailed_description.get('license')}\n")

        print(f"- Cloud MID: {result.get('@id')}")
        for identifier in result.get("identifier"):
            print(f"\t- {identifier.get('name')}: {identifier.get('value')}")

        print("\n")

Basic

REST

To search the knowledge graph for the Basic edition, call the projects.locations.publicKnowledgeGraphEntities.search method.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: Your Google Cloud project ID.
  • LOCATION: Knowledge Graph location.
    • Options: global - Global Endpoint
  • SEARCH_QUERY: The literal query string for search.
  • LANGUAGES: (Optional) The list of language codes (defined in ISO 693) to run the query with. The default value is en if not specified.
  • TYPES: (Optional) Restricts returned entities with these types, as defined by `https://schema.org`. If multiple types are specified, returned entities will contain one or more of these types. The default value is empty, which will return entities with no type restrictions. Refer to the Schema.org full hierarchy for supported types.
  • LIMIT: (Optional) Limits the number of entities to be returned. The default is 20.

HTTP method and URL:

GET https://enterpriseknowledgegraph.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publicKnowledgeGraphEntities:Search?query=SEARCH_QUERY&limit=LIMIT

To send your request, choose one of these options:

curl

Execute the following command:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://enterpriseknowledgegraph.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publicKnowledgeGraphEntities:Search?query=SEARCH_QUERY&limit=LIMIT"

PowerShell

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://enterpriseknowledgegraph.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publicKnowledgeGraphEntities:Search?query=SEARCH_QUERY&limit=LIMIT" | Select-Object -Expand Content

The response contains a list of entities, presented in JSON-LD format and compatible with schema.org schemas with limited external extensions.

Refer to Entity Response Structure for more information about the response structure.

The following JSON-LD example shows how the response body is structured:

{
  "@context": {
    "@vocab": "http://schema.org/"
  },
  "@type": "ItemList",
  "itemListElement": [
    {
      "result": {
        "@id": "c-07xuup16g",
        "name": "Stanford University",
        "description": "Private university in Stanford, California",
        "detailedDescription": {
          "license": "https://en.wikipedia.org/wiki/Wikipedia:Text_of_Creative_Commons_Attribution-ShareAlike_3.0_Unported_License",
          "url": "https://en.wikipedia.org/wiki/Stanford_University",
          "articleBody": "Stanford University, officially Leland Stanford Junior University, is a private research university in Stanford, California. The campus occupies 8,180 acres, among the largest in the United States, and enrolls over 17,000 students. "
        },
        "url": "http://www.stanford.edu/",
        "identifier": [
          {
            "@type": "PropertyValue",
            "propertyID": "googleKgMID",
            "value": "/m/06pwq"
          }
        ],
        "image": {
          "contentUrl": "https://encrypted-tbn1.gstatic.com/images?q=tbn:ANd9GcTfPPf-ker0y_892m1wu8-U89furQgQ67foDFncY3r9sREpeWxV",
          "url": "https://es.wikipedia.org/wiki/Archivo:Logo_of_Stanford_University.png"
        },
        "@type": [
          "EducationalOrganization",
          "CollegeOrUniversity",
          "Thing",
          "Place",
          "Corporation",
          "MovieTheater",
          "Organization"
        ]
      }
    }
  ]
}

Python

For more information, see the Enterprise Knowledge Graph Python API reference documentation.

To authenticate to Enterprise Knowledge Graph, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.


from __future__ import annotations

from collections.abc import Sequence

from google.cloud import enterpriseknowledgegraph as ekg

# TODO(developer): Uncomment these variables before running the sample.
# project_id = 'YOUR_PROJECT_ID'
# location = 'YOUR_GRAPH_LOCATION'      # Values: 'global'
# search_query = 'YOUR_SEARCH_QUERY'
# languages = ['en']                    # Optional: List of ISO 639-1 Codes
# types = ['']                          # Optional: List of schema.org types to return
# limit = 20                            # Optional: Number of entities to return


def search_public_kg_sample(
    project_id: str,
    location: str,
    search_query: str,
    languages: Sequence[str] = None,
    types: Sequence[str] = None,
    limit: int = 20,
):
    # Create a client
    client = ekg.EnterpriseKnowledgeGraphServiceClient()

    # The full resource name of the location
    # e.g. projects/{project_id}/locations/{location}
    parent = client.common_location_path(project=project_id, location=location)

    # Initialize request argument(s)
    request = ekg.SearchPublicKgRequest(
        parent=parent,
        query=search_query,
        languages=languages,
        types=types,
        limit=limit,
    )

    # Make the request
    response = client.search_public_kg(request=request)

    print(f"Search Query: {search_query}\n")

    # Extract and print date from response
    for item in response.item_list_element:
        result = item.get("result")

        print(f"Name: {result.get('name')}")
        print(f"- Description: {result.get('description')}")
        print(f"- Types: {result.get('@type')}\n")

        detailed_description = result.get("detailedDescription")

        if detailed_description:
            print("- Detailed Description:")
            print(f"\t- Article Body: {detailed_description.get('articleBody')}")
            print(f"\t- URL: {detailed_description.get('url')}")
            print(f"\t- License: {detailed_description.get('license')}\n")

        print(f"- Cloud MID: {result.get('@id')}")
        for identifier in result.get("identifier"):
            print(f"\t- {identifier.get('name')}: {identifier.get('value')}")

        print("\n")

Look up entities from Cloud Knowledge Graph MID

Google Knowledge Graph Search API introduces the new machine ID (MID) format for easier product and application integration. The lookup API works for both the new Cloud Knowledge Graph MID (starts with c-), as well as the Google Knowledge Graph MID (starts with /m).

Advanced

REST

To look up an entity by MID for the Advanced edition, call the projects.locations.cloudKnowledgeGraphEntities.lookup method.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: Your Google Cloud project ID.
  • LOCATION: Knowledge Graph location.
    • Options: global - Global Endpoint
  • LOOKUP_IDS: The list of entity IDs to be used for lookup.
    • Example: /m/0dl567
  • LANGUAGES: (Optional) The list of language codes (defined in ISO 693) to run the query with. The default value is en if not specified.

HTTP method and URL:

GET https://enterpriseknowledgegraph.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cloudKnowledgeGraphEntities:Lookup?ids=LOOKUP_IDS

To send your request, choose one of these options:

curl

Execute the following command:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://enterpriseknowledgegraph.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cloudKnowledgeGraphEntities:Lookup?ids=LOOKUP_IDS"

PowerShell

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://enterpriseknowledgegraph.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cloudKnowledgeGraphEntities:Lookup?ids=LOOKUP_IDS" | Select-Object -Expand Content

The response contains a list of entities, presented in JSON-LD format and compatible with schema.org schemas with limited external extensions.

Refer to Entity Response Structure for more information about the response structure.

The following JSON-LD example shows how the response body is structured:

{
  "@context": {
    "@vocab": "http://schema.org/"
  },
  "@type": "ItemList",
  "itemListElement": [
    {
      "result": {
        "description": "American singer-songwriter",
        "@type": [
          "Person",
          "Thing"
        ],
        "name": "Taylor Swift",
        "@id": "c-0260160kc",
        "url": "http://www.taylorswift.com/",
        "identifier": [
          {
            "@type": "PropertyValue",
            "propertyID": "googleKgMID",
            "value": "/m/0dl567"
          },
          {
            "@type": "PropertyValue",
            "propertyID": "wikidataQID",
            "value": "Q26876"
          }
        ],
        "detailedDescription": {
          "articleBody": "Taylor Alison Swift is an American singer-songwriter. Her discography spans multiple genres and her narrative songwriting—often inspired by her personal life—has received critical praise and widespread media coverage. ",
          "license": "https://en.wikipedia.org/wiki/Wikipedia:Text_of_Creative_Commons_Attribution-ShareAlike_3.0_Unported_License",
          "url": "https://en.wikipedia.org/wiki/Taylor_Swift"
        },
        "image": {
          "contentUrl": "https://encrypted-tbn1.gstatic.com/images?q=tbn:ANd9GcSnsjOArwgD-bhyRslj_Qa7Z2tIPLRFU3VnEuLr1ybcyned49Pt",
          "url": "https://pt.wikipedia.org/wiki/Ficheiro:191125_Taylor_Swift_at_the_2019_American_Music_Awards_(cropped).png"
        }
      }
    }
  ]
}
To look up multiple entities from Cloud Knowledge Graph, provide multiple ids. The URL should look like this.
https://enterpriseknowledgegraph.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cloudKnowledgeGraphEntities:Lookup?ids=LOOKUP_IDS&ids=LOOKUP_IDS

Python

For more information, see the Enterprise Knowledge Graph Python API reference documentation.

To authenticate to Enterprise Knowledge Graph, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.


from __future__ import annotations

from collections.abc import Sequence

from google.cloud import enterpriseknowledgegraph as ekg

# TODO(developer): Uncomment these variables before running the sample.
# project_id = 'YOUR_PROJECT_ID'
# location = 'YOUR_GRAPH_LOCATION'      # Values: 'global'
# ids = ['YOUR_LOOKUP_MID']             # https://cloud.google.com/enterprise-knowledge-graph/docs/mid
# languages = ['en']                    # Optional: List of ISO 639-1 Codes


def lookup_sample(
    project_id: str,
    location: str,
    ids: Sequence[str],
    languages: Sequence[str] = None,
):
    # Create a client
    client = ekg.EnterpriseKnowledgeGraphServiceClient()

    # The full resource name of the location
    # e.g. projects/{project_id}/locations/{location}
    parent = client.common_location_path(project=project_id, location=location)

    # Initialize request argument(s)
    request = ekg.LookupRequest(
        parent=parent,
        ids=ids,
        languages=languages,
    )

    # Make the request
    response = client.lookup(request=request)

    print(f"Lookup IDs: {ids}\n")

    print(response)

    # Extract and print date from response
    for item in response.item_list_element:
        result = item.get("result")

        print(f"Name: {result.get('name')}")
        print(f"- Description: {result.get('description')}")
        print(f"- Types: {result.get('@type')}\n")

        detailed_description = result.get("detailedDescription")

        if detailed_description:
            print("- Detailed Description:")
            print(f"\t- Article Body: {detailed_description.get('articleBody')}")
            print(f"\t- URL: {detailed_description.get('url')}")
            print(f"\t- License: {detailed_description.get('license')}\n")

        print(f"- Cloud MID: {result.get('@id')}")
        for identifier in result.get("identifier"):
            print(f"\t- {identifier.get('name')}: {identifier.get('value')}")

        print("\n")

Basic

REST

To look up an entity by MID for the Basic edition, call the projects.locations.publicKnowledgeGraphEntities.lookup method.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: Your Google Cloud project ID.
  • LOCATION: Knowledge Graph location.
    • Options: global - Global Endpoint
  • LOOKUP_IDS: The list of entity IDs to be used for lookup.
    • Example: /m/0dl567
  • LANGUAGES: (Optional) The list of language codes (defined in ISO 693) to run the query with. The default value is en if not specified.

HTTP method and URL:

GET https://enterpriseknowledgegraph.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publicKnowledgeGraphEntities:Lookup?ids=LOOKUP_IDS

To send your request, choose one of these options:

curl

Execute the following command:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://enterpriseknowledgegraph.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publicKnowledgeGraphEntities:Lookup?ids=LOOKUP_IDS"

PowerShell

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://enterpriseknowledgegraph.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publicKnowledgeGraphEntities:Lookup?ids=LOOKUP_IDS" | Select-Object -Expand Content

The response contains a list of entities, presented in JSON-LD format and compatible with schema.org schemas with limited external extensions.

Refer to Entity Response Structure for more information about the response structure.

The following JSON-LD example shows how the response body is structured:

{
  "@context": {
    "@vocab": "http://schema.org/"
  },
  "@type": "ItemList",
  "itemListElement": [
    {
      "result": {
        "description": "American singer-songwriter",
        "@type": [
          "Person",
          "Thing"
        ],
        "name": "Taylor Swift",
        "@id": "c-0260160kc",
        "url": "http://www.taylorswift.com/",
        "identifier": [
          {
            "@type": "PropertyValue",
            "propertyID": "googleKgMID",
            "value": "/m/0dl567"
          }
        ],
        "detailedDescription": {
          "articleBody": "Taylor Alison Swift is an American singer-songwriter. Her discography spans multiple genres and her narrative songwriting—often inspired by her personal life—has received critical praise and widespread media coverage. ",
          "license": "https://en.wikipedia.org/wiki/Wikipedia:Text_of_Creative_Commons_Attribution-ShareAlike_3.0_Unported_License",
          "url": "https://en.wikipedia.org/wiki/Taylor_Swift"
        },
        "image": {
          "contentUrl": "https://encrypted-tbn1.gstatic.com/images?q=tbn:ANd9GcSnsjOArwgD-bhyRslj_Qa7Z2tIPLRFU3VnEuLr1ybcyned49Pt",
          "url": "https://pt.wikipedia.org/wiki/Ficheiro:191125_Taylor_Swift_at_the_2019_American_Music_Awards_(cropped).png"
        }
      }
    }
  ]
}
To look up multiple entities from Cloud Knowledge Graph, provide multiple ids. The URL should look like this.
https://enterpriseknowledgegraph.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publicKnowledgeGraphEntities:Lookup?ids=LOOKUP_IDS&ids=LOOKUP_IDS

Python

For more information, see the Enterprise Knowledge Graph Python API reference documentation.

To authenticate to Enterprise Knowledge Graph, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.


from __future__ import annotations

from collections.abc import Sequence

from google.cloud import enterpriseknowledgegraph as ekg

# TODO(developer): Uncomment these variables before running the sample.
# project_id = 'YOUR_PROJECT_ID'
# location = 'YOUR_GRAPH_LOCATION'      # Values: 'global'
# ids = ['YOUR_LOOKUP_MID']             # https://cloud.google.com/enterprise-knowledge-graph/docs/mid
# languages = ['en']                    # Optional: List of ISO 639-1 Codes


def lookup_public_kg_sample(
    project_id: str,
    location: str,
    ids: Sequence[str],
    languages: Sequence[str] = None,
):
    # Create a client
    client = ekg.EnterpriseKnowledgeGraphServiceClient()

    # The full resource name of the location
    # e.g. projects/{project_id}/locations/{location}
    parent = client.common_location_path(project=project_id, location=location)

    # Initialize request argument(s)
    request = ekg.LookupPublicKgRequest(
        parent=parent,
        ids=ids,
        languages=languages,
    )

    # Make the request
    response = client.lookup_public_kg(request=request)

    print(f"Lookup IDs: {ids}\n")

    print(response)

    # Extract and print date from response
    for item in response.item_list_element:
        result = item.get("result")

        print(f"Name: {result.get('name')}")
        print(f"- Description: {result.get('description')}")
        print(f"- Types: {result.get('@type')}\n")

        detailed_description = result.get("detailedDescription")

        if detailed_description:
            print("- Detailed Description:")
            print(f"\t- Article Body: {detailed_description.get('articleBody')}")
            print(f"\t- URL: {detailed_description.get('url')}")
            print(f"\t- License: {detailed_description.get('license')}\n")

        print(f"- Cloud MID: {result.get('@id')}")
        for identifier in result.get("identifier"):
            print(f"\t- {identifier.get('name')}: {identifier.get('value')}")

        print("\n")

Entity Structure

Field name Type Description
@id string The canonical URI for the entity.
name string The name of the entity.
@type array The list of supported schema.org types that match the entity.
description string A short description of the entity.
image URL An image to help identify the entity.
detailedDescription string A detailed description of the entity.
url URL The official website URL of the entity, if available.
identifier array A list of other linked ids. e.g. WikidataQID.

JSON-LD keywords

Refer to the JSON-LD specification for JSON-LD keywords such as:

Schema.org compatibility

For each of the Schema.org types (such as Person) and properties (such as name) there is a corresponding full URI, as in the following examples:

Class Name URI
type Person https://schema.org/Person
type Thing https://schema.org/Thing
property name https://schema.org/name
property description https://schema.org/description

Schema extensions

Types and properties used in this API are hosted at https://schema.googleapis.com as external extensions.

The documentation for each type and property is available at the corresponding URI.

Class Name URI
type EntitySearchResult https://schema.googleapis.com/EntitySearchResult
property detailedDescription https://schema.googleapis.com/detailedDescription

Knowledge Graph entities

The Knowledge Graph has millions of entries that describe real-world entities like people, places, and things. These entities form the nodes of the graph.

The following are some of the common types of entities found in the Cloud Knowledge Graph: