Skip to content

foryourhealth111-pixel/Vibe-Skills / bundled/skills/datacommons-client

datacommons-client

Verified

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.

FileKindSize
SKILL.mdskill md8.3 KB
references/getting_started.mdmarkdown9.9 KB
references/node.mdmarkdown6.0 KB
references/observation.mdmarkdown5.4 KB
references/resolve.mdmarkdown7.0 KB

references/resolve.md

View on GitHub
# Resolve Endpoint - Entity Identification

## Purpose

The Resolve API identifies Data Commons IDs (DCIDs) for entities in the knowledge graph. DCIDs are required for most queries in the Data Commons API, so resolution is typically the first step in any workflow.

## Key Capabilities

The endpoint currently supports **place entities only** and allows resolution through multiple methods:
- **By name**: Search using descriptive terms like "San Francisco, CA"
- **By Wikidata ID**: Lookup using external identifiers (e.g., "Q30" for USA)
- **By coordinates**: Locate places via latitude/longitude
- **By relation expressions**: Advanced searches using synthetic attributes

## Available Methods

### 1. fetch()

General resolution using relation expressions—most flexible method.

**Parameters:**
- `nodes`: List of search terms or identifiers
- `property`: Property to search (e.g., "name", "wikidataId")

**Example Usage:**
```python
from datacommons_client import DataCommonsClient

client = DataCommonsClient()

# Resolve by name
response = client.resolve.fetch(
    nodes=["California", "Texas"],
    property="name"
)
```

### 2. fetch_dcids_by_name()

Name-based lookup with optional type filtering—most commonly used method.

**Parameters:**
- `names`: List of place names to resolve
- `entity_type`: Optional type filter (e.g., "City", "State", "County")

**Returns:** `ResolveResponse` object with candidates for each name

**Example Usage:**
```python
# Basic name resolution
response = client.resolve.fetch_dcids_by_name(
    names=["San Francisco, CA", "Los Angeles"]
)

# With type filtering
response = client.resolve.fetch_dcids_by_name(
    names=["San Francisco"],
    entity_type="City"
)

# Access results
for name, result in response.to_dict().items():
    print(f"{name}: {result['candidates']}")
```

### 3. fetch_dcids_by_wikidata_id()

Wikidata ID resolution for entities with known Wikidata identifiers.

**Parameters:**
- `wikidata_ids`: List of Wikidata IDs (e.g., "Q30", "Q99")

**Example Usage:**
```python
# Resolve Wikidata IDs
response = client.resolve.fetch_dcids_by_wikidata_id(
    wikidata_ids=["Q30", "Q99"]  # USA and California
)
```

### 4. fetch_dcid_by_coordinates()

Geographic coordinate lookup to find the place at specific lat/long coordinates.

**Parameters:**
- `latitude`: Latitude coordinate
- `longitude`: Longitude coordinate

**Returns:** Single DCID string for the place at those coordinates

**Example Usage:**
```python
# Find place at coordinates
dcid = client.resolve.fetch_dcid_by_coordinates(
    latitude=37.7749,
    longitude=-122.4194
)
# Returns DCID for San Francisco
```

## Response Structure

All methods (except `fetch_dcid_by_coordinates`) return a `ResolveResponse` object containing:
- **node**: The search term provided
- **candidates**: List of matching DCIDs with optional metadata
  - Each candidate may include `dominantType` field for disambiguation
- **Helper methods**:
  - `to_dict()`: Full response as dictionary
  - `to_json()`: JSON string format
  - `to_flat_dict()`: Simplified format with just DCIDs

**Example Response:**
```python
response = client.resolve.fetch_dcids_by_name(names=["Springfield"])

# May return multiple candidates since many cities named Springfield exist
# {
#   "Springfield": {
#     "candidates": [
#       {"dcid": "geoId/1767000", "dominantType": "City"},  # Springfield, IL
#       {"dcid": "geoId/2567000", "dominantType": "City"},  # Springfield, MA
#       ...
#     ]
#   }
# }
```

