Mapy.com (mapycom/developer)

Mapy.com

https://github.com/mapycom/developer
Admin
Mapy.com provides a suite of developer APIs and URL schemes for map tiles, geocoding, routing,...

Tokens:64,319
Snippets:203
Trust Score:2
Update:4 months ago
Show doc for...
Context Summary (auto-generated)
Raw
# 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
<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8" />
  <title>Mapy.com with Leaflet</title>
  <link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css" />
  <script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>
  <style>
    body { margin: 0; padding: 0; }
    #map { position: absolute; top: 0; bottom: 0; width: 100%; }
  </style>
</head>
<body>
  <div id="map"></div>
  <script>
    const API_KEY = 'YOUR_API_KEY';

    // Create map centered on Prague Castle
    const map = L.map('map').setView([50.0907, 14.4003], 16);

    // Add Mapy.com tile layer
    L.tileLayer(`https://api.mapy.com/v1/maptiles/basic/256/{z}/{x}/{y}?apikey=${API_KEY}`, {
      minZoom: 0,
      maxZoom: 20,
      attribution: '<a href="https://api.mapy.com/copyright" target="_blank">&copy; Seznam.cz a.s. a další</a>'
    }).addTo(map);

    // Add required logo control
    const LogoControl = L.Control.extend({
      options: { position: 'bottomleft' },
      onAdd: function(map) {
        const container = L.DomUtil.create('div');
        const link = L.DomUtil.create('a', '', container);
        link.setAttribute('href', 'http://mapy.com/');
        link.setAttribute('target', '_blank');
        link.innerHTML = '<img src="https://api.mapy.com/img/api/logo.svg" />';
        L.DomEvent.disableClickPropagation(link);
        return container;
      }
    });

    new LogoControl().addTo(map);
  </script>
</body>
</html>
```

## 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
<!-- Aerial map with polygon overlay -->
<img src="https://api.mapy.com/v1/static/map?width=500&height=450&mapset=aerial&shapes=color:red;path:[(15.6054,50.7260;15.6074,50.7260;15.6074,50.7240;15.6054,50.7240;15.6054,50.7260)]&shapes=color:blue;fill:%230000FF80;polygon:[(15.6112,50.7255;15.6132,50.7250;15.6152,50.7255;15.6112,50.7255)]&apikey=YOUR_API_KEY"
     alt="Map with shapes" />

<!-- Retina resolution map (2x) -->
<img src="https://api.mapy.com/v1/static/map?lon=15.742&lat=50.735&zoom=14&width=200&height=200&scale=2&mapset=outdoor&markers=color:red;size:normal;label:1;15.742,50.735&apikey=YOUR_API_KEY"
     alt="High-DPI map" />

<!-- Bounding box map covering Czech Republic -->
<img src="https://api.mapy.com/v1/static/map?lon=12.09&lat=48.55&lon=18.87&lat=51.05&width=600&height=400&mapset=basic&apikey=YOUR_API_KEY"
     alt="Czech Republic overview" />
```

## 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
<!DOCTYPE html>
<html lang="en">
<head>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@tarekraafat/autocomplete.js@10.2.7/dist/css/autoComplete.02.min.css">
</head>
<body>
  <div class="autoComplete_wrapper">
    <input id="autoComplete" type="search" placeholder="Enter address...">
  </div>

  <script src="https://cdn.jsdelivr.net/npm/@tarekraafat/autocomplete.js@10.2.7/dist/autoComplete.min.js"></script>
  <script>
    const API_KEY = 'YOUR_API_KEY';
    const queryCache = {};

    const getItems = async(query) => {
      if (queryCache[query]) return queryCache[query];

      try {
        const response = await fetch(`https://api.mapy.cz/v1/suggest?lang=cs&limit=5&type=regional.address&apikey=${API_KEY}&query=${query}`);
        const jsonData = await response.json();
        const items = jsonData.items.map(item => ({
          value: item.name,
          data: item
        }));
        queryCache[query] = items;
        return items;
      } catch (exc) {
        return [];
      }
    };

    const autoCompleteJS = new autoComplete({
      selector: () => document.querySelector("#autoComplete"),
      placeHolder: "Enter your address...",
      data: {
        keys: ["value"],
        src: async(query) => {
          const items = await getItems(query);
          const inputElem = document.querySelector("#autoComplete");
          if (queryCache[inputElem.value]) {
            return queryCache[inputElem.value];
          }
          return items;
        },
        cache: false
      },
      resultItem: {
        element: (item, data) => {
          const itemData = data.value.data;
          const desc = document.createElement("div");
          desc.style = "overflow: hidden; white-space: nowrap; text-overflow: ellipsis;";
          desc.innerHTML = `${itemData.label}, ${itemData.location}`;
          item.append(desc);
        },
        highlight: true
      }
    });

    document.querySelector("#autoComplete").addEventListener("selection", event => {
      const origData = event.detail.selection.value.data;
      console.log("Selected:", origData);
      console.log("Coordinates:", origData.position.lon, origData.position.lat);
    });
  </script>
