Index of every page on this site: llms.txt
All skills
davila7 avatar

/datacommons-client

@053feb2
Run it yourself

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.

Use this Skill: https://skilld.dev/gh/davila7/claude-code-templates/datacommons-client

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈122 tokens for metadata: the name and description. ≈1.9k when used: this file. ≈7.2k more on demand in 4 files.

Description uses 6.1% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈487 characters, or 6.1%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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.

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)
  • Compare statistics across multiple entities
  • Filter by data source for consistency

Common patterns:

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"
)

2. Node Endpoint - Knowledge Graph Exploration

Explore entity relationships and properties within the knowledge graph. See references/node.md for comprehensive documentation.

Primary use cases:

  • Discover available properties for entities
  • Navigate geographic hierarchies (parent/child relationships)
  • Retrieve entity names and metadata
  • Explore connections between entities
  • List all entity types in the graph

Common patterns:

# 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"]
)

3. Resolve Endpoint - Entity Identification

Translate entity names, coordinates, or external IDs into Data Commons IDs (DCIDs). See references/resolve.md for comprehensive documentation.

Primary use cases:

  • Convert place names to DCIDs for queries
  • Resolve coordinates to places
  • Map Wikidata IDs to Data Commons entities
  • Handle ambiguous entity names

Common patterns:

# 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"]
)

Typical Workflow

Most Data Commons queries follow this pattern:

  1. 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"]]
  2. Discover available variables (optional):

    variables = client.observation.fetch_available_statistical_variables(
        entity_dcids=dcids
    )
  3. Query statistical data:

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

    # As dictionary
    data = response.to_dict()
    
    # As Pandas DataFrame
    df = response.to_observations_as_records()

Finding Statistical Variables

Statistical variables use specific naming patterns in Data Commons:

Common variable patterns:

  • Count_Person - Total population
  • Count_Person_Female - Female population
  • UnemploymentRate_Person - Unemployment rate
  • Median_Income_Household - Median household income
  • Count_Death - Death count
  • Median_Age_Person - Median age

Discovery methods:

# 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

Working with Pandas

All observation responses integrate with Pandas:

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'
)

API Authentication

For datacommons.org (default):

  • An API key is required
  • Set via environment variable: export DC_API_KEY="your_key"
  • Or pass when initializing: client = DataCommonsClient(api_key="your_key")
  • Request keys at: https://apikeys.datacommons.org/

For custom Data Commons instances:

  • No API key required
  • Specify custom endpoint: client = DataCommonsClient(url="https://custom.datacommons.org")

Reference Documentation

Comprehensive documentation for each endpoint is available in the references/ directory:

  • references/observation.md: Complete Observation API documentation with all methods, parameters, response formats, and common use cases
  • references/node.md: Complete Node API documentation for graph exploration, property queries, and hierarchy navigation
  • references/resolve.md: Complete Resolve API documentation for entity identification and DCID resolution
  • references/getting_started.md: Quickstart guide with end-to-end examples and common patterns

Additional Resources

Tips for Effective Use

  1. Always start with resolution: Convert names to DCIDs before querying data
  2. Use relation expressions for hierarchies: Query all children at once instead of individual queries
  3. Check data availability first: Use fetch_available_statistical_variables() to see what's queryable
  4. Leverage Pandas integration: Convert responses to DataFrames for analysis
  5. Cache resolutions: If querying the same entities repeatedly, store name→DCID mappings
  6. Filter by facet for consistency: Use filter_facet_domains to ensure data from the same source
  7. Read reference docs: Each endpoint has extensive documentation in the references/ directory

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 alert1mo4 checks · Risk HIGH
  • Gen Agent Trust Hub1mo

    This skill instructs users to install a Python package named 'datacommons-client', which differs from the official 'datacommons' library provided by the Data Commons organization. This mismatch, despite referencing official Data Commons websites and repositories, suggests a potential supply chain attack such as typosquatting. Additionally, the skill ingests data from external APIs and performs file operations without explicit sanitization, presenting a vulnerability to indirect prompt injection.

  • Socket1mo

    No alerts

  • Snyk1mo

    Risk: LOW · No issues

  • Runlayer9mo

    5/5 files flagged

Signed by skilld at 053feb2. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated last year

README badge

README badge for davila7/claude-code-templates/datacommons-client