# 📋 Ejemplos de Uso - Routes API

Este documento contiene ejemplos detallados de requests y responses para todos los endpoints disponibles en Routes API.

**Autenticación:** Todos los endpoints requieren el header `x-api-key` con una clave en formato `keyId.secret` (obtenida desde el backoffice). Sin ella se responde 401.

---

## 📍 GET /geocode

**Request:**

```http
GET /geocode?address=Av. Corrientes 1000, Buenos Aires, Argentina&country=AR
```

**Response:**

```json
{
  "lat": -34.6037,
  "lng": -58.3816,
  "formattedAddress": "Av. Corrientes 1000, C1043 CABA, Argentina",
  "accuracy": "rooftop"
}
```

---

## 🔄 GET /reverseGeocode

**Request:**

```http
GET /reverseGeocode?lat=-34.6037&lng=-58.3816
```

**Response:**

```json
{
  "formattedAddress": "Av. Corrientes 1000, C1043 CABA, Argentina",
  "address": {
    "streetNumber": "1000",
    "route": "Av. Corrientes",
    "neighborhood": "",
    "locality": "",
    "city": "Buenos Aires",
    "state": "Buenos Aires",
    "stateIsoCode": "AR-C",
    "country": { "name": "Argentina", "code": "AR" },
    "postalCode": "C1043"
  },
  "location": { "lat": -34.6037, "lng": -58.3816 },
  "placeId": "ChIJd7zN_thvQw0Rj-4lIEn4aR8",
  "timezone": "America/Argentina/Buenos_Aires",
  "metadata": {
    "locationType": "ROOFTOP",
    "types": ["street_address"]
  }
}
```

---

## 📏 POST /distance

**Request:**

```json
{
  "origin": "Plaza de Mayo, Buenos Aires, Argentina",
  "destination": "Aeropuerto de Ezeiza, Buenos Aires, Argentina",
  "wayPoints": [
    {
      "address": "Avenida Medrano 333, Buenos Aires, Argentina"
    },
    {
      "address": "Avenida La Playa 1750, Buenos Aires, Argentina"
    }
  ],
  "vehicleType": "van",
  "preferences": {
    "avoidTolls": false,
    "avoidHighways": false,
    "departureTime": "2025-02-20T08:00:00"
  }
}
```

**Response:**

```json
{
  "distanceMeters": 45200,
  "distanceKilometers": 45.2,
  "estimatedTimeMinutes": 60,
  "estimatedTimeWithTrafficMinutes": 65,
  "wayPoints": [
    {
      "distanceMeters": 2100,
      "distanceKilometers": 2.1,
      "estimatedTimeMinutes": 3,
      "estimatedTimeWithTrafficMinutes": 4
    },
    {
      "distanceMeters": 8500,
      "distanceKilometers": 8.5,
      "estimatedTimeMinutes": 10,
      "estimatedTimeWithTrafficMinutes": 12
    },
    {
      "distanceMeters": 34600,
      "distanceKilometers": 34.6,
      "estimatedTimeMinutes": 47,
      "estimatedTimeWithTrafficMinutes": 52
    }
  ],
  "warnings": [
    {
      "code": "WARNING_ESTIMATED_TRAVEL_TIME_MAY_VARY_TO_LONG",
      "message": "The estimated travel time may vary due to long distances."
    }
  ]
}
```

---

## 🔍 GET /autocomplete

**Request:**

```http
GET /autocomplete?query=Obel&language=es&types=address&country=AR&state=BuenosAires&city=BuenosAires&zone=Centro&limit=5
```

**Response:**

```json
{
  "predictions": [
    {
      "placeId": "ChIJN1t_tDeuEmsRUsoyG83frY4",
      "description": "Obelisco de Buenos Aires, Avenida 9 de Julio, Buenos Aires, Argentina",
      "types": ["tourist_attraction", "point_of_interest"],
      "location": { "lat": -34.6037, "lng": -58.3816 }
    },
    {
      "placeId": "ChIJN1t_tDeuEmsRUsoyG83frY4",
      "description": "Obelisco, Avenida 9 de Julio, Buenos Aires, Argentina",
      "types": ["establishment"],
      "location": { "lat": -34.6037, "lng": -58.3816 }
    }
  ],
  "status": "OK"
}
```