</body>
</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(`<strong>${place.name}</strong><br>${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
<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css" />
  <script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>
  <style>
    body { margin: 0; padding: 0; }
    #map { position: absolute; top: 0; bottom: 0; width: 100%; }
    #info { position: absolute; top: 10px; right: 10px; background: white;
            padding: 10px; border-radius: 5px; z-index: 1000; }
  </style>
</head>
<body>
  <div id="map"></div>
  <div id="info">Calculating route...</div>

  <script>
    const API_KEY = 'YOUR_API_KEY';
    const map = L.map('map').setView([50.0755, 14.4378], 8);

    L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png').addTo(map);

    async function calculateRoute(start, end, routeType = 'car_fast') {
      try {
        const response = 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`
        );

        if (!response.ok) {
          const error = await response.json();
          throw new Error(`Route error: ${error.detail?.[0]?.msg || 'Unknown error'}`);
        }

        const data = await response.json();

        // Add route to map (geometry is already a GeoJSON Feature)
        const routeLayer = L.geoJSON(data.geometry, {
          style: { color: '#2196F3', weight: 5, opacity: 0.7 }
        }).addTo(map);

        // Add markers
        L.marker(start.reverse()).addTo(map).bindPopup('Start');
        L.marker(end.reverse()).addTo(map).bindPopup('End');

        // Fit map to route
        map.fitBounds(routeLayer.getBounds());

        // Display route info
        const distance = (data.length / 1000).toFixed(2);
        const duration = Math.round(data.duration / 60);
        document.getElementById('info').innerHTML =
          `<strong>Route Info</strong><br>Distance: ${distance} km<br>Duration: ${duration} min`;

        return data;
      } catch (error) {
        console.error('Routing error:', error);
        document.getElementById('info').innerHTML =
          `<strong style="color:red">Error:</strong><br>${error.message}`;
      }
    }

    // Calculate route from Prague to Brno
    calculateRoute([14.4378, 50.0755], [16.6068, 49.1951], 'car_fast');
  </script>
</body>
</html>
```

## 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
<!DOCTYPE html>
<html>
<head>
  <style>
    .pano-viewer { text-align: center; }
    .pano-controls { margin: 10px 0; }
    .pano-controls button { margin: 0 5px; padding: 8px 16px; }
    #panorama { max-width: 100%; border: 1px solid #ccc; }
  </style>
</head>
<body>
  <div class="pano-viewer">
    <div class="pano-controls">
      <button onclick="rotatePanorama(0)">North</button>
      <button onclick="rotatePanorama(Math.PI/2)">East</button>
      <button onclick="rotatePanorama(Math.PI)">South</button>
      <button onclick="rotatePanorama(3*Math.PI/2)">West</button>
      <button onclick="rotatePanorama('auto')">Auto</button>
      <button onclick="rotatePanorama('point')">Point to Location</button>
    </div>
    <img id="panorama" alt="Street view panorama">
  </div>

  <script>
    const API_KEY = 'YOUR_API_KEY';
    const location = { lon: 16.6, lat: 49.19 };
    let currentYaw = 'auto';
    let currentPitch = 0;
    let currentFov = 1.2;

    function rotatePanorama(yaw, pitch = 0, fov = 1.2) {
      currentYaw = yaw;
      currentPitch = pitch;
      currentFov = fov;
      updatePanorama();
    }

    function updatePanorama() {
      const yawParam = typeof currentYaw === 'number' ? `&yaw=${currentYaw}` :
                       currentYaw === 'point' ? '&yaw=point' : '';
      const url = `https://api.mapy.com/v1/static/pano?apikey=${API_KEY}&lon=${location.lon}&lat=${location.lat}&width=800&height=500${yawParam}&pitch=${currentPitch}&fov=${currentFov}`;
      document.getElementById('panorama').src = url;
    }

    // Initialize
    updatePanorama();
  </script>
</body>
</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
<!-- Basic location with marker -->
<a href="https://mapy.com/fnc/v1/showmap?center=14.4003,50.0907&zoom=16&marker=true"
   target="_blank">
  View Prague Castle
</a>

<!-- Outdoor map for hiking area -->
<a href="https://mapy.com/fnc/v1/showmap?mapset=outdoor&center=15.7392,50.7366&zoom=14&marker=true">
  View Hiking Area
</a>

<!-- Aerial/satellite view -->
<a href="https://mapy.com/fnc/v1/showmap?mapset=aerial&center=14.4378,50.0755&zoom=15">
  Aerial View
</a>

