docs: skapa README för Open Map API-projektet

Co-authored-by: aider (anthropic/claude-sonnet-4-20250514) <[email protected]>

Author: irony

README.md

@@ -0,0 +1,318 @@
+# Open Map API
+
+En Google Maps API-kompatibel geocoding-, routing- och optimeringstjänst byggd med Node.js, Koa och TypeScript. API:et fungerar som en gateway för öppna kartdata-tjänster som Pelias, OSRM och VROOM.
+
+## 🌟 Funktioner
+
+- **Geocoding & Reverse Geocoding** - Konvertera adresser till koordinater och vice versa
+- **Directions** - Beräkna rutter och turn-by-turn navigering
+- **Distance Matrix** - Beräkna avstånd och restider mellan flera punkter
+- **Places Search** - Sök efter platser med text eller närhetssökning
+- **Autocomplete** - Förslag för adresser och platser
+- **Route Optimization** - VRP (Vehicle Routing Problem) och TSP (Traveling Salesman Problem)
+- **Google Maps API-kompatibel** - Drop-in replacement för många Google Maps API-anrop
+
+## 🏗️ Arkitektur
+
+API:et använder följande öppna tjänster:
+- **[Pelias](https://pelias.io/)** - Geocoding och platssökning
+- **[OSRM](http://project-osrm.org/)** - Routing och avståndsmätning
+- **[VROOM](http://vroom-project.org/)** - Ruttoptimering
+
+## 🚀 Snabbstart
+
+### Lokal utveckling
+
+```bash
+# Klona repositoriet
+git clone https://github.com/iteam/openmapapi.git
+cd openmapapi
+
+# Installera dependencies
+npm install
+
+# Kopiera miljövariabler
+cp .env.example .env
+
+# Starta utvecklingsservern
+npm run dev
+```
+
+API:et kommer att vara tillgängligt på `http://localhost:3000`
+
+### Docker
+
+```bash
+# Bygg Docker-image
+docker build -t openmaps-api .
+
+# Kör container
+docker run -p 3000:3000 openmaps-api
+```
+
+## 📚 API-dokumentation
+
+Interaktiv API-dokumentation finns tillgänglig på:
+- **Lokal utveckling**: http://localhost:3000
+- **Produktion**: https://openmaps.iteam.pub
+
+OpenAPI-specifikation: `/openapi.json`
+
+## 🔧 Användning
+
+### Geocoding
+
+Konvertera en adress till koordinater:
+
+```bash
+curl "https://openmaps.iteam.pub/maps/api/geocode/json?address=Drottninggatan+1,+Stockholm&key=your-api-key"
+```
+
+Reverse geocoding (koordinater till adress):
+
+```bash
+curl "https://openmaps.iteam.pub/maps/api/geocode/json?latlng=59.3293,18.0686&key=your-api-key"
+```
+
+### Directions
+
+Få vägbeskrivning mellan två punkter:
+
+```bash
+curl "https://openmaps.iteam.pub/maps/api/directions/json?origin=Stockholm+Central&destination=Gamla+Stan&key=your-api-key"
+```
+
+Med waypoints och alternativ:
+
+```bash
+curl "https://openmaps.iteam.pub/maps/api/directions/json?origin=Stockholm&destination=Göteborg&waypoints=Jönköping&alternatives=true&key=your-api-key"
+```
+
+### Distance Matrix
+
+Beräkna avstånd mellan flera punkter:
+
+```bash
+curl "https://openmaps.iteam.pub/maps/api/distancematrix/json?origins=Stockholm|Göteborg&destinations=Malmö|Uppsala&key=your-api-key"
+```
+
+### Places Search
+
+Textsökning efter platser:
+
+```bash
+curl "https://openmaps.iteam.pub/maps/api/place/textsearch/json?query=restauranger+i+Stockholm&key=your-api-key"
+```
+
+Närhetssökning:
+
+```bash
+curl "https://openmaps.iteam.pub/maps/api/place/nearbysearch/json?location=59.3293,18.0686&radius=1000&type=restaurant&key=your-api-key"
+```
+
+Autocomplete:
+
+```bash
+curl "https://openmaps.iteam.pub/maps/api/place/autocomplete/json?input=Drottning&key=your-api-key"
+```
+
+### Route Optimization
+
+Traveling Salesman Problem (TSP):
+
+```bash
+curl -X POST "https://openmaps.iteam.pub/api/optimization/tsp" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "locations": [[18.0686, 59.3293], [18.0696, 59.3303], [18.0706, 59.3313]],
+    "start": 0,
+    "profile": "driving"
+  }'
+```
+
+Vehicle Routing Problem (VRP):
+
+```bash
+curl -X POST "https://openmaps.iteam.pub/api/optimization/vrp" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jobs": [
+      {"id": 1, "location": [18.0686, 59.3293], "delivery": [10]},
+      {"id": 2, "location": [18.0696, 59.3303], "delivery": [15]}
+    ],
+    "vehicles": [
+      {"id": 1, "start": [18.0676, 59.3283], "capacity": [50]}
+    ]
+  }'
+```
+
+## 🌍 JavaScript/TypeScript Exempel
+
+### Fetch API
+
+```javascript
+// Geocoding
+const geocodeResponse = await fetch(
+  'https://openmaps.iteam.pub/maps/api/geocode/json?address=Stockholm&key=your-api-key'
+);
+const geocodeData = await geocodeResponse.json();
+console.log(geocodeData.results[0].geometry.location);
+
+// Directions
+const directionsResponse = await fetch(
+  'https://openmaps.iteam.pub/maps/api/directions/json?origin=Stockholm&destination=Göteborg&key=your-api-key'
+);
+const directionsData = await directionsResponse.json();
+console.log(directionsData.routes[0].legs[0].duration.text);
+```
+
+### Axios
+
+```javascript
+import axios from 'axios';
+
+const api = axios.create({
+  baseURL: 'https://openmaps.iteam.pub',
+  params: {
+    key: 'your-api-key'
+  }
+});
+
+// Geocoding
+const geocode = await api.get('/maps/api/geocode/json', {
+  params: { address: 'Drottninggatan 1, Stockholm' }
+});
+
+// Places search
+const places = await api.get('/maps/api/place/textsearch/json', {
+  params: { query: 'restauranger i Stockholm' }
+});
+
+// Route optimization
+const optimization = await api.post('/api/optimization/tsp', {
+  locations: [[18.0686, 59.3293], [18.0696, 59.3303]],
+  start: 0
+});
+```
+
+## 🔑 API-nycklar
+
+För närvarande accepterar API:et vilken sträng som helst som API-nyckel. I produktion bör du implementera riktig autentisering.
+
+## 🏃‍♂️ Prestanda
+
+- **Caching**: Implementera Redis för att cacha vanliga förfrågningar
+- **Rate Limiting**: Nginx ingress har rate limiting konfigurerat (100 req/min)
+- **Horizontal Scaling**: HPA konfigurerat för automatisk skalning baserat på CPU/minne
+
+## 🔧 Konfiguration
+
+Miljövariabler:
+
+```bash
+# Server
+PORT=3000
+NODE_ENV=production
+API_BASE_URL=https://openmaps.iteam.pub
+
+# Externa tjänster
+PELIAS_BASE_URL=https://pelias.telge.iteam.pub/v1
+OSRM_BASE_URL=https://osrm.telge.iteam.pub
+VROOM_BASE_URL=https://vroom.telge.iteam.pub
+```
+
+## 🚢 Deployment
+
+### Kubernetes med FluxCD
+
+Projektet är konfigurerat för deployment med FluxCD. Peka FluxCD på detta repository så kommer det automatiskt att deploya:
+
+- Namespace: `openmaps`
+- Deployment med 2 replicas
+- Service på port 80
+- Ingress med TLS (Let's Encrypt)
+- HPA för autoskalning
+- ConfigMap för miljövariabler
+
+### GitHub Actions
+
+Automatisk CI/CD pipeline som:
+- Bygger och testar koden
+- Skapar Docker-image
+- Pushar till GitHub Container Registry (GHCR)
+- Taggar med branch och SHA
+
+## 🛠️ Utveckling
+
+### Projektstruktur
+
+```
+src/
+├── adapters/       # HTTP request/response hantering
+├── config/         # Konfiguration och externa klienter
+├── middleware/     # Request validering och preprocessing
+├── routes/         # Route definitioner och Swagger docs
+├── schemas/        # Zod schemas och TypeScript types
+└── services/       # Affärslogik och dataåtkomst
+```
+
+### Lägga till nya endpoints
+
+1. Definiera schema i `src/schemas/`
+2. Implementera service i `src/services/`
+3. Skapa adapter i `src/adapters/`
+4. Lägg till routes i `src/routes/`
+5. Registrera schema för OpenAPI-dokumentation
+
+### Kodstil
+
+- **TypeScript** för typsäkerhet
+- **Zod** för runtime-validering
+- **Funktionell programmering** - använd map/reduce istället för loopar
+- **Engelska** för all kod, kommentarer och dokumentation
+- **Centraliserad felhantering** - kasta typade fel, middleware hanterar formatering
+
+## 🧪 Testning
+
+```bash
+# Kör tester (när de implementeras)
+npm test
+
+# Bygg projektet
+npm run build
+
+# Starta produktionsserver
+npm start
+```
+
+## 📊 Monitoring
+
+- **Health Check**: `/health` endpoint
+- **Metrics**: Kubernetes liveness/readiness probes
+- **Logging**: Strukturerad loggning till stdout
+
+## 🤝 Bidrag
+
+1. Forka repositoriet
+2. Skapa en feature branch
+3. Gör dina ändringar
+4. Lägg till tester
+5. Skicka en pull request
+
+## 📄 Licens
+
+ISC License
+
+## 🔗 Relaterade projekt
+
+- [Pelias Geocoder](https://github.com/pelias/pelias)
+- [OSRM Backend](https://github.com/Project-OSRM/osrm-backend)
+- [VROOM](https://github.com/VROOM-Project/vroom)
+
+## 📞 Support
+
+För frågor och support, skapa en issue i detta repository.
+
+---
+
+**Byggd med ❤️ av Iteam**