| Name | socialmapper JSON |
| Version |
0.6.2
JSON |
| download |
| home_page | None |
| Summary | An open-source Python toolkit that helps understand community connections through mapping demographics and access to points of interest |
| upload_time | 2025-07-08 15:38:41 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | <3.14,>=3.11 |
| license | MIT License
Copyright (c) 2024 Mihiarc
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. |
| keywords |
openstreetmap
census
demographics
gis
mapping
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 🏘️ SocialMapper: Explore Community Connections
[](https://badge.fury.io/py/socialmapper)
[](https://pypi.org/project/socialmapper/)
[](https://opensource.org/licenses/MIT)
[](https://pypi.org/project/socialmapper/)
[](https://pepy.tech/project/socialmapper)
SocialMapper is an open-source Python toolkit that helps you understand how people connect with the important places in their community. Imagine taking a key spot like your local shopping center or school and seeing exactly what areas are within a certain travel time – whether it's a quick walk or a longer drive. SocialMapper does just that.
But it doesn't stop at travel time. SocialMapper also shows you the characteristics of the people who live within these accessible areas, like how many people live there and what the average income is. This helps you see who can easily reach vital community resources and identify any gaps in access.
Whether you're looking at bustling city neighborhoods or more spread-out rural areas, SocialMapper provides clear insights for making communities better, planning services, and ensuring everyone has good access to the places that matter.
SocialMapper is a focused tool for understanding people, places, and accessibility patterns in your community.
## 🚀 Get Started with SocialMapper
**Example: Total Population Within 15-Minute Walk of Libraries in Fuquay-Varina, NC**
## What's New in v0.6.1 🎉
- **🚶♀️ Travel Mode Support** - Generate isochrones for walking, biking, or driving with mode-specific speeds
- **🏗️ Streamlined Architecture** - Simplified codebase focused on core demographic and accessibility analysis
- **⚡ Enhanced Pipeline** - Refactored core functionality into modular ETL pipeline for better maintainability
- **💾 Lightweight Neighbor System** - Streaming census system reduces storage from 118MB to ~0.1MB
- **🗺️ Geographic Level Support** - Choose between census block groups or ZIP Code Tabulation Areas (ZCTAs)
- **🖥️ Enhanced CLI** - New options for addresses, dry-run mode, and more
📚 **[Full Documentation](https://mihiarc.github.io/socialmapper)** | 🐛 **[Report Issues](https://github.com/mihiarc/socialmapper/issues)**
## Features
- **Finding Points of Interest** - Query OpenStreetMap for libraries, schools, parks, healthcare facilities, etc.
- **Generating Travel Time Areas** - Create isochrones showing areas reachable within a certain travel time by walking, biking, or driving
- **Identifying Census Block Groups** - Determine which census block groups intersect with these areas
- **Calculating Travel Distance** - Measure the travel distance along roads from the point of interest to the block group centroids
- **Retrieving Demographic Data** - Pull census data for the identified areas
- **Data Export** - Export census data with travel distances to CSV for further analysis
## Installation
SocialMapper is available on PyPI. Install it easily with uv:
```bash
uv pip install socialmapper
```
Or with pip:
```bash
pip install socialmapper
```
**Requirements:** Python 3.11 or higher (3.11, 3.12, or 3.13)
### Environment Variables
SocialMapper supports environment variables for configuration. Create a `.env` file in your project directory:
```bash
# Copy the example file and customize
cp env.example .env
```
Key environment variables:
- `CENSUS_API_KEY`: Your Census Bureau API key (get one free at https://api.census.gov/data/key_signup.html)
- `CENSUS_CACHE_ENABLED`: Enable/disable caching (default: true)
- `CENSUS_RATE_LIMIT`: API rate limit in requests per minute (default: 60)
See `env.example` for all available configuration options.
## Using SocialMapper
### Quick Start with Python API
```python
from socialmapper import SocialMapperClient
# Simple analysis
with SocialMapperClient() as client:
result = client.analyze(
location="San Francisco, CA",
poi_type="amenity",
poi_name="library",
travel_time=15
)
if result.is_ok():
analysis = result.unwrap()
print(f"Found {analysis.poi_count} libraries")
print(f"Analyzed {analysis.census_units_analyzed} census units")
```
### Advanced Usage with Builder Pattern
```python
from socialmapper import SocialMapperClient, SocialMapperBuilder
with SocialMapperClient() as client:
# Configure analysis using fluent builder
config = (SocialMapperBuilder()
.with_location("Chicago", "IL")
.with_osm_pois("leisure", "park")
.with_travel_time(20)
.with_travel_mode("walk") # Analyze walking access
.with_census_variables("total_population", "median_income", "percent_poverty")
.with_geographic_level("zcta") # Use ZIP codes instead of block groups
.with_exports(csv=True, isochrones=True) # Generate maps
.build()
)
result = client.run_analysis(config)
```
### Using Custom POI Coordinates
```python
from socialmapper import SocialMapperClient, SocialMapperBuilder
with SocialMapperClient() as client:
config = (SocialMapperBuilder()
.with_custom_pois("my_locations.csv")
.with_travel_time(15)
.with_census_variables("total_population")
.build()
)
result = client.run_analysis(config)
```
### Command Line Interface
SocialMapper also provides a powerful command-line interface:
```bash
# Show help
uv run socialmapper --help
# Analyze libraries in Chicago
uv run socialmapper --poi --geocode-area "Chicago" --state "Illinois" \
--poi-type "amenity" --poi-name "library" --travel-time 15 \
--census-variables total_population median_household_income
# Use custom coordinates
uv run socialmapper --custom-coords "path/to/coordinates.csv" \
--travel-time 20 --census-variables total_population median_household_income
# Use ZIP codes instead of block groups
uv run socialmapper --poi --geocode-area "Denver" --state "Colorado" \
--poi-type "amenity" --poi-name "hospital" --geographic-level zcta
# Analyze walking access to parks
uv run socialmapper --poi --geocode-area "Portland" --state "Oregon" \
--poi-type "leisure" --poi-name "park" --travel-time 15 \
--travel-mode walk
```
### Travel Modes
SocialMapper supports three travel modes, each using appropriate road networks and speeds:
- **walk** - Pedestrian paths, sidewalks, crosswalks (default: 5 km/h)
- **bike** - Bike lanes, shared roads, trails (default: 15 km/h)
- **drive** - Roads accessible by cars (default: 50 km/h)
```python
from socialmapper import SocialMapperBuilder, TravelMode
# Compare walking vs driving access
walk_config = (SocialMapperBuilder()
.with_location("Seattle", "WA")
.with_osm_pois("amenity", "grocery_or_supermarket")
.with_travel_time(15)
.with_travel_mode(TravelMode.WALK)
.build()
)
drive_config = (SocialMapperBuilder()
.with_location("Seattle", "WA")
.with_osm_pois("amenity", "grocery_or_supermarket")
.with_travel_time(15)
.with_travel_mode(TravelMode.DRIVE)
.build()
)
```
### Error Handling
The modern API uses Result types for explicit error handling:
```python
from socialmapper import SocialMapperClient
with SocialMapperClient() as client:
result = client.analyze(
location="Invalid Location",
poi_type="amenity",
poi_name="library"
)
# Pattern matching (Python 3.10+)
match result:
case Ok(analysis):
print(f"Success: {analysis.poi_count} POIs found")
case Err(error):
print(f"Error type: {error.type.name}")
print(f"Message: {error.message}")
if error.context:
print(f"Context: {error.context}")
```
## Creating Your Own Community Maps: Step-by-Step Guide
### 1. Define Your Points of Interest
You can specify points of interest with direct command-line parameters.
#### Using the Command Line
You can run the tool directly with POI parameters:
```bash
socialmapper --poi --geocode-area "Fuquay-Varina" --state "North Carolina" --poi-type "amenity" --poi-name "library" --travel-time 15 --census-variables total_population median_household_income
```
### POI Types and Names Reference
Regardless of which method you use, you'll need to specify POI types and names. Common OpenStreetMap POI combinations:
- Libraries: `poi-type: "amenity"`, `poi-name: "library"`
- Schools: `poi-type: "amenity"`, `poi-name: "school"`
- Hospitals: `poi-type: "amenity"`, `poi-name: "hospital"`
- Parks: `poi-type: "leisure"`, `poi-name: "park"`
- Supermarkets: `poi-type: "shop"`, `poi-name: "supermarket"`
- Pharmacies: `poi-type: "amenity"`, `poi-name: "pharmacy"`
Check out the OpenStreetMap Wiki for more on map features: https://wiki.openstreetmap.org/wiki/Map_features
For more specific queries, you can add additional tags in a YAML format:
```yaml
# Example tags:
operator: Chicago Park District
opening_hours: 24/7
```
### 2. Choose Your Target States
If you're using direct POI parameters, you should provide the state where your analysis should occur. This ensures accurate census data selection.
For areas near state borders or POIs spread across multiple states, you don't need to do anything special - the tool will automatically identify the appropriate census data.
### 3. Select Demographics to Analyze
Choose which census variables you want to analyze. Some useful options:
| Description | Notes | SocialMapper Name | Census Variable |
|------------------------------- |--------------------------------------------|--------------------------|----------------------------------------------------|
| Total Population | Basic population count | total_population | B01003_001E |
| Median Household Income | In dollars | median_income | B19013_001E |
| Median Home Value | For owner-occupied units | median_home_value | B25077_001E |
| Median Age | Overall median age | median_age | B01002_001E |
| White Population | Population identifying as white alone | white_population | B02001_002E |
| Black Population | Population identifying as Black/African American alone | black_population | B02001_003E |
| Hispanic Population | Hispanic or Latino population of any race | hispanic_population | B03003_003E |
| Housing Units | Total housing units | housing_units | B25001_001E |
| Education (Bachelor's or higher) | Sum of education categories | education_bachelors_plus | B15003_022E + B15003_023E + B15003_024E + B15003_025E |
### 4. Run the SocialMapper
After specifying your POIs and census variables, SocialMapper will:
- Generate isochrones showing travel time areas
- Identify census block groups within these areas
- Retrieve demographic data for these block groups
- Create maps visualizing the demographics
- Export data to CSV for further analysis
The results will be found in the `output/` directory:
- GeoJSON files with isochrones in `output/isochrones/`
- GeoJSON files with block groups in `output/block_groups/`
- GeoJSON files with census data in `output/census_data/`
- PNG map visualizations in `output/maps/`
- CSV files with census data and travel distances in `output/csv/`
### Example Projects
Here are some examples of community mapping projects you could create:
1. **Food Desert Analysis**: Map supermarkets with travel times and income data to identify areas with limited food access.
```bash
socialmapper --poi --geocode-area "Chicago" --state "Illinois" --poi-type "shop" --poi-name "supermarket" --travel-time 20 --census-variables total_population median_household_income
```
2. **Healthcare Access**: Map hospitals and clinics with population and age demographics.
```bash
socialmapper --poi --geocode-area "Los Angeles" --state "California" --poi-type "amenity" --poi-name "hospital" --travel-time 30 --census-variables total_population median_age
```
3. **Educational Resource Distribution**: Map schools and libraries with educational attainment data.
```bash
socialmapper --poi --geocode-area "Boston" --state "Massachusetts" --poi-type "amenity" --poi-name "school" --travel-time 15 --census-variables total_population education_bachelors_plus
```
4. **Park Access Equity**: Map parks with demographic and income data to assess equitable access.
```bash
socialmapper --poi --geocode-area "Miami" --state "Florida" --poi-type "leisure" --poi-name "park" --travel-time 10 --census-variables total_population median_household_income white_population black_population
```
## Learn More
- 📖 **[Documentation](https://mihiarc.github.io/socialmapper)** - Full documentation and tutorials
- 🎯 **[Examples](https://github.com/mihiarc/socialmapper/tree/main/examples)** - Working code examples
- 💬 **[Discussions](https://github.com/mihiarc/socialmapper/discussions)** - Ask questions and share ideas
- 🐛 **[Issues](https://github.com/mihiarc/socialmapper/issues)** - Report bugs or request features
## Development
For development, clone the repository and install with development dependencies:
```bash
git clone https://github.com/mihiarc/socialmapper.git
cd socialmapper
uv pip install -e ".[dev]"
```
Run tests:
```bash
uv run pytest
```
### Troubleshooting
- **No POIs found**: Check your POI configuration. Try making the query more general or verify that the location name is correct.
- **Census API errors**: Ensure your API key is valid and properly set as an environment variable.
- **Isochrone generation issues**: For very large areas, try reducing the travel time to avoid timeouts.
- **Missing block groups**: The tool should automatically identify the appropriate states based on the POI locations.
## Documentation
- [Travel Modes Explained](docs/travel_modes_explained.md) - Detailed explanation of how walking, biking, and driving networks differ
- [API Reference](https://mihiarc.github.io/socialmapper/) - Full API documentation
- [Examples](examples/) - Sample scripts and use cases
## Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
## License
SocialMapper is released under the MIT License. See the [LICENSE](LICENSE) file for details.
## Citation
If you use SocialMapper in your research, please cite:
```bibtex
@software{socialmapper,
title = {SocialMapper: Community Demographic and Accessibility Analysis},
author = {mihiarc},
year = {2025},
url = {https://github.com/mihiarc/socialmapper}
}
```
Raw data
{
"_id": null,
"home_page": null,
"name": "socialmapper",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.11",
"maintainer_email": null,
"keywords": "OpenStreetMap, census, demographics, gis, mapping",
"author": null,
"author_email": "mihiarc <mihiarc@example.com>",
"download_url": "https://files.pythonhosted.org/packages/37/5d/dad37c5156fc9c0450b9127bbaaae2a52ec72274d1b74921b51e42ab8a99/socialmapper-0.6.2.tar.gz",
"platform": null,
"description": "# \ud83c\udfd8\ufe0f SocialMapper: Explore Community Connections\n\n[](https://badge.fury.io/py/socialmapper)\n[](https://pypi.org/project/socialmapper/)\n[](https://opensource.org/licenses/MIT)\n[](https://pypi.org/project/socialmapper/)\n[](https://pepy.tech/project/socialmapper)\n\nSocialMapper is an open-source Python toolkit that helps you understand how people connect with the important places in their community. Imagine taking a key spot like your local shopping center or school and seeing exactly what areas are within a certain travel time \u2013 whether it's a quick walk or a longer drive. SocialMapper does just that.\n\nBut it doesn't stop at travel time. SocialMapper also shows you the characteristics of the people who live within these accessible areas, like how many people live there and what the average income is. This helps you see who can easily reach vital community resources and identify any gaps in access.\n\nWhether you're looking at bustling city neighborhoods or more spread-out rural areas, SocialMapper provides clear insights for making communities better, planning services, and ensuring everyone has good access to the places that matter.\n\nSocialMapper is a focused tool for understanding people, places, and accessibility patterns in your community.\n\n## \ud83d\ude80 Get Started with SocialMapper\n\n**Example: Total Population Within 15-Minute Walk of Libraries in Fuquay-Varina, NC**\n\n\n\n## What's New in v0.6.1 \ud83c\udf89\n\n- **\ud83d\udeb6\u200d\u2640\ufe0f Travel Mode Support** - Generate isochrones for walking, biking, or driving with mode-specific speeds\n- **\ud83c\udfd7\ufe0f Streamlined Architecture** - Simplified codebase focused on core demographic and accessibility analysis\n- **\u26a1 Enhanced Pipeline** - Refactored core functionality into modular ETL pipeline for better maintainability\n- **\ud83d\udcbe Lightweight Neighbor System** - Streaming census system reduces storage from 118MB to ~0.1MB\n- **\ud83d\uddfa\ufe0f Geographic Level Support** - Choose between census block groups or ZIP Code Tabulation Areas (ZCTAs)\n- **\ud83d\udda5\ufe0f Enhanced CLI** - New options for addresses, dry-run mode, and more\n\n\ud83d\udcda **[Full Documentation](https://mihiarc.github.io/socialmapper)** | \ud83d\udc1b **[Report Issues](https://github.com/mihiarc/socialmapper/issues)**\n\n## Features\n\n- **Finding Points of Interest** - Query OpenStreetMap for libraries, schools, parks, healthcare facilities, etc.\n- **Generating Travel Time Areas** - Create isochrones showing areas reachable within a certain travel time by walking, biking, or driving\n- **Identifying Census Block Groups** - Determine which census block groups intersect with these areas\n- **Calculating Travel Distance** - Measure the travel distance along roads from the point of interest to the block group centroids\n- **Retrieving Demographic Data** - Pull census data for the identified areas\n- **Data Export** - Export census data with travel distances to CSV for further analysis\n\n## Installation\n\nSocialMapper is available on PyPI. Install it easily with uv:\n\n```bash\nuv pip install socialmapper\n```\n\nOr with pip:\n\n```bash\npip install socialmapper\n```\n\n**Requirements:** Python 3.11 or higher (3.11, 3.12, or 3.13)\n\n### Environment Variables\n\nSocialMapper supports environment variables for configuration. Create a `.env` file in your project directory:\n\n```bash\n# Copy the example file and customize\ncp env.example .env\n```\n\nKey environment variables:\n- `CENSUS_API_KEY`: Your Census Bureau API key (get one free at https://api.census.gov/data/key_signup.html)\n- `CENSUS_CACHE_ENABLED`: Enable/disable caching (default: true)\n- `CENSUS_RATE_LIMIT`: API rate limit in requests per minute (default: 60)\n\nSee `env.example` for all available configuration options.\n\n## Using SocialMapper\n\n### Quick Start with Python API\n\n```python\nfrom socialmapper import SocialMapperClient\n\n# Simple analysis\nwith SocialMapperClient() as client:\n result = client.analyze(\n location=\"San Francisco, CA\",\n poi_type=\"amenity\",\n poi_name=\"library\",\n travel_time=15\n )\n \n if result.is_ok():\n analysis = result.unwrap()\n print(f\"Found {analysis.poi_count} libraries\")\n print(f\"Analyzed {analysis.census_units_analyzed} census units\")\n```\n\n### Advanced Usage with Builder Pattern\n\n```python\nfrom socialmapper import SocialMapperClient, SocialMapperBuilder\n\nwith SocialMapperClient() as client:\n # Configure analysis using fluent builder\n config = (SocialMapperBuilder()\n .with_location(\"Chicago\", \"IL\")\n .with_osm_pois(\"leisure\", \"park\")\n .with_travel_time(20)\n .with_travel_mode(\"walk\") # Analyze walking access\n .with_census_variables(\"total_population\", \"median_income\", \"percent_poverty\")\n .with_geographic_level(\"zcta\") # Use ZIP codes instead of block groups\n .with_exports(csv=True, isochrones=True) # Generate maps\n .build()\n )\n \n result = client.run_analysis(config)\n```\n\n### Using Custom POI Coordinates\n\n```python\nfrom socialmapper import SocialMapperClient, SocialMapperBuilder\n\nwith SocialMapperClient() as client:\n config = (SocialMapperBuilder()\n .with_custom_pois(\"my_locations.csv\")\n .with_travel_time(15)\n .with_census_variables(\"total_population\")\n .build()\n )\n \n result = client.run_analysis(config)\n```\n\n### Command Line Interface\n\nSocialMapper also provides a powerful command-line interface:\n\n```bash\n# Show help\nuv run socialmapper --help\n\n# Analyze libraries in Chicago\nuv run socialmapper --poi --geocode-area \"Chicago\" --state \"Illinois\" \\\n --poi-type \"amenity\" --poi-name \"library\" --travel-time 15 \\\n --census-variables total_population median_household_income\n\n# Use custom coordinates\nuv run socialmapper --custom-coords \"path/to/coordinates.csv\" \\\n --travel-time 20 --census-variables total_population median_household_income\n\n# Use ZIP codes instead of block groups\nuv run socialmapper --poi --geocode-area \"Denver\" --state \"Colorado\" \\\n --poi-type \"amenity\" --poi-name \"hospital\" --geographic-level zcta\n\n# Analyze walking access to parks\nuv run socialmapper --poi --geocode-area \"Portland\" --state \"Oregon\" \\\n --poi-type \"leisure\" --poi-name \"park\" --travel-time 15 \\\n --travel-mode walk\n```\n\n### Travel Modes\n\nSocialMapper supports three travel modes, each using appropriate road networks and speeds:\n\n- **walk** - Pedestrian paths, sidewalks, crosswalks (default: 5 km/h)\n- **bike** - Bike lanes, shared roads, trails (default: 15 km/h) \n- **drive** - Roads accessible by cars (default: 50 km/h)\n\n```python\nfrom socialmapper import SocialMapperBuilder, TravelMode\n\n# Compare walking vs driving access\nwalk_config = (SocialMapperBuilder()\n .with_location(\"Seattle\", \"WA\")\n .with_osm_pois(\"amenity\", \"grocery_or_supermarket\")\n .with_travel_time(15)\n .with_travel_mode(TravelMode.WALK)\n .build()\n)\n\ndrive_config = (SocialMapperBuilder()\n .with_location(\"Seattle\", \"WA\")\n .with_osm_pois(\"amenity\", \"grocery_or_supermarket\")\n .with_travel_time(15)\n .with_travel_mode(TravelMode.DRIVE)\n .build()\n)\n```\n\n### Error Handling\n\nThe modern API uses Result types for explicit error handling:\n\n```python\nfrom socialmapper import SocialMapperClient\n\nwith SocialMapperClient() as client:\n result = client.analyze(\n location=\"Invalid Location\",\n poi_type=\"amenity\",\n poi_name=\"library\"\n )\n \n # Pattern matching (Python 3.10+)\n match result:\n case Ok(analysis):\n print(f\"Success: {analysis.poi_count} POIs found\")\n case Err(error):\n print(f\"Error type: {error.type.name}\")\n print(f\"Message: {error.message}\")\n if error.context:\n print(f\"Context: {error.context}\")\n```\n\n## Creating Your Own Community Maps: Step-by-Step Guide\n\n### 1. Define Your Points of Interest\n\nYou can specify points of interest with direct command-line parameters.\n\n#### Using the Command Line\n\nYou can run the tool directly with POI parameters:\n\n```bash\nsocialmapper --poi --geocode-area \"Fuquay-Varina\" --state \"North Carolina\" --poi-type \"amenity\" --poi-name \"library\" --travel-time 15 --census-variables total_population median_household_income\n```\n\n### POI Types and Names Reference\n\nRegardless of which method you use, you'll need to specify POI types and names. Common OpenStreetMap POI combinations:\n\n- Libraries: `poi-type: \"amenity\"`, `poi-name: \"library\"`\n- Schools: `poi-type: \"amenity\"`, `poi-name: \"school\"`\n- Hospitals: `poi-type: \"amenity\"`, `poi-name: \"hospital\"`\n- Parks: `poi-type: \"leisure\"`, `poi-name: \"park\"`\n- Supermarkets: `poi-type: \"shop\"`, `poi-name: \"supermarket\"`\n- Pharmacies: `poi-type: \"amenity\"`, `poi-name: \"pharmacy\"`\n\nCheck out the OpenStreetMap Wiki for more on map features: https://wiki.openstreetmap.org/wiki/Map_features\n\nFor more specific queries, you can add additional tags in a YAML format:\n```yaml\n# Example tags:\noperator: Chicago Park District\nopening_hours: 24/7\n```\n\n### 2. Choose Your Target States\n\nIf you're using direct POI parameters, you should provide the state where your analysis should occur. This ensures accurate census data selection.\n\nFor areas near state borders or POIs spread across multiple states, you don't need to do anything special - the tool will automatically identify the appropriate census data.\n\n### 3. Select Demographics to Analyze\n\nChoose which census variables you want to analyze. Some useful options:\n\n| Description | Notes | SocialMapper Name | Census Variable |\n|------------------------------- |--------------------------------------------|--------------------------|----------------------------------------------------|\n| Total Population | Basic population count | total_population | B01003_001E |\n| Median Household Income | In dollars | median_income | B19013_001E |\n| Median Home Value | For owner-occupied units | median_home_value | B25077_001E |\n| Median Age | Overall median age | median_age | B01002_001E |\n| White Population | Population identifying as white alone | white_population | B02001_002E |\n| Black Population | Population identifying as Black/African American alone | black_population | B02001_003E |\n| Hispanic Population | Hispanic or Latino population of any race | hispanic_population | B03003_003E |\n| Housing Units | Total housing units | housing_units | B25001_001E |\n| Education (Bachelor's or higher) | Sum of education categories | education_bachelors_plus | B15003_022E + B15003_023E + B15003_024E + B15003_025E |\n\n### 4. Run the SocialMapper\n\nAfter specifying your POIs and census variables, SocialMapper will:\n- Generate isochrones showing travel time areas\n- Identify census block groups within these areas\n- Retrieve demographic data for these block groups\n- Create maps visualizing the demographics\n- Export data to CSV for further analysis\n\nThe results will be found in the `output/` directory:\n- GeoJSON files with isochrones in `output/isochrones/`\n- GeoJSON files with block groups in `output/block_groups/`\n- GeoJSON files with census data in `output/census_data/`\n- PNG map visualizations in `output/maps/`\n- CSV files with census data and travel distances in `output/csv/`\n\n### Example Projects\n\nHere are some examples of community mapping projects you could create:\n\n1. **Food Desert Analysis**: Map supermarkets with travel times and income data to identify areas with limited food access.\n ```bash\n socialmapper --poi --geocode-area \"Chicago\" --state \"Illinois\" --poi-type \"shop\" --poi-name \"supermarket\" --travel-time 20 --census-variables total_population median_household_income\n ```\n\n2. **Healthcare Access**: Map hospitals and clinics with population and age demographics.\n ```bash\n socialmapper --poi --geocode-area \"Los Angeles\" --state \"California\" --poi-type \"amenity\" --poi-name \"hospital\" --travel-time 30 --census-variables total_population median_age\n ```\n\n3. **Educational Resource Distribution**: Map schools and libraries with educational attainment data.\n ```bash\n socialmapper --poi --geocode-area \"Boston\" --state \"Massachusetts\" --poi-type \"amenity\" --poi-name \"school\" --travel-time 15 --census-variables total_population education_bachelors_plus\n ```\n\n4. **Park Access Equity**: Map parks with demographic and income data to assess equitable access.\n ```bash\n socialmapper --poi --geocode-area \"Miami\" --state \"Florida\" --poi-type \"leisure\" --poi-name \"park\" --travel-time 10 --census-variables total_population median_household_income white_population black_population\n ```\n\n## Learn More\n\n- \ud83d\udcd6 **[Documentation](https://mihiarc.github.io/socialmapper)** - Full documentation and tutorials\n- \ud83c\udfaf **[Examples](https://github.com/mihiarc/socialmapper/tree/main/examples)** - Working code examples\n- \ud83d\udcac **[Discussions](https://github.com/mihiarc/socialmapper/discussions)** - Ask questions and share ideas\n- \ud83d\udc1b **[Issues](https://github.com/mihiarc/socialmapper/issues)** - Report bugs or request features\n\n## Development\n\nFor development, clone the repository and install with development dependencies:\n\n```bash\ngit clone https://github.com/mihiarc/socialmapper.git\ncd socialmapper\nuv pip install -e \".[dev]\"\n```\n\nRun tests:\n```bash\nuv run pytest\n```\n\n### Troubleshooting\n\n- **No POIs found**: Check your POI configuration. Try making the query more general or verify that the location name is correct.\n- **Census API errors**: Ensure your API key is valid and properly set as an environment variable.\n- **Isochrone generation issues**: For very large areas, try reducing the travel time to avoid timeouts.\n- **Missing block groups**: The tool should automatically identify the appropriate states based on the POI locations.\n\n## Documentation\n\n- [Travel Modes Explained](docs/travel_modes_explained.md) - Detailed explanation of how walking, biking, and driving networks differ\n- [API Reference](https://mihiarc.github.io/socialmapper/) - Full API documentation\n- [Examples](examples/) - Sample scripts and use cases\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n## License\n\nSocialMapper is released under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n## Citation\n\nIf you use SocialMapper in your research, please cite:\n\n```bibtex\n@software{socialmapper,\n title = {SocialMapper: Community Demographic and Accessibility Analysis},\n author = {mihiarc},\n year = {2025},\n url = {https://github.com/mihiarc/socialmapper}\n}\n```",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2024 Mihiarc\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE. ",
"summary": "An open-source Python toolkit that helps understand community connections through mapping demographics and access to points of interest",
"version": "0.6.2",
"project_urls": {
"Bug Tracker": "https://github.com/mihiarc/socialmapper/issues",
"Homepage": "https://github.com/mihiarc/socialmapper"
},
"split_keywords": [
"openstreetmap",
" census",
" demographics",
" gis",
" mapping"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2f4099e9ff6ad6e83049b82fec73ddb6100f3f2e416c954503059dd3c47b848e",
"md5": "2861cb69ec71ffd5d09ac33afbaea56d",
"sha256": "a99763ead1c5d923b669e5c4a8e4383b27c01401d8bed887ae88bb5a252d1a49"
},
"downloads": -1,
"filename": "socialmapper-0.6.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2861cb69ec71ffd5d09ac33afbaea56d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.11",
"size": 354547,
"upload_time": "2025-07-08T15:38:40",
"upload_time_iso_8601": "2025-07-08T15:38:40.059130Z",
"url": "https://files.pythonhosted.org/packages/2f/40/99e9ff6ad6e83049b82fec73ddb6100f3f2e416c954503059dd3c47b848e/socialmapper-0.6.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "375ddad37c5156fc9c0450b9127bbaaae2a52ec72274d1b74921b51e42ab8a99",
"md5": "8349309c4c1bfb4fde187229118dd0fd",
"sha256": "1c7ece63fd59bf65fc11b3a82935e2bf330aa0857aa839f6feb73434f37bab1e"
},
"downloads": -1,
"filename": "socialmapper-0.6.2.tar.gz",
"has_sig": false,
"md5_digest": "8349309c4c1bfb4fde187229118dd0fd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.11",
"size": 21167563,
"upload_time": "2025-07-08T15:38:41",
"upload_time_iso_8601": "2025-07-08T15:38:41.945794Z",
"url": "https://files.pythonhosted.org/packages/37/5d/dad37c5156fc9c0450b9127bbaaae2a52ec72274d1b74921b51e42ab8a99/socialmapper-0.6.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-08 15:38:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mihiarc",
"github_project": "socialmapper",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "socialmapper"
}
