Node Endpoint - Knowledge Graph Exploration

Node Endpoint - Knowledge Graph Exploration

Purpose

The Node endpoint retrieves property relationships and values from the Data Commons knowledge graph. It returns information about directed edges (properties) connecting nodes, enabling discovery of connections within the graph structure.

Core Capabilities

The Node API performs three primary functions:

1. Retrieve property labels associated with nodes
2. Obtain values for specific properties across nodes
3. Discover all connected nodes linked through relationships

Available Methods

1. fetch()

Retrieve properties using relation expressions with arrow notation.

Key Parameters:

• node_dcids: Target node identifier(s)
• expression: Relation syntax using arrows (->, <-, <-*)
• all_pages: Enable pagination (default: True)
• next_token: Continue paginated results

Arrow Notation:

• ->: Outgoing property (from node to value)
• <-: Incoming property (from value to node)
• <-*: Multi-hop incoming traversal

Example Usage:

from datacommons_client import DataCommonsClient

client = DataCommonsClient()

# Get outgoing properties from California
response = client.node.fetch(
    node_dcids=["geoId/06"],
    expression="->name"
)

# Get incoming properties (what points to this node)
response = client.node.fetch(
    node_dcids=["geoId/06"],
    expression="<-containedInPlace"
)

2. fetch_property_labels()

Get property labels without retrieving values—useful for discovering what properties exist.

Parameters:

• node_dcids: Node identifier(s)
• out: Boolean—True for outgoing properties, False for incoming

Example Usage:

# Get all outgoing property labels for California
labels = client.node.fetch_property_labels(
    node_dcids=["geoId/06"],
    out=True
)

# Get all incoming property labels
labels = client.node.fetch_property_labels(
    node_dcids=["geoId/06"],
    out=False
)

3. fetch_property_values()

Obtain specific property values with optional filters.

Parameters:

• node_dcids: Node identifier(s)
• property: Property name to query
• out: Direction (True for outgoing, False for incoming)
• limit: Maximum number of values to return

Example Usage:

# Get name property for California
values = client.node.fetch_property_values(
    node_dcids=["geoId/06"],
    property="name",
    out=True
)

4. fetch_all_classes()

List all entity types (Class nodes) in the Data Commons graph.

Example Usage:

classes = client.node.fetch_all_classes()

5. fetch_entity_names()

Look up entity names by DCID in selected languages.

Parameters:

• node_dcids: Entity identifier(s)
• language: Language code (default: "en")

Example Usage:

names = client.node.fetch_entity_names(
    node_dcids=["geoId/06", "country/USA"],
    language="en"
)
# Returns: {"geoId/06": "California", "country/USA": "United States"}

6. Place Hierarchy Methods

These methods navigate geographic relationships:

fetch_place_children()

Get direct child places.

Example Usage:

# Get all states in USA
children = client.node.fetch_place_children(
    node_dcids=["country/USA"]
)

fetch_place_descendants()

Retrieve full child hierarchies (recursive).

Example Usage:

# Get all descendants of California (counties, cities, etc.)
descendants = client.node.fetch_place_descendants(
    node_dcids=["geoId/06"]
)

fetch_place_parents()

Get direct parent places.

Example Usage:

# Get parent of San Francisco
parents = client.node.fetch_place_parents(
    node_dcids=["geoId/0667000"]
)

fetch_place_ancestors()

Retrieve complete parent lineages.

Example Usage:

# Get all ancestors of San Francisco (CA, USA, etc.)
ancestors = client.node.fetch_place_ancestors(
    node_dcids=["geoId/0667000"]
)

7. fetch_statvar_constraints()

Access constraint properties for statistical variables—useful for understanding variable definitions and constraints.

Example Usage:

constraints = client.node.fetch_statvar_constraints(
    node_dcids=["Count_Person"]
)

Response Format

Methods return either:

• NodeResponse objects with .to_dict(), .to_json(), and .nextToken properties
• Dictionaries for entity names and place hierarchy methods

Pagination

For large responses:

1. Set all_pages=False to receive data in chunks
2. Response includes a nextToken value
3. Re-query using that token to fetch subsequent pages

Example:

# First page
response = client.node.fetch(
    node_dcids=["country/USA"],
    expression="<-containedInPlace",
    all_pages=False
)

# Get next page if available
if response.nextToken:
    next_response = client.node.fetch(
        node_dcids=["country/USA"],
        expression="<-containedInPlace",
        next_token=response.nextToken
    )

Common Use Cases

Use Case 1: Explore Available Properties

# Discover what properties an entity has
labels = client.node.fetch_property_labels(
    node_dcids=["geoId/06"],
    out=True
)
print(labels)  # Shows all outgoing properties like 'name', 'latitude', etc.

Use Case 2: Navigate Geographic Hierarchies

# Get all counties in California
counties = client.node.fetch_place_children(
    node_dcids=["geoId/06"]
)

# Filter for specific type if needed
county_dcids = [child for child in counties["geoId/06"]
                if "County" in child]

Use Case 3: Build Entity Relationships

# Find all entities that reference a specific node
references = client.node.fetch(
    node_dcids=["geoId/06"],
    expression="<-location"
)

Important Notes

• Use fetch_property_labels() first to discover available properties
• The Node API cannot resolve complex relation expressions—use simpler expressions or break into multiple queries
• For linked entity properties with arc relationships, combine Node API queries with Observation API
• Place hierarchy methods return dictionaries, not NodeResponse objects