Nigeria Map Tool

An interactive web-based map application for exploring Nigeria's administrative divisions using MapLibre GL and PMTiles for high-performance vector tile rendering.

🚀 v2.0 - Now with PMTiles! Migrated from Leaflet + GeoJSON to MapLibre GL + PMTiles for 10x faster performance. See migration guide

Features

• MapLibre GL Map: GPU-accelerated vector tile rendering
• PMTiles Integration: Stream geographic data on-demand (no large file downloads)
• Multi-level Filtering:
  • Filter by State, LGA, or Ward
  • Filter by Senatorial District
• Dynamic Search: Real-time search across all administrative levels
• Additional Layers:
  • 🏥 Health Facilities (clickable markers)
  • 🛣️ Road Network
  • 👥 Population Density Heatmap
• Layer Toggle: Show/hide boundary and feature layers
• Collapsible Sidebar: Responsive design with mobile support
• High Performance: 99.6% reduction in data transfer, 10x faster loading

File Structure

nigeria_map_tool/
├── index.html                # Main HTML entry point
├── package.json              # Project dependencies and metadata
├── README.md                 # This file
├── PMTILES_MIGRATION.md      # Migration guide from v1.x
│
├── js/                       # JavaScript modules
│   ├── main.js              # Application entry point (PMTiles version)
│   ├── MapManager.js        # MapLibre GL singleton manager
│   └── config.js            # Centralized configuration settings
│
├── data/                     # Data files
│   ├── senatorial.json      # Senatorial district mappings
│   ├── manualLgaCorrections.json  # LGA name normalization mappings
│   ├── ag_typologies.csv    # Agricultural typology classifications
│   └── ward_fields.json     # Ward field metadata
│
├── styles/
│   └── styles.css           # Application styles
│
├── js_backup/               # Backup of v1.x JavaScript
└── index.html.backup        # Backup of v1.x HTML

Prerequisites

• Modern Web Browser with WebGL support
  • Chrome 56+, Firefox 51+, Safari 11+, Edge 79+
• Python 3.x (for local development server)
• Internet Connection (for PMTiles streaming)

Setup and Installation

1. Clone the Repository

git clone https://github.com/femiolamijulo/nigeria_map_tool.git
cd nigeria_map_tool

2. Start a Local Development Server

Option A - Using Python:

python -m http.server 8000

Option B - Using npm:

npm start

Option C - Using Node.js http-server:

npx http-server -p 8000

3. Open in Browser

Navigate to: http://localhost:8000

The map will load PMTiles data from https://tiles.staygis.com

Usage Instructions

Filtering the Map

1. State Filter:

   • Select a State from the dropdown
   • Map highlights and zooms to the selected State
   • LGA and Senatorial District dropdowns populate automatically

2. Senatorial District Filter:

   • After selecting a State, choose a Senatorial District
   • Map highlights all LGAs within that district

3. LGA Filter:

   • Select a Local Government Area
   • Map highlights the LGA and populates Ward dropdown

4. Ward Filter:

   • Select a Ward to highlight and zoom to it

Search Functionality

• Type in the search box to find States, LGAs, or Wards
• Results appear instantly as you type
• Click any result to zoom to that location

Layer Toggles

Boundary Layers:

• States - State boundary outlines
• LGAs - Local Government Area boundaries
• Wards - Ward boundaries

Additional Layers:

• Health Facilities - Clickable health facility points
• Roads - Road network (vector)
• Population Density - Population heatmap (raster)

Reset

• Click "Reset Filters" to clear all selections and return to Nigeria overview

Technology Stack

Component	Technology	Version
Map Library	MapLibre GL JS	3.6.2
Tile Format	PMTiles	4.3.0
Tile Source	StayGIS	-
Data Format	Vector Tiles	-
Basemap	OpenStreetMap	-

Performance

v2.0 (PMTiles) vs v1.x (GeoJSON)