---

## 🛣️ POST /directions

**Request:**

```json
{
  "origin": "Plaza de Mayo, Buenos Aires, Argentina",
  "destination": "Aeropuerto de Ezeiza, Buenos Aires, Argentina",
  "vehicleType": "van",
  "preferences": {
    "avoidTolls": false,
    "avoidHighways": false,
    "departureTime": "2025-02-20T08:00:00",
    "polylineFormat": "geoJSON",
    "avoidSteps": false
  }
}
```

**Response:**

```json
{
  "distanceMeters": 45200,
  "distanceKilometers": 45.2,
  "estimatedTimeMinutes": 60,
  "polyline": {
    "type": "LineString",
    "coordinates": [
      [-58.3816, -34.6037],
      [-58.3826, -34.6137],
      [-58.3927, -34.6038]
    ]
  },
  "steps": [
    {
      "instruction": "Dirígete hacia el sur por Avenida de Mayo",
      "distanceMeters": 200,
      "durationSeconds": 60,
      "startLocation": { "lat": -34.6037, "lng": -58.3816 },
      "endLocation": { "lat": -34.6137, "lng": -58.3826 }
    },
    {
      "instruction": "Gira a la derecha hacia Avenida 9 de Julio",
      "distanceMeters": 1800,
      "durationSeconds": 120,
      "startLocation": { "lat": -34.6137, "lng": -58.3826 },
      "endLocation": { "lat": -34.6038, "lng": -58.3927 }
    }
  ],
  "warnings": [
    {
      "code": "WARNING_ESTIMATED_TRAVEL_TIME_MAY_VARY_DUE_TO_DISTANCE",
      "message": "The estimated travel time may vary due to long distances."
    }
  ]
}
```

**Nota**: El campo `polyline` puede devolverse en diferentes formatos según el parámetro `preferences.polylineFormat`:

- `geoJSON` (default): Objeto GeoJSON con formato `{type: "LineString", coordinates: [[lng, lat], ...]}`
- `encoded`: String codificado del polyline
- `polyline6`: String codificado en formato polyline6

---

## 🚚 POST /routing

**Request:**

```json
{
  "origin": "Puerto de Buenos Aires, Argentina",
  "destination": "Centro Logístico de Ezeiza, Argentina",
  "vehicleType": "truck",
  "constraints": {
    "maxHeight": 4.2,
    "maxWeight": 20000,
    "avoid_narrow_streets": true,
    "avoid_low_bridges": true,
    "prefer_highways": true
  },
  "wayPoints": [
    {
      "address": "Autopista Buenos Aires - La Plata, Buenos Aires, Argentina"
    }
  ]
}
```

**Response:**

```json
{
  "totalDistance": 52.8,
  "totalDuration": 4200,
  "route": [
    {
      "origin": "Puerto de Buenos Aires, Argentina",
      "destination": "Autopista Buenos Aires - La Plata, Buenos Aires, Argentina",
      "distance": 8.2,
      "duration": 600,
      "restrictions": ["avoid_narrow_streets"]
    },
    {
      "origin": "Autopista Buenos Aires - La Plata, Buenos Aires, Argentina",
      "destination": "Centro Logístico de Ezeiza, Argentina",
      "distance": 44.6,
      "duration": 3600,
      "restrictions": ["prefer_highways", "avoid_low_bridges"]
    }
  ],
  "warnings": [
    {
      "code": "WARNING_ROUTE_ISSUE",
      "message": "Ruta optimizada para vehículos pesados. Se evitaron calles angostas y puentes bajos."
    }
  ]
}
```

🔹 **Estado**: 🚧 **Pendiente de desarrollo**

---

## 📚 Recursos Adicionales

- [Documentación de Arquitectura](architecture/architecture.md) — Estructura técnica y flujo de datos
- [Especificación OpenAPI](openapi.yaml) — Documentación técnica completa de la API
- [Tests HTTP](../http-tests/) — Ejemplos de requests para probar los endpoints