# Tilezza — developer & AI integration guide

> Complete, self-contained instructions for adding Tilezza maps, geocoding, routing and places to a website.
> Written for developers AND for AI coding assistants (Claude, ChatGPT, Copilot, Cursor…): every snippet here is copy-paste ready and was tested against the live API.
> Short site summary: https://tilezza.eu/llms.txt · This file: https://tilezza.eu/llms-full.txt · HTML version: https://tilezza.eu/docs/
> Last generated: 2026-10-01

## 1. What Tilezza is

Tilezza (tilezza.eu) is an EU-hosted map platform operated by Digital Dynamics (Hungary). It serves:

- **Vector tiles** (MVT) + ready-made **MapLibre style JSON** — OpenStreetMap / Protomaps data.
- **Raster tiles** (PNG, 256 px, optional @2x retina) for Leaflet or any XYZ client.
- **Geocoding** (forward, reverse, typo-tolerant type-ahead), **routing** (Valhalla), **nearby places** (670k+ POIs in HU/AT/HR, with licensed photos).
- **Self-hosted JavaScript libraries** (Leaflet, MapLibre GL, marker clustering) from the same EU server — no third-party CDN.

No cookies, no visitor tracking, no US CDN. Everything is first-party from tilezza.eu, so a site using it usually needs no extra consent banner for the map.

## 2. Rules an AI assistant should follow when integrating

