Skip to content

Commit 99a1a60

Browse files
afarberafarber
committed
Add more map types
1 parent cb61fee commit 99a1a60

12 files changed

Lines changed: 1370 additions & 513 deletions

File tree

‎docs/MAP_TYPES.md‎

Lines changed: 352 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,352 @@
1+
# Map Types Guide for OpenMapView
2+
3+
This guide helps you choose and configure the right map type for your OpenMapView application.
4+
5+
## Quick Start
6+
7+
OpenMapView provides **10 map types** matching the OpenStreetMap.org layer switcher. Six types work without any configuration, while four premium types require free API keys.
8+
9+
```kotlin
10+
val mapView = OpenMapView(context)
11+
mapView.setMapType(MapType.STANDARD) // Default map
12+
mapView.setMapType(MapType.CYCLOSM) // Cycling infrastructure
13+
mapView.setMapType(MapType.HUMANITARIAN) // Emergency response
14+
```
15+
16+
## Available Map Types
17+
18+
### Free Map Types (No API Key Required)
19+
20+
#### 1. STANDARD - Default OpenStreetMap
21+
**`MapType.STANDARD`** (constant value: 1)
22+
23+
The classic OpenStreetMap Mapnik rendering style.
24+
25+
- **Best for**: General purpose mapping, navigation, POI display
26+
- **Features**: Roads, buildings, land use, water features, comprehensive labels
27+
- **Tile Server**: tile.openstreetmap.org
28+
- **Max Zoom**: 19
29+
- **Attribution**: © OpenStreetMap contributors
30+
31+
```kotlin
32+
mapView.setMapType(MapType.STANDARD)
33+
```
34+
35+
#### 2. CYCLOSM - Free Cycling Map
36+
**`MapType.CYCLOSM`** (constant value: 2)
37+
38+
French OpenStreetMap cycling infrastructure map.
39+
40+
- **Best for**: Cycling apps, route planning, bikeshare applications
41+
- **Features**: Bike lanes, paths, parking, shops, difficulty ratings
42+
- **Highlights**: Clear colors to distinguish cycleway types
43+
- **Tile Server**: tile-cyclosm.openstreetmap.fr
44+
- **Max Zoom**: 20
45+
- **Attribution**: © OpenStreetMap contributors. Tiles courtesy of OpenStreetMap France
46+
47+
```kotlin
48+
mapView.setMapType(MapType.CYCLOSM)
49+
```
50+
51+
#### 3. HUMANITARIAN - Emergency Response
52+
**`MapType.HUMANITARIAN`** (constant value: 6)
53+
54+
Humanitarian OpenStreetMap Team (HOT) style with red/orange color scheme.
55+
56+
- **Best for**: Emergency response, disaster management, humanitarian aid
57+
- **Features**: Hospitals, schools, water sources, emergency services
58+
- **Highlights**: Infrastructure critical for disaster response
59+
- **Tile Server**: tile.openstreetmap.fr/hot
60+
- **Max Zoom**: 20
61+
- **Attribution**: © OpenStreetMap contributors. Tiles courtesy of Humanitarian OpenStreetMap Team
62+
63+
```kotlin
64+
mapView.setMapType(MapType.HUMANITARIAN)
65+
```
66+
67+
#### 4. OPNVKARTE - German Public Transport
68+
**`MapType.OPNVKARTE`** (constant value: 7)
69+
70+
Detailed public transport map focusing on German transit networks.
71+
72+
- **Best for**: German transit apps, ÖPNV journey planning
73+
- **Features**: Bus, tram, subway, train routes with high detail
74+
- **Highlights**: Comprehensive German public transportation coverage
75+
- **Tile Server**: tileserver.memomaps.de (MeMoMaps)
76+
- **Max Zoom**: 18
77+
- **Attribution**: © OpenStreetMap contributors. Tiles courtesy of MeMoMaps
78+
79+
```kotlin
80+
mapView.setMapType(MapType.OPNVKARTE)
81+
```
82+
83+
#### 5. NONE - No Base Tiles
84+
**`MapType.NONE`** (constant value: 0)
85+
86+
No base map tiles displayed (useful for custom tile sources or offline maps).
87+
88+
```kotlin
89+
mapView.setMapType(MapType.NONE)
90+
```
91+
92+
### Premium Map Types (API Key Required)
93+
94+
These map types require free API keys from third-party tile providers. When an API key is missing, OpenMapView automatically:
95+
- Falls back to STANDARD map tiles
96+
- Displays a translucent overlay with an error message
97+
- Keeps the map fully interactive (pan, zoom still work)
98+
- Logs a warning to help with debugging
99+
100+
#### 6. CYCLEMAP - Professional Cycling Map
101+
**`MapType.CYCLEMAP`** (constant value: 3) 🔑 **Requires Thunderforest API Key**
102+
103+
Professional cycling map with elevation contours and comprehensive infrastructure.
104+
105+
- **Best for**: Premium cycling apps, detailed route planning
106+
- **Features**: Elevation contours, cycle routes, comprehensive cycling infrastructure
107+
- **Quality**: Higher quality than CyclOSM
108+
- **Tile Server**: tile.thunderforest.com
109+
- **Max Zoom**: 21
110+
- **Free Tier**: 150,000 tiles/month
111+
- **Get API Key**: https://www.thunderforest.com/pricing/
112+
- **Attribution**: © OpenStreetMap contributors. Tiles courtesy of Andy Allan
113+
114+
```kotlin
115+
// Configure in AndroidManifest.xml:
116+
<meta-data
117+
android:name="de.afarber.openmapview.THUNDERFOREST_API_KEY"
118+
android:value="your_key_here"/>
119+
120+
// Or programmatically:
121+
ApiKeyManager.setApiKey("thunderforest", "your_key_here")
122+
123+
mapView.setMapType(MapType.CYCLEMAP)
124+
```
125+
126+
#### 7. TRANSPORT - Public Transit Map
127+
**`MapType.TRANSPORT`** (constant value: 4) 🔑 **Requires Thunderforest API Key**
128+
129+
Public transport focused map with comprehensive transit information.
130+
131+
- **Best for**: Public transit apps, journey planning, transportation analysis
132+
- **Features**: Bus routes, train lines, tram tracks, transit stations
133+
- **Highlights**: Emphasizes public transportation infrastructure
134+
- **Tile Server**: tile.thunderforest.com
135+
- **Max Zoom**: 21
136+
- **Free Tier**: 150,000 tiles/month
137+
- **Get API Key**: https://www.thunderforest.com/pricing/
138+
- **Attribution**: © OpenStreetMap contributors. Tiles courtesy of Andy Allan
139+
140+
```kotlin
141+
// Same API key as CYCLEMAP
142+
mapView.setMapType(MapType.TRANSPORT)
143+
```
144+
145+
#### 8. TRACESTRACK_TOPO - Topographic Map
146+
**`MapType.TRACESTRACK_TOPO`** (constant value: 5) 🔑 **Requires Tracestrack API Key**
147+
148+
Detailed topographic map with elevation contours and hillshading.
149+
150+
- **Best for**: Hiking apps, outdoor navigation, elevation analysis
151+
- **Features**: Elevation contours, hillshading, terrain features
152+
- **Highlights**: Excellent for outdoor activities
153+
- **Tile Server**: tile.tracestrack.com
154+
- **Max Zoom**: 19
155+
- **Free Tier**: 100,000 tiles/month
156+
- **Get API Key**: https://www.tracestrack.com/en/signup
157+
- **Attribution**: © OpenStreetMap contributors. Tiles courtesy of Tracestrack Maps
158+
159+
```kotlin
160+
// Configure in AndroidManifest.xml:
161+
<meta-data
162+
android:name="de.afarber.openmapview.TRACESTRACK_API_KEY"
163+
android:value="your_key_here"/>
164+
165+
// Or programmatically:
166+
ApiKeyManager.setApiKey("tracestrack", "your_key_here")
167+
168+
mapView.setMapType(MapType.TRACESTRACK_TOPO)
169+
```
170+
171+
#### 9. MAPTILER_OMT - OpenMapTiles Vector Style
172+
**`MapType.MAPTILER_OMT`** (constant value: 9) 🔑🚧 **Coming Soon**
173+
174+
High-quality vector tile map based on OpenMapTiles schema.
175+
176+
- **Status**: Not yet supported - requires MapLibre GL integration
177+
- **When Available**: Smooth rendering, client-side styling, excellent performance
178+
- **Get API Key**: https://www.maptiler.com/cloud/plans/
179+
- **Free Tier**: 100,000 tiles/month
180+
181+
### Vector Tile Support (Coming Soon)
182+
183+
#### 10. SHORTBREAD - Modern Vector Style
184+
**`MapType.SHORTBREAD`** (constant value: 8) 🚧 **Coming Soon**
185+
186+
Modern, clean vector-based map style.
187+
188+
- **Status**: Not yet supported - requires MapLibre GL integration
189+
- **When Available**: Smooth rendering, customizable styling
190+
- **No API Key Required**
191+
192+
## API Key Configuration
193+
194+
### Method 1: AndroidManifest.xml (Recommended)
195+
196+
Add API keys to your app's `AndroidManifest.xml`:
197+
198+
```xml
199+
<application>
200+
<!-- Thunderforest (for CYCLEMAP and TRANSPORT) -->
201+
<meta-data
202+
android:name="de.afarber.openmapview.THUNDERFOREST_API_KEY"
203+
android:value="your_thunderforest_key_here"/>
204+
205+
<!-- Tracestrack (for TRACESTRACK_TOPO) -->
206+
<meta-data
207+
android:name="de.afarber.openmapview.TRACESTRACK_API_KEY"
208+
android:value="your_tracestrack_key_here"/>
209+
210+
<!-- MapTiler (for MAPTILER_OMT - when supported) -->
211+
<meta-data
212+
android:name="de.afarber.openmapview.MAPTILER_API_KEY"
213+
android:value="your_maptiler_key_here"/>
214+
</application>
215+
```
216+
217+
### Method 2: Programmatically
218+
219+
Set API keys at runtime:
220+
221+
```kotlin
222+
import de.afarber.openmapview.ApiKeyManager
223+
224+
ApiKeyManager.setApiKey("thunderforest", "your_key_here")
225+
ApiKeyManager.setApiKey("tracestrack", "your_key_here")
226+
ApiKeyManager.setApiKey("maptiler", "your_key_here")
227+
```
228+
229+
### Obtaining API Keys
230+
231+
All providers offer generous free tiers suitable for development and small-scale production use:
232+
233+
#### Thunderforest (CYCLEMAP, TRANSPORT)
234+
- **Website**: https://www.thunderforest.com/pricing/
235+
- **Free Tier**: 150,000 tiles/month
236+
- **Sign Up**: Register for free account
237+
- **One key works for**: Both CYCLEMAP and TRANSPORT
238+
239+
#### Tracestrack (TRACESTRACK_TOPO)
240+
- **Website**: https://www.tracestrack.com/en/signup
241+
- **Free Tier**: 100,000 tiles/month
242+
- **Sign Up**: Register for free account
243+
244+
#### MapTiler (MAPTILER_OMT)
245+
- **Website**: https://www.maptiler.com/cloud/plans/
246+
- **Free Tier**: 100,000 tiles/month
247+
- **Sign Up**: Register for free account
248+
- **Note**: MAPTILER_OMT not yet supported (vector tiles)
249+
250+
### Security Best Practices
251+
252+
1. **Use Domain Restrictions**: Configure API keys on provider websites to restrict usage to your app's domain/bundle ID
253+
2. **Don't Commit Keys**: Add API keys to `local.properties` and inject via Gradle, don't commit to version control
254+
3. **Monitor Usage**: Set up usage alerts on provider dashboards to avoid unexpected charges
255+
4. **Rate Limiting**: Free tiers have monthly limits - monitor usage in provider dashboards
256+
257+
## Choosing the Right Map Type
258+
259+
### Use Case Guide
260+
261+
| Use Case | Recommended Map Type |
262+
|----------|---------------------|
263+
| General purpose app | `STANDARD` |
264+
| Cycling/bike app (free) | `CYCLOSM` |
265+
| Cycling/bike app (premium) | `CYCLEMAP` (requires API key) |
266+
| Public transit app | `TRANSPORT` (requires API key) |
267+
| German transit app | `OPNVKARTE` |
268+
| Hiking/outdoor app | `TRACESTRACK_TOPO` (requires API key) |
269+
| Emergency/humanitarian | `HUMANITARIAN` |
270+
| Custom tiles only | `NONE` |
271+
272+
### Performance Considerations
273+
274+
- **Free maps** (STANDARD, CYCLOSM, HUMANITARIAN, OPNVKARTE): No usage limits, best for production apps
275+
- **Premium maps** with API keys: Monitor monthly tile limits (free tiers: 100k-150k tiles/month)
276+
- **Tile caching**: OpenMapView automatically caches tiles in memory and on disk to minimize requests
277+
- **Subdomain rotation**: Maps with subdomain support (CYCLOSM, CYCLEMAP, TRANSPORT, HUMANITARIAN) automatically distribute load across multiple servers
278+
279+
## Tile Overlays (Additional Layers)
280+
281+
In addition to base map types, OpenMapView supports **tile overlays** that render on top of the base map:
282+
283+
- **OpenSeaMap**: Nautical charts (buoys, depth contours)
284+
- **OpenRailwayMap**: Railway infrastructure
285+
- **OpenFireMap**: Fire stations, hydrants
286+
- **OpenSnowMap**: Ski pistes, lifts
287+
- **Waymarked Trails**: Hiking, cycling, MTB, skating trails
288+
- **Stamen Overlays**: Labels, terrain lines
289+
290+
See `PredefinedTileProviders.kt` for predefined overlay sources, or create custom overlays using `TileOverlay` and `UrlTileProvider`.
291+
292+
**Key Difference**:
293+
- **Base maps** (MapType): Only one active at a time, full coverage
294+
- **Tile overlays** (TileOverlay): Multiple can layer, transparent, selective coverage
295+
296+
## Example Usage
297+
298+
See the **Example11MapTypes** sample app for a complete demonstration of all map types with:
299+
- Buttons to switch between all 10 map types
300+
- Visual indicators for API key requirements (🔑) and coming soon features (🚧)
301+
- Descriptions of each map type
302+
- Instructions for API key configuration
303+
304+
```kotlin
305+
// From Example11MapTypes:
306+
val mapView = OpenMapView(context)
307+
lifecycle.addObserver(mapView)
308+
mapView.setCenter(LatLng(46.8182, 8.2275))
309+
mapView.setZoom(12.0)
310+
mapView.setMapType(MapType.CYCLOSM) // Switch map types dynamically
311+
```
312+
313+
## Troubleshooting
314+
315+
### "API Key Required" Overlay Appears
316+
317+
**Symptom**: Translucent gray overlay with error message appears, STANDARD map tiles show underneath.
318+
319+
**Solutions**:
320+
1. Verify API key is configured in `AndroidManifest.xml` or via `ApiKeyManager`
321+
2. Check API key is correct (copy-paste from provider website)
322+
3. Ensure API key has correct permissions on provider website
323+
4. Check Logcat for detailed error messages (search for "OpenMapView")
324+
325+
### Map Shows Wrong Tiles
326+
327+
**Symptom**: Old tiles from previous map type still visible.
328+
329+
**Solution**: Tile cache is automatically cleared when changing map types. If issues persist, clear app data.
330+
331+
### Attribution Not Showing
332+
333+
**Symptom**: Attribution text not visible at bottom of map.
334+
335+
**Solution**: Attribution is automatically displayed by OpenMapView. Ensure you're not covering it with custom UI elements. Attribution is required by tile provider terms of service.
336+
337+
## Additional Resources
338+
339+
- **Source Code**: See `MapType.kt` and `TileSource.kt` for all map type definitions
340+
- **Example App**: `examples/Example11MapTypes` demonstrates all features
341+
- **Public API**: See `docs/PUBLIC_API.md` for complete API reference
342+
- **Tile Specifications**: All maps use 256×256 pixel tiles, Web Mercator projection (EPSG:3857)
343+
344+
## Future Enhancements
345+
346+
- **Vector Tile Support**: MapLibre GL integration for SHORTBREAD and MAPTILER_OMT (planned)
347+
- **Dark Mode Variants**: TransportDarkMap, ShortbreadEclipse (considering for future release)
348+
- **Additional Free Maps**: Evaluating other public tile sources
349+
350+
---
351+
352+
**Note**: OpenMapView is designed to be a drop-in replacement for Google MapView but uses free OpenStreetMap tiles. Most map types work without any API keys or registration - a key advantage over Google Maps SDK which requires API keys and billing setup for all usage.

0 commit comments

Comments
 (0)