openapi: 3.1.0
info:
  title: Traffic
  description: 'Este API es parte de **Transcend** y corresponde con el módulo de
    tráfico, para consultar información en tiempo real sobre eventos de tráfico, radares,
    puntos negros y flujo de tráfico en carreteras del sector logístico.


    **¿Para qué sirve?**

    - Consultar eventos de tráfico actuales (accidentes, cierres de carretera, eventos
    especiales)

    - Localizar radares fijos y móviles en rutas específicas

    - Identificar puntos negros (zonas de alta peligrosidad)

    - Calcular isocronas (áreas alcanzables en tiempo determinado)

    - Obtener información de flujo de tráfico en tiempo real


    **Casos de uso típicos:**

    - Planificación de rutas seguras para transporte de mercancías

    - Evitación de zonas de alto riesgo y congestión

    - Optimización de tiempos de entrega

    - Gestión de flotas en tiempo real


    **Ejemplo práctico:**

    ```

    Un transportista necesita planificar una ruta desde Madrid a Barcelona.

    Usa este API para:

    1. Consultar eventos de tráfico en la ruta

    2. Identificar radares y puntos negros

    3. Verificar el flujo de tráfico actual

    4. Calcular áreas alcanzables en diferentes tiempos

    ```

    '
  version: 1.0.0
  contact:
    email: support@cargoffer.com
  license: Private API - Access by agreement only
