v1.1.1 - Version Fix

Bug Fixes

• Fixed __version__ attribute - Package now correctly reports version 1.1.1 (was incorrectly showing 1.0.0 in v1.1.0)

Installation

pip install socialmapper==1.1.1

# With fast routing backends:
pip install socialmapper[routing]==1.1.1

Full Changelog: https://github.com/mihiarc/socialmapper/blob/main/CHANGELOG.md

v1.1.0 - Fast Routing Backends & Tutorials

What's New in v1.1.0

Fast Isochrone Generation with Routing APIs

• 10-100x faster isochrone generation via external routing APIs
• routingpy integration with Valhalla, OSRM, OpenRouteService, GraphHopper
• Automatic fallback to NetworkX when APIs unavailable

# Use fast Valhalla backend (default)
iso = create_isochrone("Seattle, WA", travel_time=15, backend="valhalla")

Comprehensive Tutorials

• 7-part tutorial series from beginner to advanced
• 7 Jupyter notebooks ready for Google Colab
• Topics: Isochrones, POIs, Census data, Mapping, Complete workflows

Bug Fixes

• Fixed multi-county census block selection for large isochrones
• Fixed POI category validation in tutorials

Installation

pip install socialmapper==1.1.0

# With fast routing backends:
pip install socialmapper[routing]==1.1.0

Full Changelog: https://github.com/mihiarc/socialmapper/blob/main/CHANGELOG.md

v1.0.0 - First Stable Release

SocialMapper v1.0.0

The first stable release of SocialMapper - a Python library for community accessibility analysis and demographic mapping.

Core Features

5 Simple API Functions:

• create_isochrone() - Generate travel-time polygons (drive, walk, bike)
• get_census_blocks() - Fetch census block groups for any area
• get_census_data() - Retrieve demographic data from US Census
• create_map() - Generate choropleth map visualizations
• get_poi() - Find points of interest near locations

Highlights

• Simple API - Just 5 functions for all your spatial analysis needs
• Built-in Caching - Automatic caching for geocoding and network data
• Web UI - Streamlit-based interactive exploration
• Helpful Errors - Context-aware exceptions with troubleshooting guidance
• Well Tested - 165 tests covering core functionality

Installation

pip install socialmapper

Quick Start

from socialmapper import create_isochrone, get_census_data

# Create a 15-minute driving isochrone
iso = create_isochrone("Portland, OR", travel_time=15)

# Get population data for the area
data = get_census_data(iso, variables=["population"])

Requirements

