datacommons-client

foryourhealth111-pixel/Vibe-SkillsResearchAudit passedSnapshot 7dd0ff4b8bde

Summary

Work with Data Commons, a platform providing programmatic access to public statistical data from global sources. Use this skill when working with demographic data, economic indicators, health statistics, environmental data, or any public datasets available through Data Commons. Applicable for querying population statistics, GDP figures, unemployment rates, disease prevalence, geographic entity resolution, and exploring relationships between statistical entities.

SKILL.md

Data Commons Client

Overview

Provides comprehensive access to the Data Commons Python API v2 for querying statistical observations, exploring the knowledge graph, and resolving entity identifiers. Data Commons aggregates data from census bureaus, health organizations, environmental agencies, and other authoritative sources into a unified knowledge graph.

Routing Boundary

Use this skill when the user explicitly asks for Data Commons/datacommons, Data Commons statistical variables, Data Commons entities/DCIDs, or population/economic indicators that fit the Data Commons knowledge graph.

Generic public data, open data, public dataset search, or public download-link collection by itself is not enough to select this skill. Those requests need a clearer Data Commons/statistical-graph signal before this skill becomes the route owner.

Installation

Install the Data Commons Python client with Pandas support:

uv pip install "datacommons-client[Pandas]"

For basic usage without Pandas:

uv pip install datacommons-client

Core Capabilities

The Data Commons API consists of three main endpoints, each detailed in dedicated reference files:

1. Observation Endpoint - Statistical Data Queries

Query time-series statistical data for entities. See references/observation.md for comprehensive documentation.

Primary use cases:

Retrieve population, economic, health, or environmental statistics
Access historical time-series data for trend analysis
Query data for hierarchies (all counties in a state, all countries in a region)

from datacommons_client import DataCommonsClient

client = DataCommonsClient()

# Get latest population data
response = client.observation.fetch(
    variable_dcids=["Count_Person"],
    entity_dcids=["geoId/06"],  # California
    date="latest"
)

# Get time series
response = client.observation.fetch(
    variable_dcids=["UnemploymentRate_Person"],
    entity_dcids=["country/USA"],
    date="all"
)

# Query by hierarchy
response = client.observation.fetch(
    variable_dcids=["MedianIncome_Household"],
    entity_expression="geoId/06<-containedInPlace+{typeOf:County}",
    date="2020"
)

# Discover properties
labels = client.node.fetch_property_labels(
    node_dcids=["geoId/06"],
    out=True
)

# Navigate hierarchy
children = client.node.fetch_place_children(
    node_dcids=["country/USA"]
)

# Get entity names
names = client.node.fetch_entity_names(
    node_dcids=["geoId/06", "geoId/48"]
)

# Resolve by name
response = client.resolve.fetch_dcids_by_name(
    names=["California", "Texas"],
    entity_type="State"
)

# Resolve by coordinates
dcid = client.resolve.fetch_dcid_by_coordinates(
    latitude=37.7749,
    longitude=-122.4194
)

# Resolve Wikidata IDs
response = client.resolve.fetch_dcids_by_wikidata_id(
    wikidata_ids=["Q30", "Q99"]
)

Resolve entities (if starting with names):

resolve_response = client.resolve.fetch_dcids_by_name(
    names=["California", "Texas"]
)
dcids = [r["candidates"][0]["dcid"]
         for r in resolve_response.to_dict().values()
         if r["candidates"]]

Discover available variables (optional):

variables = client.observation.fetch_available_statistical_variables(
    entity_dcids=dcids
)

Query statistical data:

response = client.observation.fetch(
    variable_dcids=["Count_Person", "UnemploymentRate_Person"],
    entity_dcids=dcids,
    date="latest"
)

Process results:

# As dictionary
data = response.to_dict()

# As Pandas DataFrame
df = response.to_observations_as_records()

# Check what variables are available for an entity
available = client.observation.fetch_available_statistical_variables(
    entity_dcids=["geoId/06"]
)

# Or explore via the web interface
# https://datacommons.org/tools/statvar

response = client.observation.fetch(
    variable_dcids=["Count_Person"],
    entity_dcids=["geoId/06", "geoId/48"],
    date="all"
)

# Convert to DataFrame
df = response.to_observations_as_records()
# Columns: date, entity, variable, value

# Reshape for analysis
pivot = df.pivot_table(
    values='value',
    index='date',
    columns='entity'
)

datacommons-client

Summary

SKILL.md

Data Commons Client

Overview

Routing Boundary

Installation

Core Capabilities

1. Observation Endpoint - Statistical Data Queries

2. Node Endpoint - Knowledge Graph Exploration

3. Resolve Endpoint - Entity Identification

Typical Workflow

Finding Statistical Variables

Working with Pandas

API Authentication

Reference Documentation

Additional Resources

Tips for Effective Use

Related skills