## Common Use Cases

### Use Case 1: Resolve Place Names Before Querying

Most workflows start by resolving names to DCIDs:
```python
# Step 1: Resolve names
resolve_response = client.resolve.fetch_dcids_by_name(
    names=["California", "Texas"]
)

# Step 2: Extract DCIDs
dcids = []
for name, result in resolve_response.to_dict().items():
    if result["candidates"]:
        dcids.append(result["candidates"][0]["dcid"])

# Step 3: Query data using DCIDs
data_response = client.observation.fetch(
    variable_dcids=["Count_Person"],
    entity_dcids=dcids,
    date="latest"
)
```

### Use Case 2: Handle Ambiguous Names

When multiple candidates exist, use `dominantType` or be more specific:
```python
# Ambiguous name
response = client.resolve.fetch_dcids_by_name(names=["Springfield"])
candidates = response.to_dict()["Springfield"]["candidates"]

# Filter by type or choose based on context
city_candidates = [c for c in candidates if c.get("dominantType") == "City"]

# Or be more specific in the query
response = client.resolve.fetch_dcids_by_name(
    names=["Springfield, Illinois"],
    entity_type="City"
)
```

### Use Case 3: Batch Resolution

Resolve multiple entities efficiently:
```python
places = [
    "San Francisco, CA",
    "Los Angeles, CA",
    "San Diego, CA",
    "Sacramento, CA"
]

response = client.resolve.fetch_dcids_by_name(names=places)

# Build mapping of name to DCID
name_to_dcid = {}
for name, result in response.to_dict().items():
    if result["candidates"]:
        name_to_dcid[name] = result["candidates"][0]["dcid"]
```

### Use Case 4: Coordinate-Based Queries

Find the administrative place for a location:
```python
# User provides coordinates, find the place
latitude, longitude = 37.7749, -122.4194
dcid = client.resolve.fetch_dcid_by_coordinates(
    latitude=latitude,
    longitude=longitude
)

# Now query data for that place
response = client.observation.fetch(
    variable_dcids=["Count_Person", "MedianIncome_Household"],
    entity_dcids=[dcid],
    date="latest"
)
```

### Use Case 5: External ID Integration

When working with external datasets that use Wikidata IDs:
```python
# External dataset has Wikidata IDs
wikidata_ids = ["Q30", "Q99", "Q1384"]  # USA, California, New York

# Convert to Data Commons DCIDs
response = client.resolve.fetch_dcids_by_wikidata_id(
    wikidata_ids=wikidata_ids
)

# Extract DCIDs for further queries
dcids = []
for wid, result in response.to_dict().items():
    if result["candidates"]:
        dcids.append(result["candidates"][0]["dcid"])
```

## Important Limitations

1. **Place entities only**: The Resolve API currently supports only place entities (countries, states, cities, counties, etc.). For other entity types, DCIDs must be obtained through other means (e.g., Node API exploration).

2. **Cannot resolve linked entity properties**: For queries involving relationships like `containedInPlace`, use the Node API instead.

3. **Ambiguity handling**: When multiple candidates exist, the API returns all matches. The application must decide which is correct based on context or additional filtering.

## Best Practices

1. **Always resolve names first**: Never assume DCID format—always use the Resolve API
2. **Cache resolutions**: If querying the same places repeatedly, cache name→DCID mappings
3. **Handle ambiguity**: Check for multiple candidates and use `entity_type` filtering or more specific names
4. **Validate results**: Always check that `candidates` list is not empty before accessing DCIDs
5. **Use appropriate method**:
   - Names → `fetch_dcids_by_name()`
   - Coordinates → `fetch_dcid_by_coordinates()`
   - Wikidata IDs → `fetch_dcids_by_wikidata_id()`
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexUnverifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall