🗺️ OSRM Map Data Setup


An interactive, user-friendly bash script to download and process OpenStreetMap data for OSRM (Open Source Routing Machine) routing services.

Perfect for developers building route optimization, navigation apps, logistics platforms, or any application requiring offline routing capabilities.

---

✨ Features

- 🌍 Global Coverage - Access 180+ countries across all continents
- 🎨 Beautiful Interactive UI - Intuitive menu system with color-coded navigation
- 🚀 Parallel Downloads - Download multiple regions simultaneously
- 🔄 Auto-Retry Logic - Robust download handling with exponential backoff
- ⚙️ Automated Processing - Automatic OSRM graph extraction, partitioning, and customization
- 🏥 Health Checks - Built-in verification to ensure routing service is ready
- 📊 Progress Tracking - Real-time feedback on download and processing status
- 🐳 Docker-Ready - Seamless integration with Docker-based OSRM deployments
- 💾 Resume Support - Continue interrupted downloads automatically

---

🎯 Use Cases

- Route Optimization - Build logistics and delivery route planning systems
- Navigation Apps - Create offline-capable navigation applications
- Geospatial Analysis - Analyze road networks and accessibility
- Location Services - Develop location-based services with routing
- Research Projects - Academic research on transportation and urban planning
- Ride-Sharing Platforms - Calculate optimal routes for drivers
- Fleet Management - Optimize vehicle routing for fleet operations

---

🚀 Quick Start

$3

- Bash 5.0+ (comes pre-installed on macOS and most Linux distributions)
- Docker - Install Docker
- curl or wget - For downloading map data
- Disk Space - Varies by region (10GB - 100GB+ for large countries/continents)

$3

#### Option 1: NPM (Recommended)

``bash


Install globally

npm install -g osrm-map-data-setup

Run the interactive menu

osrm-setup

Or with arguments

osrm-setup germany --profile car
`

#### Option 2: Clone Repository

`bash


Clone the repository

git clone https://github.com/mahdialavitabar/osrm-map-data-setup.git
cd osrm-map-data-setup

Make the script executable

chmod +x setup-osrm.sh

Run the interactive menu

./setup-osrm.sh
`

#### Option 3: Programmatic API (Node.js)

`javascript
const osrm = require('osrm-map-data-setup');

// Download and process Germany
await osrm.setup({
regions: ['germany'],
dir: './osrm-data',
profile: 'car',
});

// Download only (no processing)
await osrm.download(['france', 'spain'], './osrm-data');

// Process existing files only
await osrm.process(['germany'], { profile: 'bicycle' });

// Check dependencies
const deps = osrm.checkDependencies();
console.log(deps); // { bash: true, docker: true, curl: true, wget: false }
`

$3

#### Interactive Mode (Recommended)

Simply run the script without arguments to launch the interactive menu:

`bash
./setup-osrm.sh
`

Navigate through the beautiful menu to:

1. Select a continent
2. Choose specific countries or download entire regions
3. Add multiple selections
4. Download and process automatically

#### Command-Line Mode

For automation, scripts, or CI/CD pipelines:

`bash


Single country

./setup-osrm.sh iran

Multiple countries

./setup-osrm.sh germany france spain

Entire continent

./setup-osrm.sh europe

Mix and match

./setup-osrm.sh japan south-korea europe/monaco us-west

Custom Geofabrik paths

./setup-osrm.sh europe/germany/berlin
`

---

📖 How It Works

$3

The script downloads .osm.pbf (Protocolbuffer Binary Format) files from Geofabrik, a reliable source for OpenStreetMap extracts.

$3

Using Docker containers, the script processes the raw OSM data through three OSRM stages:

- Extract - Converts OSM data to routing graph
- Partition - Optimizes graph structure for fast queries
- Customize - Applies routing profiles (e.g., car, bike, foot)

$3

Renames processed files to the standard map.osrm format for Docker Compose integration.

$3

Validates the routing service by performing test route calculations.

---

📁 Project Structure

`
osrm-map-data-setup/
├── setup-osrm.sh # Main setup script
├── README.md # This file
├── LICENSE # MIT License
├── CONTRIBUTING.md # Contribution guidelines
├── .gitignore # Git ignore patterns
├── examples/
│ ├── docker-compose.yml # Example Docker Compose configuration
│ └── api-usage.md # OSRM API usage examples
└── osrm/ # Output directory (created by script)
├── map.osrm* # Processed routing data
└── downloads/ # Downloaded .osm.pbf files
`

---

🌍 Supported Regions

$3

- 🌍 Africa (58 countries)
- 🧊 Antarctica (whole continent)
- 🌏 Asia (37 countries)
- 🦘 Australia & Oceania (5 countries)
- 🌴 Central America (6 countries)
- 🏰 Europe (49 countries)
- 🗽 North America (9 regions)
- 🐻 Russia (whole country)
- 🌎 South America (11 countries)

📋 View Full Country List

#### Africa

algeria, angola, benin, botswana, burkina-faso, burundi, cameroon, canary-islands, cape-verde, central-african-republic, chad, comores, congo-brazzaville, congo-democratic-republic, djibouti, egypt, equatorial-guinea, eritrea, ethiopia, gabon, gambia, ghana, guinea, guinea-bissau, ivory-coast, kenya, lesotho, liberia, libya, madagascar, malawi, mali, mauritania, mauritius, morocco, mozambique, namibia, niger, nigeria, reunion, rwanda, saint-helena-ascension-and-tristan-da-cunha, sao-tome-and-principe, senegal, seychelles, sierra-leone, somalia, south-africa, south-sudan, sudan, swaziland, tanzania, togo, tunisia, uganda, zambia, zimbabwe

#### Asia

afghanistan, armenia, azerbaijan, bangladesh, bhutan, cambodia, china, gcc-states, india, indonesia, iran, iraq, israel-and-palestine, japan, jordan, kazakhstan, kyrgyzstan, laos, lebanon, malaysia-singapore-brunei, maldives, mongolia, myanmar, nepal, north-korea, pakistan, philippines, south-korea, sri-lanka, syria, taiwan, tajikistan, thailand, turkmenistan, uzbekistan, vietnam, yemen

#### Australia & Oceania

australia, fiji, new-caledonia, new-zealand, papua-new-guinea

#### Central America

belize, cuba, guatemala, haiti-and-domrep, jamaica, nicaragua

#### Europe

albania, andorra, austria, azores, belarus, belgium, bosnia-herzegovina, bulgaria, croatia, cyprus, czech-republic, denmark, estonia, faroe-islands, finland, france, georgia, germany, great-britain, greece, hungary, iceland, ireland-and-northern-ireland, isle-of-man, italy, kosovo, latvia, liechtenstein, lithuania, luxembourg, macedonia, malta, moldova, monaco, montenegro, netherlands, norway, poland, portugal, romania, serbia, slovakia, slovenia, spain, sweden, switzerland, turkey, ukraine

#### North America

canada, greenland, mexico, us, us-midwest, us-northeast, us-pacific, us-south, us-west

#### South America

argentina, bolivia, brazil, chile, colombia, ecuador, paraguay, peru, suriname, uruguay, venezuela

---

🐳 Docker Integration

$3

Create a docker-compose.yml file:

`yaml
version: '3.8'

services:
osrm:
image: osrm/osrm-backend
container_name: osrm-routing
ports:
- '5000:5000'
volumes:
- ./osrm:/data
command: osrm-routed --algorithm mld /data/map.osrm
restart: unless-stopped
`

$3

`bash


After running setup-osrm.sh

docker-compose up -d

Test the routing API

curl 'http://localhost:5000/route/v1/driving/13.388860,52.517037;13.397634,52.529407?overview=false'
`

---

🔧 Configuration

$3

Customize behavior by setting these variables before running the script:

`bash


Maximum download retry attempts (default: 3)

export MAX_RETRIES=5

Initial retry delay in seconds (default: 5)

export RETRY_DELAY=10

Custom output directory (default: ./osrm)

export OSRM_DIR="/path/to/custom/directory"
`

$3

`bash


Process only, skip download (if you already have .osm.pbf files)

SKIP_DOWNLOAD=1 ./setup-osrm.sh iran

Specify custom OSRM profile

OSRM_PROFILE=bicycle ./setup-osrm.sh netherlands
`

---

📊 Disk Space Requirements

Approximate disk space needed (varies by region density):

| Region Type | Raw OSM Data | Processed OSRM | Total |
| -------------- | ------------ | -------------- | ---------- |
| Small Country | 50-200 MB | 100-500 MB | 150-700 MB |
| Medium Country | 200-1 GB | 500 MB-2 GB | 1-3 GB |
| Large Country | 1-5 GB | 2-10 GB | 5-15 GB |
| Continent | 5-30 GB | 10-60 GB | 20-100 GB |

Examples:

- Monaco: ~20 MB total
- Germany: ~3 GB total
- USA: ~15 GB total
- Europe: ~50 GB total
- Planet: ~100+ GB total

---

🧪 Testing the Setup

After successful setup, test your OSRM instance:

$3

`bash


Replace coordinates with locations within your map region


curl 'http://localhost:5000/route/v1/driving/LON1,LAT1;LON2,LAT2?overview=false'
`

$3

`bash
curl 'http://localhost:5000/table/v1/driving/LON1,LAT1;LON2,LAT2;LON3,LAT3'
`

$3

`bash
curl 'http://localhost:5000/nearest/v1/driving/LON,LAT'
`

See OSRM API Documentation for complete API reference.

---

🐛 Troubleshooting

$3

Issue: Network timeouts or failed downloads

`bash


Increase retry attempts


export MAX_RETRIES=10
./setup-osrm.sh iran
`

$3

Issue: Docker socket permission errors

`bash


Add user to docker group

sudo usermod -aG docker $USER

Log out and back in

`

$3

Issue: Insufficient space for large regions

`bash


Check available space

df -h

Clean Docker cache

docker system prune -a

Use external drive

export OSRM_DIR="/Volumes/ExternalDrive/osrm"
`

$3

Issue: Memory issues on large datasets

`bash


Increase Docker memory limit in Docker Desktop settings

Recommended: 4GB+ for large countries, 8GB+ for continents

`

$3

Issue: Test coordinates outside map area

- Ensure test coordinates are within the downloaded region
- Use coordinates from major cities in your region

---

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

$3

`bash


Fork the repository

git clone https://github.com/mahdialavitabar/osrm-map-data-setup.git
cd osrm-map-data-setup

Create a feature branch

git checkout -b feature/amazing-feature

Make your changes and test

./setup-osrm.sh

Commit and push

git commit -m "Add amazing feature"
git push origin feature/amazing-feature
``

---

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

- OpenStreetMap Contributors - For the incredible map data
- Geofabrik - For providing reliable OSM extracts
- Project OSRM - For the amazing routing engine
- OSRM Backend - For the Docker images and tools

---

🔗 Useful Links

- OSRM Documentation
- OpenStreetMap Wiki
- Geofabrik Download Server
- OSRM Demo

---

⭐ Support

If this project helped you, please consider:

- ⭐ Starring the repository
- 🐛 Reporting bugs and requesting features via Issues
- 🤝 Contributing improvements via Pull Requests
- 📢 Sharing with others who might find it useful

---