servers:
- url: https://api.pro.cargoffer.com
  description: Producción
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Token JWT para autenticación
  schemas:
    Coordinates:
      type: object
      properties:
        lat:
          $ref: '#/components/schemas/Latitude'
        lon:
          $ref: '#/components/schemas/Longitude'
      required:
      - lat
      - lon
    Latitude:
      type: number
      format: float
      minimum: -90
      maximum: 90
      description: 'Coordenada de latitud geográfica en grados decimales (estándar
        WGS84)


        **Ejemplos:**

        - Madrid: 40.4168

        - Barcelona: 41.3851

        - Valencia: 39.4699

        '
      example: 40.4168
    Longitude:
      type: number
      format: float
      minimum: -180
      maximum: 180
      description: 'Coordenada de longitud geográfica en grados decimales (estándar
        WGS84)


        **Ejemplos:**

        - Madrid: -3.7038

        - Barcelona: 2.1734

        - Valencia: -0.3763

        '
      example: -3.7038
    Radius:
      type: number
      minimum: 1000
      maximum: 25000
      default: 25000
      description: 'Radio de búsqueda en metros desde el punto central


        **Escalas típicas:**

        - 1.000m: Área muy localizada (una intersección)

        - 5.000m: Barrio o zona urbana

        - 10.000m: Distrito o área metropolitana pequeña

        - 25.000m: Ciudad mediana o área extensa

        '
    BlackSpot:
      type: object
      properties:
        id:
          type: string
          description: Identificador único del punto negro
        coordinates:
          $ref: '#/components/schemas/Coordinates'
        dangerLevel:
          type: number
          minimum: 0
          maximum: 100
          description: Nivel de peligrosidad (0-100)
        description:
          type: string
          description: Descripción del punto negro
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
      - id
      - coordinates
      - dangerLevel
    Isochrone:
      type: object
      properties:
        id:
          type: string
          description: Identificador único de la isócrona
        center:
          $ref: '#/components/schemas/Coordinates'
        travelTime:
          type: number
          description: Tiempo de viaje en minutos
        polygon:
          type: array
          items:
            $ref: '#/components/schemas/Coordinates'
          description: Polígono que define el área alcanzable
        createdAt:
          type: string
          format: date-time
      required:
      - id
      - center
      - travelTime
      - polygon
    Language:
      type: string
      enum:
      - es
      - en
      - fr
      - de
      - pt
      default: es
      description: 'Idioma para los datos de respuesta


        **Idiomas disponibles:**

        - `es`: Español (predeterminado)

        - `en`: Inglés

        - `fr`: Francés

        - `de`: Alemán

        - `pt`: Portugués


        **Ejemplo de uso:**

        ```

        GET /events/nearby?lat=40.4168&lng=-3.7038&lang=en

        ```

        '
    TrafficEvent:
      type: object
      properties:
        id:
          type: string
          description: Identificador único del evento
        type:
          type: string
          enum:
          - ACCIDENT
          - ROAD_CLOSURE
          - SPECIAL_EVENT
          description: Tipo de evento de tráfico
        location:
          $ref: '#/components/schemas/Coordinates'
        severity:
          type: number
          minimum: 0
          maximum: 100
          description: Nivel de severidad (0-100)
        expectedDuration:
          type: number
          description: Duración esperada en minutos
        affectedVehicleTypes:
          type: array
          items:
            type: string
          description: Tipos de vehículos afectados por este evento
        createdAt:
          type: string
          format: date-time
          description: Cuando se creó el evento
        updatedAt:
          type: string
          format: date-time
          description: Cuando se actualizó el evento por última vez
      required:
      - id
      - type
      - location
      - severity
      - expectedDuration
      - affectedVehicleTypes
    RoadRestriction:
      type: object
      properties:
        roadId:
          type: string
          description: Identificador de la carretera afectada
        restrictionType:
          type: string
          enum:
          - WEIGHT
          - HEIGHT
          - ENVIRONMENTAL
          - TIME
          description: Tipo de restricción
        value:
          type:
            oneOf:
            - type: number
            - type: string
          description: Valor de la restricción (numérico o descriptivo)
        schedule:
          type: object
          properties:
            days:
              type: array
              items:
                type: number
                minimum: 0
                maximum: 6
              description: Días de la semana cuando aplica la restricción (0=Domingo)
            hours:
              type: string
              description: Rango de tiempo cuando aplica la restricción
          description: Horario para restricciones basadas en tiempo
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
      - roadId
      - restrictionType
      - value
    Radar:
      type: object
      properties:
        id:
          type: string
          description: Identificador único del radar
        adminName2:
          type: string
          description: Nombre del área administrativa
        roadName:
          type: string
          description: Nombre de la carretera donde se encuentra el radar
        type:
          type: string
          enum:
          - MOBILE
          - FIXED
          description: Tipo de radar
        sense:
          type: string
          enum:
          - UNKNOWN
          - POSITIVE
          - NEGATIVE
          - BOTH
          description: Sentido de dirección del radar
        kilometers:
          type: number
          description: Punto kilométrico donde se encuentra el radar
        maxSpeed:
          type: number
          description: Límite de velocidad en km/h
        location:
          $ref: '#/components/schemas/Coordinates'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
      - id
      - adminName2
      - roadName
      - type
      - sense
      - location
    TrafficFlowData:
      type: object
      properties:
        speed_current:
          type: number
          description: Velocidad actual en km/h
        speed_normal:
          type: number
          description: Velocidad normal/flujo libre en km/h
        time_current:
          type: number
          description: Tiempo de viaje actual en segundos
        time_normal:
          type: number
          description: Tiempo de viaje normal en segundos
        roadClosure:
          type: boolean
          description: Si la carretera está cerrada
        polyline:
          type: string
          description: Polilínea codificada para el segmento de carretera
    SearchResponse:
      type: object
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/TrafficEvent'
          description: Eventos de tráfico encontrados en el área de búsqueda
        radars:
          type: array
          items:
            $ref: '#/components/schemas/Radar'
          description: Radares encontrados en el área de búsqueda
      required:
      - events
      - radars
      description: Resultados combinados de búsqueda para eventos y radares
  parameters:
    Latitude:
      name: lat
      in: query
      schema:
        $ref: '#/components/schemas/Latitude'
      required: true
      description: Coordenada de latitud geográfica
    Longitude:
      name: lon
      in: query
      schema:
        $ref: '#/components/schemas/Longitude'
      required: true
      description: Coordenada de longitud geográfica
    Radius:
      name: radius
      in: query
      schema:
        $ref: '#/components/schemas/Radius'
      description: Radio de búsqueda en metros
    Language:
      name: lang
      in: query
      schema:
        $ref: '#/components/schemas/Language'
      description: Idioma para los datos de respuesta
    EventType:
      name: type
      in: path
      schema:
        type: string
        enum:
        - ACCIDENT
        - ROAD_CLOSURE
        - SPECIAL_EVENT
      required: true
      description: Tipo de evento de tráfico
