# OpenCivics Python Package
A comprehensive Python package for analyzing Australian geospatial data, including census data, OpenStreetMap features, and interactive map visualization.
## Features
### 🏛️ Census & ABS Data (`census` module)
- Download Australian Statistical Geography Standard (ASGS) boundary files
- Load and process Suburbs and Localities (SAL) and Local Government Areas (LGA) data
- Merge census data with geographical boundaries
- Calculate centroids for mapping applications
### 🗺️ Location Data Extraction
**PBF-based (`osm` module):**
- Extract features from large OSM PBF files using configurable tag rules
- Spatial analysis of amenities, services, and infrastructure
- Built-in feature configurations for Australian contexts
- Custom metrics calculation for urban analysis
**API-based (`api_extractor` module):**
- **OpenStreetMap Overpass API**: Free, no API key required
- **Google Maps Places API**: Commercial data with ratings and reviews
- No need to download large PBF files
- Automatic chunking for large areas
- Concurrent processing for faster extraction
- Same feature configuration system as PBF extraction
### 📊 Interactive Mapping (`mapping` module)
- Create interactive Folium maps with Australian city presets
- Multi-layer visualizations with custom styling
- Automated popup generation from analysis data
- City-specific zoom levels and bounds for major Australian cities
## Installation
```bash
pip install -e .
```
For development:
```bash
pip install -e ".[dev]"
```
## Quick Start
### Option 1: Using OpenStreetMap Overpass API (Free)
```python
import opencivics
# Download and load ABS boundary data
boundary_files = opencivics.download_aus_boundary_files("boundaries/")
boundaries = opencivics.load_abs_boundaries(boundary_files, "SAL", state_filter=["Victoria"])
# Extract OSM features using Overpass API (no PBF file needed!)
analysis_result = opencivics.analyze_osm_features_api(
boundaries_gdf=boundaries,
area_code_col='area_code',
feature_config=opencivics.FEATURE_TAGS,
api_type="overpass", # Free OpenStreetMap data
max_workers=3
)
# Create an interactive map for Melbourne
map_config = {
'Schools': {'column': 'school_count', 'caption': 'Number of Schools', 'default': True},
'Retail': {'column': 'retail_count', 'caption': 'Retail Outlets'}
}
melbourne_map = opencivics.create_city_map(
analysis_result,
'Melbourne',
map_config,
output_filename='melbourne_analysis.html'
)
```
### Option 2: Using Google Maps API (Commercial)
```python
import opencivics
# Same boundary setup as above...
# Extract features using Google Maps API (requires API key)
analysis_result = opencivics.analyze_osm_features_api(
boundaries_gdf=boundaries,
area_code_col='area_code',
feature_config=opencivics.FEATURE_TAGS,
api_type="google",
google_api_key="YOUR_GOOGLE_API_KEY",
max_workers=2 # Be conservative with commercial API
)
# Same mapping code as above...
```
### Option 3: Using PBF Files (For large-scale analysis)
```python
import opencivics
# Download and load ABS boundary data
boundary_files = opencivics.download_aus_boundary_files("boundaries/")
boundaries = opencivics.load_abs_boundaries(boundary_files, "SAL", state_filter=["Victoria"])
# Extract OSM features from PBF file
analysis_result = opencivics.analyze_osm_features(
boundaries, "australia.osm.pbf", "area_code", opencivics.FEATURE_TAGS
)
# Same mapping code as above...
```
## Supported Australian Cities
The package includes predefined configurations for:
- Sydney, Melbourne, Brisbane, Perth, Adelaide
- Canberra, Darwin, Hobart
- Gold Coast, Newcastle, Wollongong, Geelong, Townsville, Cairns
## Dependencies
- pandas, geopandas, shapely
- requests (for downloading ABS data)
- folium, branca (for interactive maps)
- osmium (for OSM data processing)
- numpy, openpyxl
## License
MIT License - see LICENSE file for details.
## Contributing
Contributions welcome! Please read our contributing guidelines and submit pull requests.
Raw data
{
"_id": null,
"home_page": null,
"name": "opencivics",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "geospatial, australia, census, openstreetmap, mapping, civic",
"author": "Alexander Tashevski",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/72/bd/b823a804bc3976d9c6f4abb7d51cec54720e00351986a407b16244cc6b22/opencivics-0.3.1.tar.gz",
"platform": null,
"description": "# OpenCivics Python Package\n\nA comprehensive Python package for analyzing Australian geospatial data, including census data, OpenStreetMap features, and interactive map visualization.\n\n## Features\n\n### \ud83c\udfdb\ufe0f Census & ABS Data (`census` module)\n- Download Australian Statistical Geography Standard (ASGS) boundary files\n- Load and process Suburbs and Localities (SAL) and Local Government Areas (LGA) data\n- Merge census data with geographical boundaries\n- Calculate centroids for mapping applications\n\n### \ud83d\uddfa\ufe0f Location Data Extraction \n**PBF-based (`osm` module):**\n- Extract features from large OSM PBF files using configurable tag rules\n- Spatial analysis of amenities, services, and infrastructure\n- Built-in feature configurations for Australian contexts\n- Custom metrics calculation for urban analysis\n\n**API-based (`api_extractor` module):**\n- **OpenStreetMap Overpass API**: Free, no API key required\n- **Google Maps Places API**: Commercial data with ratings and reviews\n- No need to download large PBF files\n- Automatic chunking for large areas\n- Concurrent processing for faster extraction\n- Same feature configuration system as PBF extraction\n\n### \ud83d\udcca Interactive Mapping (`mapping` module)\n- Create interactive Folium maps with Australian city presets\n- Multi-layer visualizations with custom styling\n- Automated popup generation from analysis data\n- City-specific zoom levels and bounds for major Australian cities\n\n## Installation\n\n```bash\npip install -e .\n```\n\nFor development:\n```bash\npip install -e \".[dev]\"\n```\n\n## Quick Start\n\n### Option 1: Using OpenStreetMap Overpass API (Free)\n\n```python\nimport opencivics\n\n# Download and load ABS boundary data\nboundary_files = opencivics.download_aus_boundary_files(\"boundaries/\")\nboundaries = opencivics.load_abs_boundaries(boundary_files, \"SAL\", state_filter=[\"Victoria\"])\n\n# Extract OSM features using Overpass API (no PBF file needed!)\nanalysis_result = opencivics.analyze_osm_features_api(\n boundaries_gdf=boundaries,\n area_code_col='area_code',\n feature_config=opencivics.FEATURE_TAGS,\n api_type=\"overpass\", # Free OpenStreetMap data\n max_workers=3\n)\n\n# Create an interactive map for Melbourne\nmap_config = {\n 'Schools': {'column': 'school_count', 'caption': 'Number of Schools', 'default': True},\n 'Retail': {'column': 'retail_count', 'caption': 'Retail Outlets'}\n}\n\nmelbourne_map = opencivics.create_city_map(\n analysis_result, \n 'Melbourne', \n map_config, \n output_filename='melbourne_analysis.html'\n)\n```\n\n### Option 2: Using Google Maps API (Commercial)\n\n```python\nimport opencivics\n\n# Same boundary setup as above...\n\n# Extract features using Google Maps API (requires API key)\nanalysis_result = opencivics.analyze_osm_features_api(\n boundaries_gdf=boundaries,\n area_code_col='area_code',\n feature_config=opencivics.FEATURE_TAGS,\n api_type=\"google\",\n google_api_key=\"YOUR_GOOGLE_API_KEY\",\n max_workers=2 # Be conservative with commercial API\n)\n\n# Same mapping code as above...\n```\n\n### Option 3: Using PBF Files (For large-scale analysis)\n\n```python\nimport opencivics\n\n# Download and load ABS boundary data\nboundary_files = opencivics.download_aus_boundary_files(\"boundaries/\")\nboundaries = opencivics.load_abs_boundaries(boundary_files, \"SAL\", state_filter=[\"Victoria\"])\n\n# Extract OSM features from PBF file\nanalysis_result = opencivics.analyze_osm_features(\n boundaries, \"australia.osm.pbf\", \"area_code\", opencivics.FEATURE_TAGS\n)\n\n# Same mapping code as above...\n```\n\n## Supported Australian Cities\n\nThe package includes predefined configurations for:\n- Sydney, Melbourne, Brisbane, Perth, Adelaide\n- Canberra, Darwin, Hobart\n- Gold Coast, Newcastle, Wollongong, Geelong, Townsville, Cairns\n\n## Dependencies\n\n- pandas, geopandas, shapely\n- requests (for downloading ABS data)\n- folium, branca (for interactive maps)\n- osmium (for OSM data processing)\n- numpy, openpyxl\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Contributing\n\nContributions welcome! Please read our contributing guidelines and submit pull requests.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A comprehensive package for analyzing Australian geospatial data with PBF, OpenStreetMap Overpass API, and Google Maps API support",
"version": "0.3.1",
"project_urls": {
"Documentation": "https://opencivics.readthedocs.io",
"Homepage": "https://github.com/opencivics/opencivics-package",
"Issues": "https://github.com/opencivics/opencivics-package/issues",
"Repository": "https://github.com/opencivics/opencivics-package"
},
"split_keywords": [
"geospatial",
" australia",
" census",
" openstreetmap",
" mapping",
" civic"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "df98136879a36989fff4bcaa171da65c6dc8cc03b5afba09f85910e752e35969",
"md5": "33be11154d5da650eedb05a92f597c51",
"sha256": "c53d59d308620bb67211831fe12079ba805383cdeb8ff98686a831c7df14401a"
},
"downloads": -1,
"filename": "opencivics-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "33be11154d5da650eedb05a92f597c51",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 24338,
"upload_time": "2025-07-15T03:19:09",
"upload_time_iso_8601": "2025-07-15T03:19:09.042191Z",
"url": "https://files.pythonhosted.org/packages/df/98/136879a36989fff4bcaa171da65c6dc8cc03b5afba09f85910e752e35969/opencivics-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "72bdb823a804bc3976d9c6f4abb7d51cec54720e00351986a407b16244cc6b22",
"md5": "44496ded02e9fc09d66e8f836fe9374f",
"sha256": "9c00731b0c9e48c5a0b5a9df24330babf71fb3e98ea1df77bd18b847e86dcb05"
},
"downloads": -1,
"filename": "opencivics-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "44496ded02e9fc09d66e8f836fe9374f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 24697,
"upload_time": "2025-07-15T03:19:10",
"upload_time_iso_8601": "2025-07-15T03:19:10.511053Z",
"url": "https://files.pythonhosted.org/packages/72/bd/b823a804bc3976d9c6f4abb7d51cec54720e00351986a407b16244cc6b22/opencivics-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-15 03:19:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "opencivics",
"github_project": "opencivics-package",
"github_not_found": true,
"lcname": "opencivics"
}
JSON
