# Getting Started with Data Commons
## Quick Start Guide
This guide provides end-to-end examples for common Data Commons workflows.
## Installation and Setup
```bash
# Install with Pandas support
pip install "datacommons-client[Pandas]"
# Set up API key for datacommons.org
export DC_API_KEY="your_api_key_here"
```
Request an API key at: https://apikeys.datacommons.org/
## Example 1: Basic Population Query
Query current population for specific places:
```python
from datacommons_client import DataCommonsClient
# Initialize client
client = DataCommonsClient()
# Step 1: Resolve place names to DCIDs
places = ["California", "Texas", "New York"]
resolve_response = client.resolve.fetch_dcids_by_name(
names=places,
entity_type="State"
)
# Extract DCIDs
dcids = []
for name, result in resolve_response.to_dict().items():
if result["candidates"]:
dcids.append(result["candidates"][0]["dcid"])
print(f"{name}: {result['candidates'][0]['dcid']}")
# Step 2: Query population data
response = client.observation.fetch(
variable_dcids=["Count_Person"],
entity_dcids=dcids,
date="latest"
)
# Step 3: Display results
data = response.to_dict()
for variable, entities in data.items():
for entity, observations in entities.items():
for obs in observations:
print(f"{entity}: {obs['value']:,} people ({obs['date']})")
```
## Example 2: Time Series Analysis
Retrieve and plot historical unemployment rates:
```python
import pandas as pd
import matplotlib.pyplot as plt
client = DataCommonsClient()
# Query unemployment rate over time
response = client.observation.fetch(
variable_dcids=["UnemploymentRate_Person"],
entity_dcids=["country/USA"],
date="all" # Get all historical data
)
# Convert to DataFrame
df = response.to_observations_as_records()
# Plot
df = df.sort_values('date')
plt.figure(figsize=(12, 6))
plt.plot(df['date'], df['value'])
plt.title('US Unemployment Rate Over Time')
plt.xlabel('Year')
plt.ylabel('Unemployment Rate (%)')
plt.grid(True)
plt.show()
```
## Example 3: Geographic Hierarchy Query
Get data for all counties within a state:
```python
client = DataCommonsClient()
# Query median income for all California counties
response = client.observation.fetch(
variable_dcids=["Median_Income_Household"],
entity_expression="geoId/06 1:
print(f"Multiple matches found: {len(result['candidates'])}")
for candidate in result["candidates"]:
print(f" {candidate['dcid']} ({candidate.get('dominantType', 'N/A')})")
# Let user select or use additional filtering
```
## Next Steps
1. Explore available statistical variables: https://datacommons.org/tools/statvar
2. Browse the knowledge graph: https://datacommons.org/browser/
3. Read detailed endpoint documentation in `references/` directory
4. Check official documentation: https://docs.datacommons.org/api/python/v2/
Source: claude-code-templates (MIT). See About Us for full credits.