paths:
  /blackspots/area:
    get:
      tags:
      - Blackspots
      summary: Obtener puntos negros en un área
      description: 'Recupera puntos negros (lugares con alto nivel de peligrosidad)
        dentro de un área específica.


        **Ejemplo de uso:**

        ```

        GET /blackspots/area?lat=40.4168&lng=-3.7038&radius=5000&minDangerLevel=50

        ```


        Este endpoint es útil para identificar zonas de alto riesgo en rutas logísticas.

        '
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/Latitude'
      - $ref: '#/components/parameters/Longitude'
      - $ref: '#/components/parameters/Radius'
      - name: minDangerLevel
        in: query
        schema:
          type: number
          minimum: 0
          maximum: 100
          default: 50
        description: Nivel mínimo de peligrosidad para filtrar (0-100)
      responses:
        '200':
          description: Lista de puntos negros en el área
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BlackSpot'
              examples:
                ejemplo_exitoso:
                  summary: Puntos negros encontrados
                  value:
                  - id: bs_12345
                    coordinates:
                      lat: 40.4168
                      lon: -3.7038
                    dangerLevel: 75
                    description: Intersección con alta tasa de accidentes
                    createdAt: '2024-01-15T10:30:00Z'
                    updatedAt: '2024-01-15T10:30:00Z'
        '400':
          description: Parámetros inválidos
        '401':
          description: No autorizado
        '500':
          description: Error interno del servidor
  /blackspots/path:
    post:
      tags:
      - Blackspots
      summary: Obtener puntos negros a lo largo de una ruta
      description: "Identifica puntos negros a lo largo de una ruta específica, calculando\
        \ el nivel de peligrosidad para cada segmento.\n\n**Ejemplo de uso:**\n```json\n\
        POST /blackspots/path\n{\n  \"points\": [\n    [-3.7038, 40.4168],\n    [-3.7138,\
        \ 40.4268]\n  ],\n  \"minDangerLevel\": 50\n}\n```\n"
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                points:
                  type: array
                  items:
                    type: array
                    items:
                      type: number
                    minItems: 2
                    maxItems: 2
                  minItems: 2
                  description: Array de pares de coordenadas [longitud, latitud]
                minDangerLevel:
                  type: number
                  minimum: 0
                  maximum: 100
                  default: 50
                  description: Nivel mínimo de peligrosidad para filtrar
              required:
              - points
      responses:
        '200':
          description: Puntos negros encontrados a lo largo de la ruta
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BlackSpot'
        '400':
          description: Ruta inválida o parámetros incorrectos
        '401':
          description: No autorizado
        '500':
          description: Error interno del servidor
  /events/historical:
    get:
      tags:
      - Events
      summary: Consultar eventos de tráfico históricos
      description: 'Recupera eventos de tráfico que ocurrieron en un rango de fechas
        específico.


        **Ejemplo de uso:**

        ```

        GET /events/historical?from=2024-01-01&to=2024-01-31&lat=40.4168&lng=-3.7038&radius=10000

        ```


        **Casos de uso:**

        - Análisis de patrones de tráfico en fechas pasadas

        - Investigación de incidentes ocurridos

        - Planificación basada en datos históricos


        **Parámetros importantes:**

        - `from` y `to`: Fechas en formato YYYY-MM-DD

        - `lat` y `lng`: Opcionales para filtrar por ubicación

        - `radius`: Radio de búsqueda cuando se especifica ubicación

        '
      security:
      - bearerAuth: []
      parameters:
      - name: from
        in: query
        required: true
        schema:
          type: string
          format: date
        description: Fecha de inicio del rango (YYYY-MM-DD)
      - name: to
        in: query
        required: true
        schema:
          type: string
          format: date
        description: Fecha de fin del rango (YYYY-MM-DD)
      - $ref: '#/components/parameters/Latitude'
      - $ref: '#/components/parameters/Longitude'
      - $ref: '#/components/parameters/Radius'
      responses:
        '200':
          description: Lista de eventos de tráfico históricos
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TrafficEvent'
              examples:
                ejemplo_historico:
                  summary: Eventos históricos encontrados
                  value:
                  - id: evt_12345
                    type: ACCIDENT
                    location:
                      lat: 40.4168
                      lon: -3.7038
                    severity: 75
                    expectedDuration: 120
                    affectedVehicleTypes:
                    - CAR
                    - TRUCK
                    createdAt: '2024-01-15T10:30:00Z'
                    updatedAt: '2024-01-15T12:30:00Z'
        '400':
          description: Parámetros inválidos
        '401':
          description: No autorizado
        '500':
          description: Error interno del servidor
  /events/type/{type}:
    get:
      tags:
      - Events
      summary: Consultar eventos por tipo específico
      description: 'Filtra eventos de tráfico por categoría específica (accidente,
        cierre de carretera, evento especial).


        **Tipos disponibles:**

        - `ACCIDENT`: Accidentes de tráfico

        - `ROAD_CLOSURE`: Cierres de carretera

        - `SPECIAL_EVENT`: Eventos especiales (conciertos, manifestaciones, etc.)


        **Ejemplo de uso:**

        ```

        GET /events/type/ACCIDENT?lat=40.4168&lng=-3.7038&radius=5000

        ```


        **Escenario típico:**

        Un gestor de flota quiere evitar zonas con accidentes recientes para sus vehículos.

        '
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/EventType'
      - $ref: '#/components/parameters/Latitude'
      - $ref: '#/components/parameters/Longitude'
      - $ref: '#/components/parameters/Radius'
      responses:
        '200':
          description: Lista de eventos del tipo especificado
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TrafficEvent'
              examples:
                ejemplo_por_tipo:
                  summary: Eventos filtrados por tipo
                  value:
                  - id: evt_67890
                    type: ROAD_CLOSURE
                    location:
                      lat: 41.3851
                      lon: 2.1734
                    severity: 90
                    expectedDuration: 180
                    affectedVehicleTypes:
                    - ALL
                    createdAt: '2024-01-15T14:20:00Z'
                    updatedAt: '2024-01-15T14:20:00Z'
        '400':
          description: Parámetros inválidos
        '401':
          description: No autorizado
        '500':
          description: Error interno del servidor
  /events:
    get:
      tags:
      - Events
      summary: Consultar eventos de tráfico actuales
      description: 'Obtiene eventos de tráfico en tiempo real cerca de una ubicación,
        con opciones de filtrado avanzado.


        **Ejemplo de uso completo:**

        ```

        GET /events?lat=40.4168&lng=-3.7038&radius=10000&types[]=ACCIDENT&types[]=ROAD_CLOSURE&minSeverity=30&vehicleTypes[]=TRUCK&lang=es

        ```


        **Filtros disponibles:**

        - `types`: Tipos de eventos a incluir

        - `minSeverity`: Severidad mínima (0-100)

        - `vehicleTypes`: Tipos de vehículos afectados

        - `lang`: Idioma de la respuesta


        **Ejemplo práctico:**

        Una empresa de logística filtra solo eventos que afecten a camiones con severidad
        alta.

        '
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/Latitude'
      - $ref: '#/components/parameters/Longitude'
      - $ref: '#/components/parameters/Radius'
      - name: types
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - ACCIDENT
            - ROAD_CLOSURE
            - SPECIAL_EVENT
        description: Tipos de eventos a incluir en la búsqueda
      - name: minSeverity
        in: query
        schema:
          type: number
          minimum: 0
          maximum: 100
        description: Severidad mínima del evento (0-100)
      - name: vehicleTypes
        in: query
        schema:
          type: array
          items:
            type: string
        description: Tipos de vehículos afectados por el evento
      - $ref: '#/components/parameters/Language'
      responses:
        '200':
          description: Lista de eventos de tráfico actuales
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TrafficEvent'
              examples:
                eventos_actuales:
                  summary: Eventos actuales encontrados
                  value:
                  - id: evt_11111
                    type: SPECIAL_EVENT
                    location:
                      lat: 40.4168
                      lon: -3.7038
                    severity: 60
                    expectedDuration: 240
                    affectedVehicleTypes:
                    - CAR
                    - BUS
                    createdAt: '2024-01-15T16:00:00Z'
                    updatedAt: '2024-01-15T16:00:00Z'
        '400':
          description: Parámetros inválidos
        '401':
          description: No autorizado
        '500':
          description: Error interno del servidor
  /events/all:
    get:
      tags:
      - Events
      summary: Consultar todos los eventos de tráfico
      description: 'Recupera todos los eventos de tráfico disponibles sin filtros
        de ubicación.


        **Advertencia:** Este endpoint puede devolver grandes volúmenes de datos.


        **Ejemplo de uso:**

        ```

        GET /events/all

        ```


        **Casos de uso:**

        - Dashboards de monitorización general

        - Análisis global del estado del tráfico

        - Sistemas que necesitan datos completos sin filtros

        '
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Lista completa de eventos de tráfico
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TrafficEvent'
              examples:
                todos_eventos:
                  summary: Todos los eventos disponibles
                  value:
                  - id: evt_22222
                    type: ACCIDENT
                    location:
                      lat: 39.4699
                      lon: -0.3763
                    severity: 85
                    expectedDuration: 90
                    affectedVehicleTypes:
                    - TRUCK
                    - CAR
                    createdAt: '2024-01-15T17:30:00Z'
                    updatedAt: '2024-01-15T17:30:00Z'
                  - id: evt_33333
                    type: ROAD_CLOSURE
                    location:
                      lat: 41.3851
                      lon: 2.1734
                    severity: 95
                    expectedDuration: 360
                    affectedVehicleTypes:
                    - ALL
                    createdAt: '2024-01-15T18:00:00Z'
                    updatedAt: '2024-01-15T18:00:00Z'
        '401':
          description: No autorizado
        '500':
          description: Error interno del servidor
  /events/nearby:
    get:
      tags:
      - Events
      summary: Consultar eventos cercanos
      description: 'Versión simplificada para obtener eventos cerca de una ubicación
        sin filtros complejos.


        **Ejemplo de uso rápido:**

        ```

        GET /events/nearby?lat=40.4168&lng=-3.7038&radius=5000&lang=es

        ```


        **Diferencia con /events:**

        - Menos parámetros de filtrado

        - Más rápido para consultas simples

        - Ideal para aplicaciones móviles con necesidades básicas

        '
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/Latitude'
      - $ref: '#/components/parameters/Longitude'
      - $ref: '#/components/parameters/Radius'
      - $ref: '#/components/parameters/Language'
      responses:
        '200':
          description: Lista de eventos cercanos
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TrafficEvent'
              examples:
                eventos_cercanos:
                  summary: Eventos cercanos encontrados
                  value:
                  - id: evt_44444
                    type: ACCIDENT
                    location:
                      lat: 40.4268
                      lon: -3.7138
                    severity: 70
                    expectedDuration: 60
                    affectedVehicleTypes:
                    - CAR
                    createdAt: '2024-01-15T19:00:00Z'
                    updatedAt: '2024-01-15T19:00:00Z'
        '400':
          description: Parámetros inválidos
        '401':
          description: No autorizado
        '500':
          description: Error interno del servidor
  /events/getAlongPath:
    post:
      tags:
      - Events
      summary: Consultar eventos a lo largo de una ruta
      description: "Identifica eventos de tráfico a lo largo de una ruta específica\
        \ definida por puntos GPS.\n\n**Ejemplo de uso:**\n```json\nPOST /events/getAlongPath\n\
        {\n  \"points\": [\n    [-3.7038, 40.4168],  // Madrid\n    [-2.1734, 41.3851],\
        \  // Barcelona\n    [-0.3763, 39.4699]   // Valencia\n  ],\n  \"lang\": \"\
        es\"\n}\n```\n\n**Características:**\n- Optimizado para rutas largas\n- Filtra\
        \ puntos cada 15km para eficiencia\n- Elimina duplicados automáticamente\n\
        \n**Uso en navegación:**\nIdeal para aplicaciones de navegación que necesitan\
        \ alertas de tráfico en ruta.\n"
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                points:
                  type: array
                  items:
                    type: array
                    items:
                      type: number
                    minItems: 2
                    maxItems: 2
                  minItems: 2
                  description: Array de pares de coordenadas [longitud, latitud]
                lang:
                  type: string
                  enum:
                  - es
                  - en
                  - fr
                  - de
                  - pt
                  default: es
                  description: Idioma para los datos de respuesta
              required:
              - points
      responses:
        '200':
          description: Eventos encontrados a lo largo de la ruta
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TrafficEvent'
              examples:
                eventos_ruta:
                  summary: Eventos a lo largo de la ruta
                  value:
                  - id: evt_55555
                    type: ROAD_CLOSURE
                    location:
                      lat: 40.4168
                      lon: -3.7038
                    severity: 80
                    expectedDuration: 180
                    affectedVehicleTypes:
                    - TRUCK
                    - BUS
                    createdAt: '2024-01-15T20:00:00Z'
                    updatedAt: '2024-01-15T20:00:00Z'
        '400':
          description: Ruta inválida
        '401':
          description: No autorizado
        '500':
          description: Error interno del servidor
  /events/isochrone:
    post:
      tags:
      - Events
      summary: Calcular isocronas para una ruta
      description: "Calcula áreas alcanzables (isocronas) desde puntos específicos\
        \ a lo largo de una ruta en un tiempo determinado.\n\n**Ejemplo de uso:**\n\
        ```json\nPOST /events/isochrone\n{\n  \"points\": [\n    [-3.7038, 40.4168],\n\
        \    [-3.7138, 40.4268],\n    [-3.7238, 40.4368]\n  ]\n}\n```\n\nÚtil para\
        \ planificar rutas y determinar áreas de cobertura en tiempo real.\n"
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                points:
                  type: array
                  items:
                    type: array
                    items:
                      type: number
                    minItems: 2
                    maxItems: 2
                  minItems: 2
                  description: Array de pares de coordenadas [longitud, latitud] que
                    definen la ruta
              required:
              - points
      responses:
        '200':
          description: Isocronas calculadas para la ruta
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Isochrone'
              examples:
                ejemplo_isocronas:
                  summary: Isocronas calculadas
                  value:
                  - id: iso_12345
                    center:
                      lat: 40.4168
                      lon: -3.7038
                    travelTime: 30
                    polygon:
                    - lat: 40.4268
                      lon: -3.6938
                    - lat: 40.4068
                      lon: -3.6938
                    - lat: 40.4068
                      lon: -3.7138
                    - lat: 40.4268
                      lon: -3.7138
                    createdAt: '2024-01-15T10:30:00Z'
        '400':
          description: Ruta inválida o parámetros incorrectos
        '401':
          description: No autorizado
        '500':
          description: Error interno del servidor
  /radar/nearby:
    get:
      tags:
      - Radars
      summary: Get nearby radars
      description: Retrieve radar information near a location
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/Latitude'
      - $ref: '#/components/parameters/Longitude'
      - $ref: '#/components/parameters/Radius'
      - $ref: '#/components/parameters/Language'
      responses:
        '200':
          description: List of nearby radars
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Radar'
        '400':
          description: Invalid parameters
        '401':
          description: Unauthorized
        '500':
          description: Internal server error
  /radar/getAlongPath:
    post:
      tags:
      - Radars
      summary: Get radars along a path
      description: Retrieve radar information along a specified route
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                points:
                  type: array
                  items:
                    type: array
                    items:
                      type: number
                    minItems: 2
                    maxItems: 2
                  minItems: 2
                  description: Array of coordinate pairs [longitude, latitude]
                lang:
                  type: string
                  enum:
                  - es
                  - en
                  - fr
                  - de
                  - pt
                  default: es
                  description: Language for response data
              required:
              - points
      responses:
        '200':
          description: List of radars along the path
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Radar'
        '400':
          description: Invalid route
        '401':
          description: Unauthorized
        '500':
          description: Internal server error
  /traffic/current:
    get:
      tags:
      - Traffic
      summary: Get current traffic flow
      description: Retrieve current traffic flow information
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/Latitude'
      - $ref: '#/components/parameters/Longitude'
      - $ref: '#/components/parameters/Radius'
      - $ref: '#/components/parameters/Language'
      responses:
        '200':
          description: Current traffic flow data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrafficFlowData'
        '400':
          description: Invalid parameters
        '401':
          description: Unauthorized
        '500':
          description: Internal server error
  /traffic/nearby:
    get:
      tags:
      - Traffic
      summary: Get nearby traffic flow
      description: Retrieve traffic flow information near a location
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/Latitude'
      - $ref: '#/components/parameters/Longitude'
      - $ref: '#/components/parameters/Radius'
      - $ref: '#/components/parameters/Language'
      responses:
        '200':
          description: Traffic flow data near the location
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrafficFlowData'
        '400':
          description: Invalid parameters
        '401':
          description: Unauthorized
        '500':
          description: Internal server error
  /traffic/getAlongPath:
    post:
      tags:
      - Traffic
      summary: Get traffic flow along a path
      description: Retrieve traffic flow information along a specified route
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                points:
                  type: array
                  items:
                    type: array
                    items:
                      type: number
                    minItems: 2
                    maxItems: 2
                  minItems: 2
                  description: Array of coordinate pairs [longitude, latitude]
                lang:
                  type: string
                  enum:
                  - es
                  - en
                  - fr
                  - de
                  - pt
                  default: es
                  description: Language for response data
              required:
              - points
      responses:
        '200':
          description: Traffic flow data along the path
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TrafficFlowData'
        '400':
          description: Invalid route
        '401':
          description: Unauthorized
        '500':
          description: Internal server error
  /search/nearby:
    get:
      tags:
      - Search
      summary: Search nearby events and radars
      description: Combined search for traffic events and radars near a location
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/Latitude'
      - $ref: '#/components/parameters/Longitude'
      - $ref: '#/components/parameters/Radius'
      - $ref: '#/components/parameters/Language'
      - name: types
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - ACCIDENT
            - ROAD_CLOSURE
            - SPECIAL_EVENT
        description: Filter by event types
      - name: minSeverity
        in: query
        schema:
          type: number
          minimum: 0
          maximum: 100
        description: Minimum event severity level
      - name: vehicleTypes
        in: query
        schema:
          type: array
          items:
            type: string
        description: Filter by affected vehicle types
      responses:
        '200':
          description: Combined search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Invalid parameters
        '401':
          description: Unauthorized
        '500':
          description: Internal server error
  /search/getAlongPath:
    post:
      tags:
      - Search
      summary: Search events and radars along a path
      description: Combined search for traffic events and radars along a specified
        route
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                points:
                  type: array
                  items:
                    type: array
                    items:
                      type: number
                    minItems: 2
                    maxItems: 2
                  minItems: 2
                  description: Array of coordinate pairs [longitude, latitude]
                lang:
                  type: string
                  enum:
                  - es
                  - en
                  - fr
                  - de
                  - pt
                  default: es
                  description: Language for response data
              required:
              - points
      responses:
        '200':
          description: Combined search results along the path
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Invalid route
        '401':
          description: Unauthorized
        '500':
          description: Internal server error