Metric	v1.x	v2.0	Improvement
Initial Load	~8s	~1s	8x faster
Data Transfer	~50MB	~180KB	99.6% reduction
State Selection	~200ms	~50ms	4x faster
Search	~300ms	~10ms	30x faster
Memory Usage	~200MB	~50MB	75% reduction

Data Sources

PMTiles Layers

All PMTiles are hosted at https://tiles.staygis.com:

Layer	File	Source Layer	Type
States	ng_states.pmtiles	grid3_nga_boundary_vaccstates	Vector
LGAs	ng_lgas.pmtiles	grid3_nga_boundary_vacclgas	Vector
Wards	ng_wards.pmtiles	grid3_nga_boundary_vaccwards	Vector
Health	ng_health_facilities.pmtiles	GRID3_NGA_health_facilities_v2_0	Vector
Roads	ng_roads.pmtiles	roads	Vector
Population	ng_pop_total.pmtiles	-	Raster

Data Credits

Admin boundary data from eHealth Africa and Proxy Logics. 2020. Nigeria Operational Ward Boundaries. Geo-Referenced Infrastructure and Demographic Data for Development (GRID3). https://grid3.gov.ng/

Tile hosting: StayGIS (https://tiles.staygis.com)

Customization

Map Configuration

Edit js/config.js to customize:

• Initial map center and zoom (map.center, map.zoom)
• Layer styles and colors (layerStyles)
• PMTiles base URL (BASE_URL)

Adding Custom Layers

// In MapManager.js, add to addOptionalLayers()
this.map.addSource('custom', {
  type: 'vector',
  url: `pmtiles://${this.config.BASE_URL}/custom.pmtiles`
});

this.map.addLayer({
  id: 'custom-layer',
  type: 'fill',
  source: 'custom',
  'source-layer': 'layer_name',
  paint: {
    'fill-color': '#ff0000',
    'fill-opacity': 0.5
  }
});

Troubleshooting

Common Issues

1. Map Not Displaying

   • Ensure you're using a WebGL-capable browser
   • Check browser console for errors (F12)
   • Verify internet connection for PMTiles loading

2. "Failed to load map" Error

   • Check if https://tiles.staygis.com is accessible
   • Verify local web server is running
   • Check browser developer console for details

3. Layers Not Appearing

   • PMTiles may be loading - wait a few seconds
   • Check layer toggles are enabled
   • Zoom to appropriate level (some layers are zoom-dependent)

4. Slow Performance

   • Clear browser cache
   • Disable unnecessary layers
   • Check internet connection speed

5. Search Not Working

   • Wait for map to finish loading (spinner should disappear)
   • Features are cached on map.idle event
   • Try zooming in to load more features

Migration from v1.x

If you're upgrading from the Leaflet/GeoJSON version, see the PMTiles Migration Guide for:

• Detailed architecture changes
• API differences
• Rollback instructions
• Performance comparison

Quick Rollback:

cp index.html.backup index.html
rm -rf js/
cp -r js_backup/ js/

Development

Adding New Features

1. Create feature branch: git checkout -b feature-name
2. Make changes and test locally
3. Ensure no console errors
4. Submit pull request

Code Style

• Use ES6 modules
• Follow existing naming conventions
• Add comments for complex logic
• Keep console logs minimal

Dependencies

Runtime Dependencies (CDN)

• MapLibre GL JS v3.6.2 - Map rendering library
• PMTiles v4.3.0 - Tile format protocol

Development Dependencies

• Python 3.x (HTTP server) or Node.js (http-server)

Contributing

Contributions welcome! Please:

• Open an issue to discuss major changes
• Follow the existing code structure
• Test thoroughly with all layer combinations
• Update documentation as needed

License

This project is licensed under the MIT License.

Contact

Olufemi Olamijulo

• Email: lamijulo99@gmail.com
• GitHub: @femiolamijulo

---

Version: 2.0.0 Last Updated: 2025-10-08 Status: ✅ Production Ready