Kolay Map

An elegant, auto-touring map of Kolay IK customers across Türkiye. Two pieces, zero infrastructure: a local Python script geocodes a customer Excel once, then a standalone HTML file renders it — no server, no build step, no live API calls from the map.

⚠️ Data policy: this repository contains code only. Customer spreadsheets must never be committed — .gitignore blocks all spreadsheet/export formats (*.xlsx, *.csv, *.json, data/, …). Keep it that way.

1. Geocode the customer Excel (one-time, local)

Input: an .xlsx with customer name, city, district and address columns. English (Company Name, City, District, Address) and Turkish (Firma Adı, İl, İlçe, Adres) headers are auto-detected.

pip install -r requirements.txt
python geocode.py customers.xlsx

This produces customers_geocoded.xlsx with added Latitude, Longitude and Geocode_Precision columns.

Notes:

• Uses free OpenStreetMap Nominatim — rate-limited to ~1 request/second, so large files take a while (a progress bar shows status).
• Addresses that can't be resolved fall back to district- then city-level coordinates; complete failures are left blank and logged.
• Interrupted? Re-run the script on the output file — already-geocoded rows are skipped automatically.

2. Open the map

Open map.html in any modern browser and upload (or drag & drop) the *_geocoded.xlsx file — once. The list is saved in the browser's localStorage on that device, so every later open goes straight to the map. Use the Update list button (bottom-left) to replace it with a new file.

• All customers are plotted as minimalist dot markers on a CartoDB Positron basemap.
• Every 10 seconds the map flies to a random customer, opens its popup and pulses the marker — ideal for an office screen.
• Use the Pause tour button (bottom-left) to stop/resume the loop.

Privacy & security

• The map is fully client-side. The uploaded Excel is parsed in the browser with SheetJS; customer data is never uploaded anywhere. The only network traffic is map tiles (CARTO), fonts (Google) and the pinned libraries below.
• The saved list lives in the browser's localStorage on the device where it was uploaded — not in this repo, not on any server. Clearing site data removes it.
• Geocoding is the one step that talks to a third party: geocode.py sends each address (not the customer name) to OpenStreetMap's Nominatim service. If that is not acceptable for your data, swap in a self-hosted Nominatim instance.
• CDN assets are SRI-pinned (Leaflet 1.9.4, SheetJS 0.20.3) — the browser refuses to run them if the CDN ever serves modified code.
• All rendered values are HTML-escaped, so a malicious spreadsheet cannot inject script into the page.