<!-- Traffic map -->
<a href="https://mapy.com/fnc/v1/showmap?mapset=traffic&center=14.4378,50.0755&zoom=13">
  Current Traffic
</a>
```

### 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 ? `&center=${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
<!-- Car route -->
<a href="https://mapy.com/fnc/v1/route?start=14.4378,50.0755&end=16.6068,49.1951&routeType=car_fast">
  Drive to Brno
</a>

<!-- Walking directions -->
<a href="https://mapy.com/fnc/v1/route?start=14.4203,50.0875&end=14.4378,50.0755&routeType=foot_fast">
  Walk to Location
</a>

<!-- Hiking route on outdoor map -->
<a href="https://mapy.com/fnc/v1/route?start=15.7392,50.7366&end=15.7500,50.7400&routeType=foot_hiking&mapset=outdoor">
  Hiking Trail
</a>

<!-- Cycling route with waypoint -->
<a href="https://mapy.com/fnc/v1/route?start=14.4,50.07&end=14.5,50.09&waypoints=14.45,50.08&routeType=bike_road">
  Bike Route
</a>

<!-- Start navigation immediately (mobile) -->
<a href="https://mapy.com/fnc/v1/route?start=14.4378,50.0755&end=14.5,50.08&routeType=car_fast&navigate=true">
  Navigate Now
</a>
```

### 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
<!DOCTYPE html>
<html>
<head>
  <title>Interactive Panorama</title>
  <script src='https://api.mapy.cz/js/panorama/v1/panorama.js'></script>
  <style>
    #panoContainer { width: 100%; height: 600px; }
    #controls { margin: 10px 0; }
  </style>
</head>
<body>
  <div id="controls">
    <button onclick="loadPanorama(16.6080370, 49.1949758)">Brno</button>
    <button onclick="loadPanorama(14.4200, 50.0875)">Prague</button>
    <button onclick="checkPanoExists(14.5, 50.1)">Check if Exists</button>
  </div>
  <div id="panoContainer"></div>
  <div id="info"></div>

  <script>
    const API_KEY = 'YOUR_API_KEY';
    let currentPano = null;

    async function loadPanorama(lon, lat) {
      const container = document.getElementById('panoContainer');

      // Destroy existing panorama
      if (currentPano) {
        currentPano.destroy();
      }

      try {
        currentPano = await Panorama.panoramaFromPosition({
          parent: container,
          lon: lon,
          lat: lat,
          apiKey: API_KEY,
          radius: 100,
          yaw: 'auto',
          pitch: 0,
          fov: 1.2,
          showNavigation: true,
          lang: 'en',
          hideErrors: false
        });

        if (currentPano.errorCode !== 'NONE') {
          document.getElementById('info').innerHTML =
            `<strong style="color:red">Error:</strong> ${currentPano.error}`;
          return;
        }

        // Display panorama info
        if (currentPano.info) {
          document.getElementById('info').innerHTML =
            `<strong>Panorama loaded:</strong><br>
             Location: ${currentPano.info.lat.toFixed(6)}, ${currentPano.info.lon.toFixed(6)}<br>
             Date: ${currentPano.info.date}`;
        }

        // Add event listeners
        currentPano.addListener('pano-view', (viewData) => {
          const camera = currentPano.getCamera();
          console.log('View changed:', {
            yaw: camera.yaw.toFixed(2),
            pitch: camera.pitch.toFixed(2),
            fov: camera.fov.toFixed(2)
          });
        });

        currentPano.addListener('pano-place', (placeData) => {
          console.log('Location changed to:', placeData.info);
          document.getElementById('info').innerHTML =
            `<strong>Moved to:</strong><br>
             Location: ${placeData.info.lat.toFixed(6)}, ${placeData.info.lon.toFixed(6)}<br>
             Date: ${placeData.info.date}`;
        });

      } catch (error) {
        console.error('Error loading panorama:', error);
        document.getElementById('info').innerHTML =
          `<strong style="color:red">Error:</strong> ${error.message}`;
      }
    }

    async function checkPanoExists(lon, lat) {
      try {
        const result = await Panorama.panoramaExists({
          lon: lon,
          lat: lat,
          apiKey: API_KEY,
          radius: 100
        });

        if (result.exists) {
          document.getElementById('info').innerHTML =
            `<strong style="color:green">Panorama exists!</strong><br>
             Location: ${result.info.lat.toFixed(6)}, ${result.info.lon.toFixed(6)}<br>
             Date: ${result.info.date}`;
        } else {
          document.getElementById('info').innerHTML =
            '<strong style="color:orange">No panorama found at this location</strong>';
        }
      } catch (error) {
        console.error('Error checking panorama:', error);
      }
    }

    // Load initial panorama
    window.addEventListener('load', () => {
      loadPanorama(16.6080370, 49.1949758);
    });
  </script>
</body>
</html>
```

### 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.