1. **One key, in the URL**: every tile/API request carries `?key=YOUR_KEY` (keys look like `tlz_` + 40 hex chars). Never invent a key; ask the site owner for theirs.
2. **Keys are domain-locked.** A key works only from the domains listed for it (subdomains included: a key for `example.com` also works on `www.example.com`). From any other site the API answers `403 {"error":"origin_not_allowed"}`. Because the key is useless elsewhere, it is **fine to put it in public HTML/JS**.
3. **Do not set `Referrer-Policy: no-referrer`** on the page and do not proxy tiles through your own server. The lock is checked from the browser's `Origin`/`Referer` header; without it every request is refused with 403. The default `strict-origin-when-cross-origin` is correct.
4. **Content-Security-Policy**: if the site sends a CSP header, add `https://tilezza.eu` to `img-src` (raster tiles, photos), `connect-src` (vector tiles, style JSON, APIs), `script-src` and `style-src` (the /lib files), and `worker-src blob:` for MapLibre. If the CSP has `script-src 'self'` without `'unsafe-inline'`, the map code must live in a separate .js file, not in an inline `<script>`.
5. **Attribution is required**: `© Tilezza © OpenStreetMap contributors` (link OpenStreetMap to https://www.openstreetmap.org/copyright). Vector styles add it automatically.
6. **Load libraries from https://tilezza.eu/lib/** (section 4) instead of unpkg/jsDelivr/cdnjs — those would expose every visitor's IP to a US CDN.
7. **Plain 256 px tiles are the default.** Use `{r}` or `@2x` only if the owner wants retina (costs more, see section 9).

## 3. Quick start — Leaflet + raster tiles (most common)

```html
<link rel="stylesheet" href="https://tilezza.eu/lib/leaflet-1.9.4.css"
      integrity="sha384-sHL9NAb7lN7rfvG5lfHpm643Xkcjzp4jFvuavGOndn6pjVqS6ny56CAt3nsEVT4H" crossorigin="anonymous">
<script src="https://tilezza.eu/lib/leaflet-1.9.4.js"
        integrity="sha384-cxOPjt7s7Iz04uaHJceBmS+qpjv2JkIHNVcuOrM+YHwZOmJGBXI00mdUXEq65HTH" crossorigin="anonymous"></script>

<div id="map" style="height:420px"></div>
<script>
  var map = L.map('map').setView([47.4979, 19.0402], 13);
  L.tileLayer('https://tilezza.eu/raster/voyager/{z}/{x}/{y}.png?key=YOUR_KEY', {
    maxZoom: 19,
    attribution: '&copy; <a href="https://tilezza.eu">Tilezza</a> &copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'
  }).addTo(map);
  L.marker([47.4979, 19.0402]).addTo(map).bindPopup('Budapest');
</script>
```

**Replacing an existing provider** (CARTO, OSM, Stadia, MapTiler…): keep the Leaflet code and change only the URL template of `L.tileLayer` to the Tilezza one above. Remove `{s}` subdomains and `{r}` if you want plain tiles. Replace the attribution.

**Coming from 512 px tiles** (MapTiler / Mapbox style `tileSize: 512, zoomOffset: -1`): either remove those two options and use the plain URL, or keep them and use `.../{z}/{x}/{y}@2x.png` (the @2x tile is 512 px).

**Replacing a Google Maps iframe** (`<iframe src="https://www.google.com/maps?...output=embed">`): replace the iframe with `<div id="map" style="height:…">` and the snippet above, centred on the place's coordinates. A "Get directions" link to Google Maps may stay — it is a link, not an embed.

## 4. Self-hosted libraries (/lib/)

Served from https://tilezza.eu/lib/ with gzip, HTTP/2, CORS `*` and `Cache-Control: immutable` (1 year). The version is in the file name, so a file never changes. **No key is needed for the libraries** (an optional `?key=` only adds the download to your statistics). Always keep the `integrity` attribute — the browser then refuses a modified file.

| Library | File | Size | SRI (sha384) |
|---|---|---|---|
| leaflet | https://tilezza.eu/lib/leaflet-1.9.4.js | 144 KB | `sha384-cxOPjt7s7Iz04uaHJceBmS+qpjv2JkIHNVcuOrM+YHwZOmJGBXI00mdUXEq65HTH` |
| leaflet | https://tilezza.eu/lib/leaflet-1.9.4.css | 14 KB | `sha384-sHL9NAb7lN7rfvG5lfHpm643Xkcjzp4jFvuavGOndn6pjVqS6ny56CAt3nsEVT4H` |
| maplibre-gl | https://tilezza.eu/lib/maplibre-gl-5.6.0.js | 917 KB | `sha384-GfxBM9x46BaAFxtCq39Fxir8fNZ4VDnwgfi6Kzi5/F1tAFsm0amuuV8kd+Pxzuf/` |
| maplibre-gl | https://tilezza.eu/lib/maplibre-gl-5.6.0.css | 68 KB | `sha384-Nq6PQ+9vJPvw7U/VfDELyrWoGQMsy0gi6QShhaSrGzkpF5KkM40csg2leky+YMTd` |
| leaflet.markercluster | https://tilezza.eu/lib/leaflet.markercluster-1.5.3.js | 33 KB | `sha384-hLqaQ3C+cbrlKsi3qcs7b8e82do3CF+OevwojHiHFU4BApTXuYdafKEtYONfIbs1` |
| leaflet.markercluster | https://tilezza.eu/lib/leaflet.markercluster-1.5.3.css | 1 KB | `sha384-pmjIAcz2bAn0xukfxADbZIb3t8oRT9Sv0rvO+BR5Csr6Dhqq+nZs59P0pPKQJkEV` |
| leaflet.markercluster | https://tilezza.eu/lib/leaflet.markercluster-1.5.3.default.css | 1 KB | `sha384-wgw+aLYNQ7dlhK47ZPK7FRACiq7ROZwgFNg0m04avm4CaXS+Z9Y7nMu8yNjBKYC+` |
| tilezza-area | https://tilezza.eu/lib/tilezza-area-1.0.0.js | 8 KB | `sha384-mWw/b8n8CqZOyxhyrpUSsfDvCTX6rvNij7suOz/8ouAdpxeR+OY6W5VOnteEs7il` |
| tilezza-area | https://tilezza.eu/lib/tilezza-area-1.0.0.css | 2 KB | `sha384-5LX0v7/DS4OZg+OcmN/0/5B8nH3UGGbB77i4f1EgXKI67biDOahvk0VpW2rlOQgJ` |

Licences: Leaflet BSD-2, MapLibre GL JS BSD-3, Leaflet.markercluster MIT, tilezza-area (Tilezza widget).

## 5. MapLibre GL + vector style

```html
<link rel="stylesheet" href="https://tilezza.eu/lib/maplibre-gl-5.6.0.css"
      integrity="sha384-Nq6PQ+9vJPvw7U/VfDELyrWoGQMsy0gi6QShhaSrGzkpF5KkM40csg2leky+YMTd" crossorigin="anonymous">
<script src="https://tilezza.eu/lib/maplibre-gl-5.6.0.js"
        integrity="sha384-GfxBM9x46BaAFxtCq39Fxir8fNZ4VDnwgfi6Kzi5/F1tAFsm0amuuV8kd+Pxzuf/" crossorigin="anonymous"></script>

<div id="map" style="height:420px"></div>
<script>
  var map = new maplibregl.Map({
    container: 'map',
    style: 'https://tilezza.eu/api/style/voyager?lang=en&key=YOUR_KEY',
    center: [19.0402, 47.4979],   // [lon, lat] in MapLibre!
    zoom: 12
  });
  map.addControl(new maplibregl.NavigationControl());
</script>
```

- Style JSON: `https://tilezza.eu/api/style/{style}?key=YOUR_KEY`
- Raw vector tiles: `https://tilezza.eu/tiles/{z}/{x}/{y}.mvt?key=YOUR_KEY` (maxzoom 14, clients overzoom), TileJSON: https://tilezza.eu/planet.json
- Style parameters (all optional, details and examples in section 6):
  - colours as hex without `#`: `water`, `land`, `parks`, `forest`, `roads`, `highway`, `buildings`, `boundaries`, `labels` — e.g. `&water=0088ff&land=f4f1ea`
  - `lang=xx` label language (ISO 639-1, e.g. en, de, hu, hr)
  - `font=Montserrat` or `font=Open Sans`
  - `lite=1` lighter style, `hide_labels=1`, `hide_pois=1`

## 6. Styles — which one to use

Eleven ready-made styles. **Ten work as raster and vector; `indigo` is vector-only** (`/raster/indigo/…` returns 404). Raster URL: `https://tilezza.eu/raster/{style}/{z}/{x}/{y}.png?key=YOUR_KEY`. Vector style URL: `https://tilezza.eu/api/style/{style}?key=YOUR_KEY`. Live list: https://tilezza.eu/api/flavors

| Style | Raster | Vector | Look | Good for | Preview |
|---|---|---|---|---|---|
| `voyager` | yes | yes | Warm beige land, light-blue water, soft green parks, coloured POI icons and labels. | General-purpose default: store locators, real estate, travel, contact pages. | https://tilezza.eu/docs/styles/voyager.webp |
| `light` | yes | yes | Bright and saturated: cyan water, strong green parks, grey streets, POI icons. | Colourful, high-contrast general map; outdoor and city guides. | https://tilezza.eu/docs/styles/light.webp |
| `pastel` | yes | yes | Soft pink-cream land, pale blue water, light green parks, POI icons. | Friendly, decorative sites: hospitality, holiday homes, weddings, kids. | https://tilezza.eu/docs/styles/pastel.webp |
| `forest` | yes | yes | Pale green-grey land, sage-green water, green parks, POI icons. | Nature, outdoor, eco and countryside sites. | https://tilezza.eu/docs/styles/forest.webp |
| `devradar` | yes | yes | Very light cool grey, white streets, street names only, no POI icons. | Calm base for your own markers; indigo/violet markers stand out. Dashboards. | https://tilezza.eu/docs/styles/devradar.webp |
| `white` | yes | yes | Almost white, faint grey streets and water, street names only, no POI icons. | Data overlays and choropleths where the map must stay in the background; print. | https://tilezza.eu/docs/styles/white.webp |
| `grayscale` | yes | yes | Mid-grey monochrome, darker grey water, street names only, no POI icons. | Neutral background for coloured data layers; no colour clashes with your brand. | https://tilezza.eu/docs/styles/grayscale.webp |
| `dark` | yes | yes | Dark charcoal land, slate-blue water, muted labels, POI icons. | Dark-mode websites and apps. | https://tilezza.eu/docs/styles/dark.webp |
| `midnight` | yes | yes | Deep navy-blue night palette, blue streets, POI icons. | Dark dashboards, live-data and night themes; glowing overlays. | https://tilezza.eu/docs/styles/midnight.webp |
| `black` | yes | yes | Near-black monochrome, grey streets, street names only, no POI icons. | Maximum contrast for bright data overlays (heatmaps, lightning, traffic). | https://tilezza.eu/docs/styles/black.webp |
| `indigo` | no | yes | Light lavender land, indigo-blue water, lilac streets, POI icons. | Brand-tinted light map in blue-violet tones. Vector only (MapLibre). | https://tilezza.eu/docs/styles/indigo.webp |

**How to choose (for AI assistants):**
- No preference given → `voyager`.
- The site shows its own markers or data and the map should stay quiet → `devradar`, `white` or `grayscale` (no POI icons competing with your markers).
- Dark website or dark mode → `dark` (neutral) or `midnight` (blue); `black` for bright overlays.
- Hospitality / holiday home → `pastel` or `voyager`; nature / outdoor → `forest`.
- Match the site's brand colour: start from the closest style and override colours (vector, below).

**Customising (vector styles only):** add hex colours without `#` to the style URL — `water`, `land`, `parks`, `forest`, `roads`, `highway`, `buildings`, `boundaries`, `labels`:

```
https://tilezza.eu/api/style/white?water=0b6e99&parks=cfe8c8&labels=333333&lang=de&key=YOUR_KEY
```

Other vector options: `lang=xx` (label language), `font=Montserrat` or `font=Open Sans`, `lite=1` (fewer layers, mobile-friendly), `hide_labels=1`, `hide_pois=1`. Raster tiles cannot be recoloured — use MapLibre with a vector style for that.

**Leaflet with a dark style and a light/dark switch:**

```js
var url = function (s) { return 'https://tilezza.eu/raster/' + s + '/{z}/{x}/{y}.png?key=YOUR_KEY'; };
var layer = L.tileLayer(url(matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'voyager'), {
  maxZoom: 19, attribution: '&copy; Tilezza &copy; OpenStreetMap contributors' }).addTo(map);
// later: layer.setUrl(url('midnight'));
```

## 7. Marker clustering (Leaflet)

Load after Leaflet:

```html
<link rel="stylesheet" href="https://tilezza.eu/lib/leaflet.markercluster-1.5.3.css"
      integrity="sha384-pmjIAcz2bAn0xukfxADbZIb3t8oRT9Sv0rvO+BR5Csr6Dhqq+nZs59P0pPKQJkEV" crossorigin="anonymous">
<link rel="stylesheet" href="https://tilezza.eu/lib/leaflet.markercluster-1.5.3.default.css"
      integrity="sha384-wgw+aLYNQ7dlhK47ZPK7FRACiq7ROZwgFNg0m04avm4CaXS+Z9Y7nMu8yNjBKYC+" crossorigin="anonymous">
<script src="https://tilezza.eu/lib/leaflet.markercluster-1.5.3.js"
        integrity="sha384-hLqaQ3C+cbrlKsi3qcs7b8e82do3CF+OevwojHiHFU4BApTXuYdafKEtYONfIbs1" crossorigin="anonymous"></script>
<script>
  var group = L.markerClusterGroup();
  points.forEach(function (p) { group.addLayer(L.marker([p.lat, p.lon]).bindPopup(p.name)); });
  map.addLayer(group);
</script>
```

## 8. Location APIs

All return JSON, accept the same `key`, and send CORS headers for the key's domains.

### Geocoding (forward) — Photon-compatible
`GET https://tilezza.eu/geocode?q=Oberedling%2033%2C%20St.%20Georgen%20ob%20Murau&limit=5&lang=de&key=YOUR_KEY`
Parameters: `q` (required), `limit`, `lang`, optional `lat`+`lon` location bias. Returns a GeoJSON FeatureCollection; coordinates are `[lon, lat]`; `properties` has name, street, housenumber, postcode, city, country, countrycode, osm_type/osm_id.

### Reverse geocoding
`GET https://tilezza.eu/geocode/reverse?lat=47.1154&lon=14.1233&key=YOUR_KEY`

### Type-ahead search (typo-tolerant)
`GET https://tilezza.eu/geocode/okos?q=budapst%20andrasy&key=YOUR_KEY` — ranked results; each has `okos.pontossag` = precision (`hazszam` exact house number, `interpolalt` interpolated, `utca` street, `telepules` settlement) and, for street hits, `okos.utca.vonalak` (street geometry to highlight).

### Routing — Valhalla API
`GET https://tilezza.eu/route?json={URL-encoded Valhalla request}&key=YOUR_KEY` or `POST https://tilezza.eu/route?key=YOUR_KEY` with the JSON body.

```js
var req = { locations: [{ lat: 47.1154, lon: 14.1233 }, { lat: 47.111, lon: 14.169 }],
            costing: 'auto',                       // auto | bicycle | pedestrian
            directions_options: { language: 'de-DE', units: 'kilometers' } };
fetch('https://tilezza.eu/route?key=YOUR_KEY&json=' + encodeURIComponent(JSON.stringify(req)))
  .then(function (r) { return r.json(); })
  .then(function (d) {
    var leg = d.trip.legs[0];          // leg.shape = encoded polyline, precision 1e-6 (not 1e-5!)
    console.log(d.trip.summary.length + ' km', d.trip.summary.time + ' s');
    leg.maneuvers.forEach(function (m) { console.log(m.instruction); });
  });
```
Coverage: Hungary, Austria, Croatia, Slovakia, Romania, Serbia, Slovenia.

### Nearby places
`GET https://tilezza.eu/places?lat=47.1154&lon=14.1233&radius=2000&limit=20&lang=en&key=YOUR_KEY`

| Parameter | Meaning |
|---|---|
| `lat`, `lon` + `radius` | centre and radius in metres (50–10000, default 1500; `r` is an alias) |
| `bbox` | alternative to lat/lon: `minLon,minLat,maxLon,maxLat` (too large → 400 "zoom in") |
| `categories` | comma list, e.g. `restaurant,cafe` |
| `groups` | comma list: transport, eat_drink, culture_sights, nature_leisure, shopping, accommodation, services, education, health, public |
| `min_confidence` | 0–99, drop low-confidence places |
| `limit` | 1–100, default 30 |
| `lang` | label language (en, hu, de…) |
| `mode=categories` | returns the full category tree with counts instead of places |
| `mode=area` | a neighbourhood summary (sights, food, essentials, travel times, night-sky quality, bathing water) |

Categories: charging, fuel, rail, transit, bar, cafe, restaurant, culture, landmark, library, sight, beach, park, playground, spa, sport, grocery, shop, lodging, bank, post, recycling, service, school, health, pharmacy, public.

Response: GeoJSON FeatureCollection, distance-sorted. `properties`: id, name, category, subcategory, group, address, distance_m, phone, email, website, opening_hours, cuisine, wheelchair, brand, wikidata, confidence, updated, sources, and `photo` (id, url, author, license, source_url) when available. Photos are served at `https://tilezza.eu/places/photo/{id}?key=YOUR_KEY` — show the author and licence next to them.

### Neighbourhood widget (one line, no code)
```html
<link rel="stylesheet" href="https://tilezza.eu/lib/tilezza-area-1.0.0.css"
      integrity="sha384-5LX0v7/DS4OZg+OcmN/0/5B8nH3UGGbB77i4f1EgXKI67biDOahvk0VpW2rlOQgJ" crossorigin="anonymous">
<div data-tilezza-area data-lat="47.1154" data-lon="14.1233" data-key="YOUR_KEY" data-lang="de"></div>
<script src="https://tilezza.eu/lib/tilezza-area-1.0.0.js"
        integrity="sha384-mWw/b8n8CqZOyxhyrpUSsfDvCTX6rvNij7suOz/8ouAdpxeR+OY6W5VOnteEs7il" crossorigin="anonymous" defer></script>
```

## 9. Plans, units and limits

Each request costs tile units: vector tile 1, raster tile 3, raster @2x 5, geocode 2, places 4, place photo 1, route 8.

| Plan | Units / month | Requests / s |
|---|---|---|
| Free | 100,000 | 15 |
| Starter | 150,000 | 30 |
| Pro | 500,000 | 100 |
| Scale | 5,000,000 | 500 |

The **free key covers vector tiles and style JSON only** (non-commercial). Raster tiles, @2x retina, geocoding, routing and places need a paid plan — contact info@digitaldynamics.hu. Rate limits are per account (all keys of an account share them) with a short burst allowance for map loads. Get a key: https://tilezza.eu/app.html

## 10. Errors and troubleshooting

| Response | Meaning | Fix |
|---|---|---|
| `403 {"error":"invalid_api_key"}` | key missing, mistyped or revoked | check the key |
| `403 {"error":"origin_not_allowed"}` | page's domain is not on the key's allowlist | add the domain to the key (dashboard / ask the owner); check Referrer-Policy is not `no-referrer` |
| `403 {"error":"plan_limit"}` | the plan does not include this service (e.g. raster on free) | use vector tiles or upgrade |
| `429 {"error":"rate_limit_exceeded"}` | too many requests per second | debounce type-ahead, cache API results |
| `429 {"error":"monthly_quota_exceeded"}` | monthly units used up | upgrade or wait for the next month |
| `400 {"error":"…"}` | bad parameters (missing lat/lon, bbox too large…) | read the message |

Checklist when the map is grey or empty:
1. Browser DevTools → Network → filter `tilezza`: tile requests should be 200.
2. A CSP error in the console → add tilezza.eu to the directives in rule 4.
3. 403 on `localhost` → localhost must be on the key's allowlist too.
4. Leaflet map with zero height → give the container an explicit height.
5. MapLibre centre is `[lon, lat]`, Leaflet is `[lat, lon]`.

## 11. Contact

info@digitaldynamics.hu · Digital Dynamics Kft., Hungary · https://tilezza.eu