# Mapy.com Developer Documentation
## Introduction
Mapy.com provides a comprehensive suite of mapping and location services through REST APIs, URL schemes, and JavaScript components. This platform enables developers to integrate map tiles, geocoding, routing, elevation data, panoramic imagery, and timezone information into web, mobile, and desktop applications. The service covers primarily Czech Republic and Central Europe with high-accuracy data from lidar-based elevation models and extensive street-level panoramic imagery captured during 2021-2023.
All REST API functions require an API key obtained through a free registration process at developer.mapy.com. The platform uses a credit-based pricing model with free credits included in both Basic and Extended tariffs. URL schemes for map display, search, and routing are freely available without API keys and automatically open in the Mapy.com mobile app when available. The JavaScript Panorama component provides interactive 360° views with efficient tile-based loading that only downloads visible portions of the panoramic imagery.
## API Authentication
### Getting an API Key
Obtain free API access by registering with your Seznam account and creating a project in the developer portal.
```bash
# Step 1: Visit the My Account portal
https://developer.mapy.com/account/
# Step 2: Log in with your Seznam account email
# Step 3: Create a new API project for your application
# Step 4: Your first API key is automatically created
# Test your API key with a simple geocoding request
curl "https://api.mapy.com/v1/geocode?apikey=YOUR_API_KEY&query=Prague"
```
## Map Tiles API
### Get Raster Map Tiles
Retrieve individual map tiles for integration with Leaflet, MapLibre GL JS, or other mapping libraries.
```bash
# Get a basic map tile for Prague area (zoom 14, coordinates 8956/5513)
curl "https://api.mapy.com/v1/maptiles/basic/256/14/8956/5513?apikey=YOUR_API_KEY" \
--output tile.png
# Get high-resolution retina tile (2x)
curl "https://api.mapy.com/v1/maptiles/basic/256@2x/14/8956/5513?apikey=YOUR_API_KEY" \
--output tile_retina.png
# Get outdoor map tile for hiking
curl "https://api.mapy.com/v1/maptiles/outdoor/256/14/8956/5513?apikey=YOUR_API_KEY" \
--output tile_outdoor.png
```
### Leaflet Integration Example
Complete interactive map with Leaflet using Mapy.com tiles.
```html
Mapy.com with Leaflet
```
## Static Maps API
### Generate Static Map Images
Create static map images with markers, shapes, and custom styling without JavaScript.
```bash
# Simple map centered on Špindlerův Mlýn
curl "https://api.mapy.com/v1/static/map?lon=15.608&lat=50.725&zoom=16&width=300&height=200&mapset=outdoor&apikey=YOUR_API_KEY" \
--output map.png
# Map with red marker
curl "https://api.mapy.com/v1/static/map?lon=15.608&lat=50.725&zoom=16&width=400&height=300&markers=color:red;size:normal;label:A;15.608,50.725&apikey=YOUR_API_KEY" \
--output map_marker.png
# Map with multiple markers (auto-fit bounds)
curl "https://api.mapy.com/v1/static/map?width=500&height=400&markers=color:red;label:A;15.6051,50.7270&markers=color:green;label:B;15.6111,50.7230&markers=color:blue;label:C;15.6031,50.7220&apikey=YOUR_API_KEY" \
--output map_multi.png
```
### HTML Image Embedding with Shapes
Display static maps with custom shapes and polygons directly in HTML.
```html
```
## Forward Geocoding API
### Address to Coordinates Conversion
Search for addresses, places, and POIs to get their geographic coordinates.
```bash
# Find coordinates for Prague Castle
curl "https://api.mapy.com/v1/geocode?apikey=YOUR_API_KEY&query=Prague+Castle&limit=5"
# Search for addresses only
curl "https://api.mapy.com/v1/geocode?apikey=YOUR_API_KEY&query=Václavské+náměstí&type=regional.address&limit=5"
# Search within Prague
curl "https://api.mapy.com/v1/geocode?apikey=YOUR_API_KEY&query=Hlavní+náměstí&locality=Praha&limit=5"
# Search with bounding box preference (prefer results in this area)
curl "https://api.mapy.com/v1/geocode?apikey=YOUR_API_KEY&query=restaurant&preferBBox=14.4,50.0,14.5,50.1&limit=10"
# Search near specific coordinates
curl "https://api.mapy.com/v1/geocode?apikey=YOUR_API_KEY&query=hotel&preferNear=14.4378,50.0755&preferNearPrecision=1000&limit=5"
```
### Autocomplete Suggestions
Provide real-time address suggestions as users type.
```html
```
## Reverse Geocoding API
### Coordinates to Address Conversion
Convert geographic coordinates to human-readable addresses.
```bash
# Get address for Prague coordinates
curl "https://api.mapy.com/v1/rgeocode?apikey=YOUR_API_KEY&lon=14.4378&lat=50.0755"
# Get address in English
curl "https://api.mapy.com/v1/rgeocode?apikey=YOUR_API_KEY&lon=14.42212&lat=50.08861&lang=en"
```
### JavaScript Click-on-Map Example
Implement "click on map to get address" functionality with Leaflet.
```javascript
const map = L.map('map').setView([50.0755, 14.4378], 13);
L.tileLayer(`https://api.mapy.com/v1/maptiles/basic/256/{z}/{x}/{y}?apikey=${API_KEY}`).addTo(map);
let marker = null;
map.on('click', async function(e) {
const { lat, lng } = e.latlng;
try {
const response = await fetch(`https://api.mapy.com/v1/rgeocode?apikey=${API_KEY}&lon=${lng}&lat=${lat}`);
const data = await response.json();
if (data.items && data.items.length > 0) {
const address = data.items.find(item => item.type === 'regional.address');
const street = data.items.find(item => item.type === 'regional.street');
const place = address || street || data.items[0];
// Remove old marker
if (marker) map.removeLayer(marker);
// Add new marker with popup
marker = L.marker([lat, lng])
.addTo(map)
.bindPopup(`${place.name} ${place.location}`)
.openPopup();
console.log('Full address data:', place);
}
} catch (error) {
console.error('Reverse geocoding error:', error);
}
});
```
## Routing API
### Calculate Routes Between Points
Compute routes with multiple transport modes and optional waypoints.
```bash
# Calculate car route from Prague to Brno
curl "https://api.mapy.com/v1/routing/route?apikey=YOUR_API_KEY&start=14.4378,50.0755&end=16.6068,49.1951&routeType=car_fast"
# Route with traffic consideration
curl "https://api.mapy.com/v1/routing/route?apikey=YOUR_API_KEY&start=14.4378,50.0755&end=16.6068,49.1951&routeType=car_fast_traffic"
# Walking route
curl "https://api.mapy.com/v1/routing/route?apikey=YOUR_API_KEY&start=14.4378,50.0755&end=14.5,50.1&routeType=foot_fast"
# Route with waypoints
curl "https://api.mapy.com/v1/routing/route?apikey=YOUR_API_KEY&start=14.4378,50.0755&end=16.6068,49.1951&waypoints=15.0,50.0;15.5,49.8&routeType=car_fast"
# Avoid toll roads
curl "https://api.mapy.com/v1/routing/route?apikey=YOUR_API_KEY&start=14.4378,50.0755&end=16.6068,49.1951&routeType=car_fast&avoidToll=true"
# Get route in polyline format
curl "https://api.mapy.com/v1/routing/route?apikey=YOUR_API_KEY&start=14.4378,50.0755&end=16.6068,49.1951&routeType=car_fast&format=polyline"
```
### Display Route on Leaflet Map
Complete example showing route calculation and display with error handling.
```html
Calculating route...
```
## Matrix Routing API
### Calculate Distance/Time Matrices
Compute distances and durations between multiple origins and destinations.
```bash
# 2x2 matrix (2 starts to 2 ends)
curl "https://api.mapy.com/v1/routing/matrix-m?apikey=YOUR_API_KEY&starts=14.4378,50.0755;14.5,50.1&ends=16.6068,49.1951;16.7,49.2&routeType=car_fast"
# NxN matrix (all starts to all starts - omit ends parameter)
curl "https://api.mapy.com/v1/routing/matrix-m?apikey=YOUR_API_KEY&starts=14.4378,50.0755;14.5,50.1;15.0,50.0&routeType=car_fast"
# Matrix with exploded array format
curl "https://api.mapy.com/v1/routing/matrix-m?apikey=YOUR_API_KEY&starts=14.4378,50.0755&starts=14.5,50.1&ends=16.6068,49.1951&ends=16.7,49.2&routeType=car_fast"
```
### Fleet Optimization Example
Calculate optimal delivery routes from warehouse to multiple locations.
```javascript
async function optimizeDeliveries(warehouseCoords, deliveryLocations) {
const API_KEY = 'YOUR_API_KEY';
// Prepare starts (warehouse) and ends (delivery locations)
const starts = `${warehouseCoords.lon},${warehouseCoords.lat}`;
const ends = deliveryLocations
.map(loc => `${loc.lon},${loc.lat}`)
.join(';');
const response = await fetch(
`https://api.mapy.com/v1/routing/matrix-m?apikey=${API_KEY}&starts=${starts}&ends=${ends}&routeType=car_fast`
);
const data = await response.json();
// Process results
const routes = deliveryLocations.map((loc, index) => {
const result = data.matrix[0][index];
// Check for errors (negative values)
if (result.length < 0) {
const errorMsg = result.length === -2 ? 'Too far' :
result.length === -3 ? 'Route not found' :
result.length === -4 ? 'Timeout' : 'Error';
return {
location: loc,
error: errorMsg,
distance: null,
duration: null
};
}
return {
location: loc,
distance: (result.length / 1000).toFixed(2) + ' km',
duration: Math.round(result.duration / 60) + ' min',
distanceMeters: result.length,
durationSeconds: result.duration
};
});
// Sort by distance
routes.sort((a, b) => (a.distanceMeters || Infinity) - (b.distanceMeters || Infinity));
return routes;
}
// Usage example
const warehouse = { lon: 14.4378, lat: 50.0755 };
const deliveries = [
{ lon: 14.5, lat: 50.1, name: 'Customer A' },
{ lon: 14.45, lat: 50.08, name: 'Customer B' },
{ lon: 14.48, lat: 50.09, name: 'Customer C' }
];
optimizeDeliveries(warehouse, deliveries).then(routes => {
console.log('Optimized delivery order:');
routes.forEach((route, index) => {
if (route.error) {
console.log(`${index + 1}. ${route.location.name}: ERROR - ${route.error}`);
} else {
console.log(`${index + 1}. ${route.location.name}: ${route.distance}, ${route.duration}`);
}
});
});
```
## Elevation API
### Get Elevation Data for Coordinates
Retrieve elevation information using the DTM-5 elevation model.
```bash
# Get elevation for single point
curl "https://api.mapy.com/v1/elevation?apikey=YOUR_API_KEY&positions=14.4009400,50.0711000"
# Get elevation for multiple points (semicolon-separated)
curl "https://api.mapy.com/v1/elevation?apikey=YOUR_API_KEY&positions=14.4009400,50.0711000;14.3951303,50.0704094;14.4100000,50.0720000"
# Get elevation for route profile (exploded array format)
curl "https://api.mapy.com/v1/elevation?apikey=YOUR_API_KEY&positions=14.40,50.07&positions=14.41,50.07&positions=14.42,50.07&positions=14.43,50.07"
```
### Create Elevation Profile for Route
Generate elevation profile chart for a calculated route.
```javascript
async function getRouteElevationProfile(start, end, routeType = 'foot_hiking') {
const API_KEY = 'YOUR_API_KEY';
// First, calculate the route
const routeResponse = await fetch(
`https://api.mapy.com/v1/routing/route?apikey=${API_KEY}&start=${start[0]},${start[1]}&end=${end[0]},${end[1]}&routeType=${routeType}&format=geojson`
);
const routeData = await routeResponse.json();
// Extract coordinates from route geometry
const routeCoords = routeData.geometry.geometry.coordinates;
// Sample every 10th point to reduce API calls (max 256 points)
const sampledCoords = routeCoords.filter((_, index) => index % 10 === 0);
// Format coordinates for elevation API (lon,lat format)
const positions = sampledCoords
.map(coord => `${coord[0]},${coord[1]}`)
.join(';');
// Get elevation data
const elevResponse = await fetch(
`https://api.mapy.com/v1/elevation?apikey=${API_KEY}&positions=${positions}`
);
const elevData = await elevResponse.json();
// Calculate distance along route for each point
let cumulativeDistance = 0;
const profile = elevData.items.map((item, index) => {
if (index > 0) {
const prev = elevData.items[index - 1];
const distance = calculateDistance(
prev.position.lat, prev.position.lon,
item.position.lat, item.position.lon
);
cumulativeDistance += distance;
}
return {
distance: cumulativeDistance,
elevation: item.elevation,
lat: item.position.lat,
lon: item.position.lon
};
});
return {
route: routeData,
profile: profile,
totalDistance: routeData.length / 1000, // km
elevationGain: calculateElevationGain(profile),
maxElevation: Math.max(...profile.map(p => p.elevation)),
minElevation: Math.min(...profile.map(p => p.elevation))
};
}
function calculateDistance(lat1, lon1, lat2, lon2) {
const R = 6371000; // Earth radius in meters
const φ1 = lat1 * Math.PI / 180;
const φ2 = lat2 * Math.PI / 180;
const Δφ = (lat2 - lat1) * Math.PI / 180;
const Δλ = (lon2 - lon1) * Math.PI / 180;
const a = Math.sin(Δφ/2) * Math.sin(Δφ/2) +
Math.cos(φ1) * Math.cos(φ2) *
Math.sin(Δλ/2) * Math.sin(Δλ/2);
const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1-a));
return R * c;
}
function calculateElevationGain(profile) {
let gain = 0;
for (let i = 1; i < profile.length; i++) {
const diff = profile[i].elevation - profile[i-1].elevation;
if (diff > 0) gain += diff;
}
return Math.round(gain);
}
// Usage
getRouteElevationProfile([15.7392, 50.7366], [15.7500, 50.7400], 'foot_hiking')
.then(data => {
console.log(`Total distance: ${data.totalDistance.toFixed(2)} km`);
console.log(`Elevation gain: ${data.elevationGain} m`);
console.log(`Max elevation: ${data.maxElevation.toFixed(1)} m`);
console.log(`Min elevation: ${data.minElevation.toFixed(1)} m`);
console.log('Profile points:', data.profile.length);
});
```
## Static Panorama API
### Generate 360° Panorama Images
Retrieve static panoramic street-level images for embedding in applications.
```bash
# Basic panorama with automatic orientation
curl "https://api.mapy.com/v1/static/pano?apikey=YOUR_API_KEY&lon=16.6&lat=49.19&width=400&height=250" \
--output panorama.jpg
# Panorama looking north (yaw=0)
curl "https://api.mapy.com/v1/static/pano?apikey=YOUR_API_KEY&lon=16.6&lat=49.19&width=400&height=250&yaw=0" \
--output pano_north.jpg
# Panorama with custom view (yaw, pitch, fov)
curl "https://api.mapy.com/v1/static/pano?apikey=YOUR_API_KEY&lon=16.6&lat=49.19&width=600&height=400&yaw=1.57&pitch=0.5&fov=1.0" \
--output pano_custom.jpg
# Panorama pointing toward coordinates
curl "https://api.mapy.com/v1/static/pano?apikey=YOUR_API_KEY&lon=16.6&lat=49.19&width=400&height=250&yaw=point" \
--output pano_point.jpg
```
### HTML Panorama Gallery
Create a panorama viewer with direction controls.
```html
```
## Time Zones API
### Get Timezone Information
Retrieve timezone data, local time, and UTC offsets for coordinates or IANA codes.
```bash
# Get all IANA timezone names
curl "https://api.mapy.com/v1/timezone/list-timezones?apikey=YOUR_API_KEY"
# Get timezone by IANA code
curl "https://api.mapy.com/v1/timezone/timezone?apikey=YOUR_API_KEY&timezone=Europe/Prague"
# Get timezone by coordinates
curl "https://api.mapy.com/v1/timezone/coordinate?apikey=YOUR_API_KEY&lon=14.4378&lat=50.0755"
# Get timezone in English
curl "https://api.mapy.com/v1/timezone/coordinate?apikey=YOUR_API_KEY&lon=-74.0060&lat=40.7128&lang=en"
```
### World Clock Application
Display current time for multiple locations with DST information.
```javascript
class WorldClock {
constructor(apiKey) {
this.apiKey = apiKey;
}
async getTimeForLocation(lon, lat, locationName) {
try {
const response = await fetch(
`https://api.mapy.com/v1/timezone/coordinate?apikey=${this.apiKey}&lon=${lon}&lat=${lat}&lang=en`
);
const data = await response.json();
const tz = data.timezone;
return {
location: locationName,
timezone: tz.timezoneName,
localTime: new Date(tz.currentLocalTime),
utcTime: new Date(tz.currentUtcTime),
utcOffset: tz.currentUtcOffsetSeconds / 3600,
isDST: tz.isDstActive,
dstInfo: tz.hasDst ? {
active: tz.isDstActive,
start: new Date(tz.dstInfo.dstStartLocalTime),
end: new Date(tz.dstInfo.dstEndLocalTime)
} : null
};
} catch (error) {
console.error(`Error getting time for ${locationName}:`, error);
return null;
}
}
async displayWorldTimes(locations) {
const times = await Promise.all(
locations.map(loc => this.getTimeForLocation(loc.lon, loc.lat, loc.name))
);
console.log('\n=== WORLD CLOCK ===\n');
times.forEach(time => {
if (time) {
const offsetStr = time.utcOffset >= 0 ? `+${time.utcOffset}` : time.utcOffset;
const dstIndicator = time.isDST ? ' (DST)' : '';
console.log(`${time.location}:`);
console.log(` Local Time: ${time.localTime.toLocaleString()}`);
console.log(` Timezone: ${time.timezone} (UTC${offsetStr})${dstIndicator}`);
if (time.dstInfo && time.dstInfo.active) {
console.log(` DST ends: ${time.dstInfo.end.toLocaleDateString()}`);
}
console.log('');
}
});
return times;
}
}
// Usage
const clock = new WorldClock('YOUR_API_KEY');
const locations = [
{ name: 'Prague', lon: 14.4378, lat: 50.0755 },
{ name: 'New York', lon: -74.0060, lat: 40.7128 },
{ name: 'Tokyo', lon: 139.6917, lat: 35.6895 },
{ name: 'Sydney', lon: 151.2093, lat: -33.8688 }
];
clock.displayWorldTimes(locations);
```
## URL Schemes
### Show Map URL
Link directly to map locations on Mapy.com.
```html
View Prague Castle
View Hiking Area
Aerial View
Current Traffic
```
### Search URL
Trigger location and business searches on Mapy.com.
```javascript
// Dynamic search function
function searchOnMapy(query, centerLon, centerLat, zoom = 14) {
const encodedQuery = encodeURIComponent(query);
const centerParam = centerLon && centerLat ? `¢er=${centerLon},${centerLat}` : '';
const url = `https://mapy.com/fnc/v1/search?query=${encodedQuery}${centerParam}&zoom=${zoom}`;
window.open(url, '_blank');
}
// Search form integration
document.getElementById('searchForm').addEventListener('submit', function(e) {
e.preventDefault();
const query = document.getElementById('query').value;
searchOnMapy(query, 14.4378, 50.0755);
});
// Example searches
searchOnMapy('restaurant', 14.4378, 50.0755); // Restaurants near Prague center
searchOnMapy('hotel', 16.6068, 49.1951); // Hotels in Brno
searchOnMapy('Prague Castle'); // Search without location bias
```
### Route URL
Provide "Get Directions" links with various transport modes.
```html
Drive to Brno
Walk to Location
Hiking Trail
Bike Route
Navigate Now
```
### Dynamic Route from Current Location
Generate navigation links using browser geolocation.
```javascript
function getDirectionsFromHere(destLon, destLat, destName, routeType = 'car_fast') {
if (!navigator.geolocation) {
alert('Geolocation is not supported by your browser');
return;
}
navigator.geolocation.getCurrentPosition(
position => {
const start = `${position.coords.longitude},${position.coords.latitude}`;
const end = `${destLon},${destLat}`;
const url = `https://mapy.com/fnc/v1/route?start=${start}&end=${end}&routeType=${routeType}`;
window.open(url, '_blank');
},
error => {
console.error('Error getting location:', error);
// Fallback: open without start location (user will be prompted)
const url = `https://mapy.com/fnc/v1/route?end=${destLon},${destLat}&routeType=${routeType}`;
window.open(url, '_blank');
}
);
}
// Usage
document.getElementById('directionsBtn').addEventListener('click', () => {
getDirectionsFromHere(14.5, 50.08, 'Our Office', 'car_fast');
});
```
## JS Panorama Component
### Interactive 360° Panorama Viewer
Embed interactive street-level panoramas in your application.
```html
Interactive Panorama
```
### Programmatic Camera Control
Control panorama view direction programmatically.
```javascript
// Create panorama viewer
const panoData = await Panorama.panoramaFromPosition({
parent: document.getElementById('panoContainer'),
lon: 16.6080370,
lat: 49.1949758,
apiKey: 'YOUR_API_KEY',
showNavigation: true
});
// Get current camera position
const camera = panoData.getCamera();
console.log('Current view:', {
yaw: camera.yaw, // Horizontal angle (0 = north)
pitch: camera.pitch, // Vertical angle (0 = horizon)
fov: camera.fov // Field of view (zoom)
});
// Set camera to look east with slight upward tilt
panoData.setCamera({
yaw: Math.PI / 2, // 90 degrees = east
pitch: -Math.PI / 12, // Look slightly up
fov: 1.0 // Slightly zoomed in
});
// Rotate panorama slowly (360 degree rotation)
function rotatePanorama(durationMs = 10000) {
const startYaw = panoData.getCamera().yaw;
const startTime = Date.now();
function animate() {
const elapsed = Date.now() - startTime;
const progress = elapsed / durationMs;
if (progress < 1) {
panoData.setCamera({
yaw: startYaw + (2 * Math.PI * progress),
pitch: 0,
fov: 1.2
});
requestAnimationFrame(animate);
}
}
animate();
}
// Start rotation
rotatePanorama(15000); // 15 second rotation
```
## Summary
The Mapy.com platform provides developers with comprehensive mapping capabilities through three integration methods: REST APIs for programmatic data access, URL schemes for direct web linking, and JavaScript components for interactive features. The REST APIs cover essential geospatial operations including map tile serving with multiple mapsets (basic, outdoor, winter, aerial), geocoding for address-coordinate conversion with autocomplete support, routing with multiple transport modes and waypoint support, distance/time matrix calculations for logistics optimization, elevation data from high-precision DTM models, static panoramic imagery generation, and timezone information with DST handling. All REST endpoints return JSON responses and support rate limits appropriate for production applications, with tile APIs supporting up to 500 requests per second and other endpoints ranging from 30-300 requests per second.
Integration patterns range from simple HTML image embedding for static maps and panoramas, to full interactive mapping applications using Leaflet or MapLibre GL JS, to complex geospatial analysis workflows. The URL schemes enable seamless deep-linking from websites to the Mapy.com platform and mobile apps for map display, location search, and navigation without requiring API keys. The JS Panorama component provides efficient tile-based loading of 360° imagery with event handling, programmatic camera control, and navigation between adjacent panoramas. Common use cases include business location display with "Get Directions" functionality, real estate property mapping with nearby amenities, logistics route optimization with matrix routing, outdoor recreation planning with elevation profiles on hiking maps, travel applications with timezone-aware scheduling, and location-based services with geocoding and reverse geocoding. The platform excels in Central European coverage with particularly detailed data for Czech Republic including nationwide panoramic imagery updated 2021-2023 and high-accuracy lidar-based elevation models.