• Python 3.11+
• Census API key (free from https://api.census.gov/data/key_signup.html)

Documentation

See the README for full documentation.

v0.6.2 - Fix Travel Time Propagation

🐛 Bug Fixes

Fixed Travel Time Propagation in Census Data Export

• Fixed incorrect travel_time_minutes in exported census CSV files
• Travel time now correctly propagates from pipeline configuration to census data
• Previously defaulted to 15 minutes regardless of actual isochrone travel time
• Now accurately reflects the travel time used for isochrone generation (e.g., 60, 120 minutes)

🔧 Technical Details

• Added travel_time parameter to integrate_census_data() function
• Updated PipelineOrchestrator to pass travel_time to census integration
• Modified add_travel_distances() to accept and use travel_time parameter
• Maintains backward compatibility while fixing the metadata accuracy

📦 Installation

pip install socialmapper==0.6.2

Full Changelog: v0.6.1...v0.6.2

v0.6.1 - Fix Isochrone Export

🐛 Bug Fixes

Fixed Isochrone Export Functionality

• Fixed missing implementation of enable_isochrone_export() in the pipeline
• Added GeoParquet export for isochrone geometries when enabled
• Updated API client to properly track exported isochrone files
• Files are now saved to output/isochrones/ directory as GeoParquet format

📚 Documentation Updates

Enhanced API Documentation

• Updated enable_isochrone_export() documentation with detailed usage
  examples
• Added isochrone file path to AnalysisResult documentation
• New examples showing how to load and visualize exported isochrones
• Updated exporting guide with modern API examples and GeoParquet format
  details

🔧 Technical Details

• Isochrones are exported using the naming pattern:
  {base_filename}_{travel_time}min_isochrones.geoparquet
• GeoParquet format with snappy compression for efficient storage
• Files can be loaded with GeoPandas and converted to other formats (Shapefile,
  GeoJSON)
• Exported isochrone files are included in
  analysis.files_generated['isochrone_data']

v0.6.0

[0.6.0] - 2025-06-18

🚀 Major Features

🎨 Streamlit UI Overhaul

• Completely redesigned Streamlit application with multi-page tutorial structure
• Interactive tutorials for Getting Started, Custom POIs, and Travel Modes
• Enhanced UI components with better error handling and user feedback
• Map previews and downloadable results for all analyses
• Travel mode comparison with equity analysis features

📦 Updated Dependencies

• Streamlit 1.46.0 - Latest version with improved performance
• Streamlit-Folium 0.25.0 - Better map integration
• All packages updated to their latest stable versions
• Better compatibility with modern Python environments

🔧 Error Handling Improvements

• Comprehensive error handling throughout census and isochrone services
• Better error messages for common issues
• Graceful fallbacks when services are unavailable
• Improved logging for debugging

✨ New Features

Streamlit Pages

1. Getting Started - Interactive introduction to SocialMapper

2. Custom POIs - Upload and analyze custom locations with:

   • CSV file upload with validation
   • Interactive map preview
   • Multiple export formats
   • Detailed demographic analysis

3. Travel Modes - Compare accessibility across different modes:

   • Side-by-side comparison of walk, bike, and drive
   • Equity analysis based on income distribution
   • Distance distribution visualizations
   • Comprehensive demographic comparisons

4. ZCTA Analysis - (Coming Soon) ZIP code level analysis

Enhanced Visualization

• Map downloads for all generated visualizations
• Preview capabilities for maps and data tables
• Better labeling of exported files
• Support for multiple map types (accessibility, distance, demographics)

🔧 Technical Improvements

Code Organization

• Modular page structure for Streamlit app
• Centralized configuration for POI types, census variables, and travel modes
• Reusable UI components for maps and data display
• Better separation of concerns between UI and business logic

Census Integration

• Fixed import errors in census pipeline
• Better error handling for census API failures
• Numba compatibility fixes for caching
• Improved ZCTA support (partial implementation)

File Management

• Better handling of directory structures in exports
• Individual file downloads for map directories
• User-friendly file naming for downloads
• Support for various file formats (PNG, CSV, GeoJSON)

🐛 Bug Fixes

• Fixed AttributeError with PosixPath objects in file handling
• Fixed IsADirectoryError when trying to open directories as files
• Fixed missing imports for format_number and format_currency utilities
• Fixed numba caching errors in distance calculations
• Resolved import errors in census pipeline module
• Fixed relative import issues in Streamlit app structure

📈 Performance Improvements

• Optimized file loading in Streamlit pages
• Better memory management for large analyses
• Improved caching for repeated operations
• Faster map rendering with selective data loading

🏘️ User Experience

• Clearer error messages when analyses fail
• Progress indicators for long-running operations
• Helpful tooltips and explanations throughout UI
• Example templates for custom POI uploads
• Comprehensive analysis summaries in JSON format

📊 Data Export Enhancements

• Multiple export formats supported (CSV, PNG, GeoJSON)
• Organized file structure for outputs
• Downloadable analysis summaries
• Better file naming conventions

🚧 Known Issues

• ZCTA Analysis temporarily disabled pending full implementation
• Some advanced features may require additional testing
• Large dataset processing may be slower in Streamlit environment

🔄 Migration Notes

• Streamlit app location changed - use streamlit run streamlit_app.py from root
• Updated dependencies may require virtual environment refresh
• New page-based structure replaces single-page app
• Configuration moved to centralized location

📚 Documentation

• Improved in-app documentation with tutorial content
• Better code comments throughout new features
• Updated type hints for better IDE support
• Comprehensive docstrings for new functions

---

v0.5.0

🚀 SocialMapper v0.5.0 - Performance Optimization Release

Status: Pre-release (Alpha)
Performance: 17.3x Performance Improvement
Breaking Changes: Streamlit UI components affected

⚠️ Important Notes

• Pre-release Software: This version may contain bugs and is not production-ready
• Streamlit App: The web interface has breaking changes and may not function correctly
• Testing Recommended: Thoroughly test with your specific use cases before deployment

🎯 Key Improvements

• 17.3x Performance Improvement: Core processing engine optimized for large datasets
• Memory Optimization: 84% reduction in memory usage through streaming
• Internal Architecture Updates: Modernized distance calculations and isochrone generation

📊 Benchmark Results

Dataset Size	v0.4.3	v0.5.0	Improvement
50 POIs	~45 minutes	1.1 minutes	41x faster
500 POIs	~4.5 hours	5.2 minutes	52x faster
2,659 POIs	5.3 hours	18.5 minutes	17.3x faster

🔧 Technical Changes

• Distance Engine: Numba JIT compilation, vectorized NumPy operations
• Isochrone System: DBSCAN clustering, SQLite caching, 80% reduction in network downloads
• Data Pipeline: Streaming architecture, Parquet support, memory monitoring

💾 Installation

pip install socialmapper==0.5.0
# or
uv add socialmapper==0.5.0

📋 Breaking Changes

• Streamlit UI components require updates
• Some internal APIs have changed (main functions remain compatible)
• Configuration system restructured

For detailed information, see the full Release Announcement.

Census Module

SocialMapper v0.4.2-beta Release Notes

🚀 Major Performance Optimization Release

Release Date: May 24, 2025
Previous Version: v0.4.1-beta
Breaking Changes: None (Backward compatible)

---

🎯 Overview

This release introduces massive performance improvements to SocialMapper's neighbor relationship system, delivering 10x to 4000x faster geographic operations.

⚡ Performance Improvements

Neighbor Lookups

• State neighbors: 10-50x faster (sub-millisecond lookups)
• County neighbors: 100x faster with pre-computed spatial relationships
• Cross-state relationships: Now included for complete coverage

Point-to-Geography Operations

• Point geocoding: 100-1000x faster with intelligent caching
• POI processing: 100-4000x faster batch operations
• Repeat lookups: Instant response from cache

Database Optimization

• Pre-computed relationships: 218 state + 18,560 county neighbor pairs
• Spatial indexing: DuckDB-powered geographic queries
• Packaged database: 6.0MB neighbor database included in distribution

---

🆕 New Features

Unified Neighbor API

Three convenient access methods for neighbor functionality:

# 1. Package-level access (simplest)
import socialmapper
neighbors = socialmapper.get_neighboring_states('37')  # North Carolina

# 2. Dedicated neighbors module (most features)
import socialmapper.neighbors as neighbors
nc_neighbors = neighbors.get_neighboring_states_by_abbr('NC')
stats = neighbors.get_statistics()

# 3. Census module access (original location)
from socialmapper.census import get_neighboring_states
neighbors = get_neighboring_states('37')

Enhanced Geographic Functions

• get_geography_from_point() - Complete geographic hierarchy for any point
• get_counties_from_pois() - Optimized batch POI processing with neighbor inclusion
• get_neighbor_statistics() - System performance and coverage statistics

Intelligent Caching

• Point-to-geography lookups cached for instant repeat access
• Automatic cache management with configurable limits
• Cross-session persistence for improved performance

---

🔧 Technical Improvements

Database Architecture

• Dedicated neighbor database: Separate from census data for optimal performance
• Spatial optimization: DuckDB spatial extension for efficient geographic queries
• Pre-computed relationships: All US state and county neighbors included

Package Distribution

• Self-contained: No external downloads or setup required
• Immediate functionality: Works out-of-the-box with pre-computed data
• Optimized packaging: Efficient data compression and distribution

---

📊 Benchmark Results

Operation	Before	After	Improvement
State neighbor lookup	~500ms	~0.3ms	1,667x faster
Point geocoding (cached)	~769ms	~0.8ms	961x faster
POI batch processing (100 POIs)	~106s	~0.02s	5,300x faster
County neighbor lookup	~30s	~1ms	30,000x faster

---

New (optimized):

from socialmapper.census import get_neighboring_states, get_neighboring_counties, get_counties_from_pois
# OR
import socialmapper
neighbors = socialmapper.get_neighboring_states('06')

---

📦 Installation & Upgrade

# Install new version
pip install socialmapper==0.4.2b0

# Or upgrade from previous version
pip install --upgrade socialmapper

Requirements: No additional dependencies required. The optimized neighbor database is included in the package.

---

🔍 What's Next

Upcoming Features (v0.4.3+)

• Tract and block group neighbor relationships
• Enhanced spatial analysis capabilities
• Additional geographic utility functions
• Performance monitoring and analytics

Long-term Roadmap

• Natural environment connectivity analysis
• Advanced spatial relationship modeling
• Machine learning-powered geographic insights

---

📞 Support

• Documentation: GitHub Repository
• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Full Changelog: v0.4.1-beta...v0.4.2-beta

v0.4.0-beta

We are excited to announce the beta release of SocialMapper! This release marks a significant milestone as we transition from alpha to beta, introducing several new features and improvements.

New Features

1. Streamlit App Availability

   • The socialmapper.streamlit.app is now live! You can use it without needing to code in Python, making SocialMapper more accessible to all users.

2. Interactive Maps with Folium

   • Added Folium interactive maps to the Streamlit app for a more engaging visualization experience.

3. Distance Traveled Export

   • Functionality to export distance traveled has been added, providing greater flexibility in data analysis.

4. Export to CSV

   • You can now export data directly to CSV format, simplifying data sharing and record-keeping.

Enhancements

5. Runtime Optimizations

   • Significant optimizations have been implemented to improve the app's runtime performance.

6. Python Package on PyPI

   • SocialMapper is now available as a proper Python package on PyPI. Install it easily using pip install socialmapper.

v0.3.0-alpha

Changelog: Streamlit Integration and Major Enhancements

Streamlit App Integration

• Added Streamlit Web App: Introduced a new Streamlit-based web application (Home.py) for Community Mapper, providing an interactive and user-friendly interface for community mapping workflows.
• Enhanced User Experience: The Streamlit app allows users to configure, run, and visualize community mapping analyses directly from the browser, streamlining the workflow for both technical and non-technical users.

New Progress Tracking Functionality

• Integrated stqdm for Progress Tracking: Added the stqdm library to provide real-time progress bars and feedback during long-running analyses, such as census data fetching and POI processing.
• Improved User Feedback: Progress tracking is now visible both in the command-line interface and within the Streamlit app, making it easier to monitor the status of data processing tasks.

Block Group Fetching: State to County Transition

• Refactored Block Group Fetching: Changed the logic for fetching census block groups from a state-based approach to a county-based approach, significantly improving performance and accuracy.
• County-Based Selection: Users can now select and analyze block groups at the county level, enabling more granular and relevant community analyses.
• Optimized Data Handling: The new approach reduces unnecessary data fetching and processing, resulting in faster and more efficient analyses.

---

These enhancements mark a major step forward in the usability, performance, and flexibility of the Community Mapper project. The addition of the Streamlit app, improved progress tracking, and the shift to county-based block group selection collectively provide a more robust and user-friendly experience for all users.