openapi: 3.0.0
info:
  title: Weather
  description: 'Esta API es parte de **Transcend** y corresponde al módulo de consulta
    meteorológica, para verificar la situación meteorológica en un punto dado de las
    rutas en el sector logístico.


    Su principal misión es verificar la climatología, además de una consulta habitual
    para complementar la información correspondiente a los otros servicios de TransCend;
    sirve para determinar si un punto de la ruta presenta problemas *(o representa
    un peligro)* para el transporte de mercancías, proporcionando un valor porcentual
    de peligrosidad y un nivel de alerta en relación con la climatología habitual.

    '
  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 de autenticación, obtenido de IAM
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Clave API para autenticación alternativa
  parameters:
    Latitude:
      name: lat
      in: query
      description: Coordenada de latitud en grados decimales (estándar WGS84).
      required: true
      schema:
        type: number
        format: float
        minimum: -90
        maximum: 90
        default: 42.5585667
        example: 42.5585667
    Longitude:
      name: lon
      in: query
      description: Coordenada de longitud en grados decimales (estándar WGS84).
      required: true
      schema:
        type: number
        format: float
        minimum: -180
        maximum: 180
        default: -9.0018432
        example: -9.0018432
    StartDate:
      name: start
      in: query
      description: Fecha de inicio para la consulta meteorológica en formato AAAA-MM-DD.
      required: true
      schema:
        type: string
        format: date
        default: '2025-03-25'
      example: '2025-03-21'
    EndDate:
      name: end
      in: query
      description: Fecha de fin para la consulta meteorológica en formato AAAA-MM-DD.
      required: true
      schema:
        type: string
        format: date
        default: '2025-03-25'
      example: '2025-03-25'
    Language:
      name: lang
      in: query
      required: false
      schema:
        type: string
        enum:
        - es
        - en
        - it
        - fr
        - pt
        - de
        example: es
        default: es
      description: Código de idioma en formato ISO 639-1 (2 letras)
    DangerLevel:
      name: dangerLevel
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 100
        default: 0
        example: 50
      description: 'Nivel de peligro meteorológico (0-100) para filtrar puntos de
        ruta.

        - 0: Incluir todos los puntos (sin filtro)

        - 1-100: Solo los puntos con un nivel de peligro igual o superior al valor
        especificado

        - Los valores fuera de límites se ajustan automáticamente (mínimo 0, máximo
        100)

        '
    StationId:
      name: stationId
      in: query
      required: true
      schema:
        type: string
        example: '3195'
      description: ID de la estación meteorológica AEMET
    Municipio:
      name: municipio
      in: query
      required: true
      schema:
        type: string
        example: '28079'
      description: Código de municipio para las consultas AEMET
    Parametro:
      name: parametro
      in: query
      required: true
      schema:
        type: string
        enum:
        - TEMP_MAX
        - TEMP_MIN
        - PREC
        - VIENTO
        example: TEMP_MAX
      description: Parámetro meteorológico para la consulta de valores extremos
    StationIdPath:
      name: stationId
      in: path
      required: true
      schema:
        type: string
        example: '3195'
      description: ID de la estación meteorológica AEMET
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
      required:
      - error
paths:
  /current:
    get:
      tags:
      - Core Weather
      summary: Get current weather
      operationId: getCurrent
      description: Obtener las condiciones meteorológicas en tiempo real para su ubicación
        exacta.
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/Latitude'
      - $ref: '#/components/parameters/Longitude'
      - $ref: '#/components/parameters/Language'
      responses:
        '200':
          description: Condiciones meteorológicas actuales recuperadas exitosamente.
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Parámetros inválidos o faltantes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /forecast:
    get:
      tags:
      - Core Weather
      summary: Get weather forecast
      operationId: getForeCast
      description: Obtener pronósticos meteorológicos detallados para el período seleccionado.
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/Latitude'
      - $ref: '#/components/parameters/Longitude'
      - $ref: '#/components/parameters/StartDate'
      - $ref: '#/components/parameters/EndDate'
      - $ref: '#/components/parameters/Language'
      responses:
        '200':
          description: Pronóstico meteorológico recuperado exitosamente.
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Parámetros inválidos o faltantes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /alerts/current:
    get:
      tags:
      - Weather Alerts
      summary: Get current weather alerts
      operationId: getAlertCurrent
      description: Manténgase informado sobre las alertas meteorológicas activas en
        su zona.
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/Latitude'
      - $ref: '#/components/parameters/Longitude'
      - $ref: '#/components/parameters/Language'
      responses:
        '200':
          description: Alertas meteorológicas recuperadas exitosamente.
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Parámetros inválidos o faltantes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error interno del servidor.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /alerts/range:
    get:
      tags:
      - Weather Alerts
      summary: Get weather alerts for date range
      operationId: getAlertRange
      description: Consultar alertas meteorológicas históricas o futuras para su ubicación.
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/Latitude'
      - $ref: '#/components/parameters/Longitude'
      - $ref: '#/components/parameters/StartDate'
      - $ref: '#/components/parameters/EndDate'
      - $ref: '#/components/parameters/Language'
      responses:
        '200':
          description: Alertas meteorológicas históricas o futuras recuperadas exitosamente.
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Parámetros inválidos o faltantes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error interno del servidor.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /route:
    post:
      tags:
      - Route Analysis
      summary: Get weather along route with danger filtering
      operationId: getWeatherAlongPath
      description: 'Obtener las condiciones meteorológicas a lo largo de una ruta
        GPS con filtrado opcional por nivel de peligro.


        **Funcionalidad de filtrado por peligro:**

        - Si `dangerLevel` no se especifica, se incluyen todos los puntos (equivalente
        a dangerLevel=0)

        - Si `dangerLevel` se especifica, solo se devuelven los puntos con un nivel
        de peligro igual o superior al valor

        - El valor se ajusta automáticamente entre 0 y 100 (mínimo 0, máximo 100)


        **Procesamiento de la ruta:**

        - Los puntos GPS se filtran para conservar solo aquellos separados por al
        menos 25 km

        - Se obtienen datos climáticos y alertas para cada punto filtrado

        - Se calcula una puntuación de peligro basada en visibilidad, lluvia, nieve,
        viento, temperatura, nubes y condiciones extremas

        '
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/Language'
      - $ref: '#/components/parameters/DangerLevel'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                points:
                  type: array
                  description: Array de puntos GPS en el formato [[lat, lon], [lat,
                    lon], ...]
                  items:
                    type: array
                    items:
                      type: number
                    minItems: 2
                    maxItems: 2
                    example:
                    - 40.4168
                    - -3.7038
              required:
              - points
      responses:
        '200':
          description: Datos meteorológicos recuperados exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  alerts:
                    type: array
                    description: Alertas meteorológicas activas en los puntos de la
                      ruta
                  currentWeather:
                    type: array
                    description: 'Datos climáticos actuales, filtrados por nivel de
                      peligro.

                      Cada elemento incluye una puntuación de peligro (0-100) calculada
                      automáticamente.

                      '
        '400':
          description: Cuerpo de solicitud inválido o puntos GPS mal formados
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error interno del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /aemet/current:
    get:
      tags:
      - AEMET
      summary: Get current AEMET weather alerts
      operationId: getAemetCurrent
      description: Alertas meteorológicas en tiempo real proporcionadas por AEMET
        para ubicaciones en España
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/Latitude'
      - $ref: '#/components/parameters/Longitude'
      - $ref: '#/components/parameters/Language'
      responses:
        '200':
          description: Alertas meteorológicas actuales recuperadas exitosamente
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Parámetros inválidos o faltantes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /aemet/forecast:
    get:
      tags:
      - AEMET
      summary: Get AEMET weather forecast
      operationId: getAemetForecast
      description: Pronósticos meteorológicos proporcionados por AEMET para ubicaciones
        en España
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/Latitude'
      - $ref: '#/components/parameters/Longitude'
      - $ref: '#/components/parameters/StartDate'
      - $ref: '#/components/parameters/EndDate'
      - $ref: '#/components/parameters/Language'
      responses:
        '200':
          description: Pronóstico meteorológico recuperado exitosamente
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Parámetros inválidos o faltantes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /aemet/alerts/current:
    get:
      tags:
      - AEMET
      summary: Get current AEMET alerts
      operationId: getAemetAlertsCurrent
      description: Alertas meteorológicas actuales proporcionadas por AEMET para ubicaciones
        en España
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/Latitude'
      - $ref: '#/components/parameters/Longitude'
      - $ref: '#/components/parameters/Language'
      responses:
        '200':
          description: Alertas meteorológicas recuperadas exitosamente
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Parámetros inválidos o faltantes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /aemet/alerts/range:
    get:
      tags:
      - AEMET
      summary: Get AEMET alerts for date range
      operationId: getAemetAlertsRange
      description: Alertas meteorológicas históricas o futuras proporcionadas por
        AEMET para ubicaciones en España
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/Latitude'
      - $ref: '#/components/parameters/Longitude'
      - $ref: '#/components/parameters/StartDate'
      - $ref: '#/components/parameters/EndDate'
      - $ref: '#/components/parameters/Language'
      responses:
        '200':
          description: Alertas meteorológicas históricas o futuras recuperadas exitosamente
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Parámetros inválidos o faltantes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /aemet/stations:
    get:
      tags:
      - AEMET
      summary: Get AEMET weather stations list
      operationId: getAemetStations
      description: Lista completa de estaciones meteorológicas disponibles en AEMET
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      responses:
        '200':
          description: Lista de estaciones recuperada exitosamente
          content:
            application/json:
              schema:
                type: object
        '500':
          description: Error del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /aemet/stations/{stationId}:
    get:
      tags:
      - AEMET
      summary: Get AEMET weather station details
      operationId: getAemetStationDetails
      description: Información detallada de una estación meteorológica específica
        de AEMET
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/StationIdPath'
      responses:
        '200':
          description: Detalles de la estación recuperados exitosamente
          content:
            application/json:
              schema:
                type: object
        '400':
          description: ID de estación inválido o faltante
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /aemet/forecast/station:
    get:
      tags:
      - AEMET
      summary: Get weather forecast for specific station
      operationId: getAemetForecastStation
      description: Pronóstico meteorológico de AEMET para una estación meteorológica
        específica
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/StationId'
      - $ref: '#/components/parameters/StartDate'
      - $ref: '#/components/parameters/EndDate'
      responses:
        '200':
          description: Pronóstico de la estación recuperado exitosamente
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Parámetros inválidos o faltantes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /aemet/forecast/stations:
    get:
      tags:
      - AEMET
      summary: Get weather forecast for all stations
      operationId: getAemetForecastAllStations
      description: Pronóstico meteorológico de AEMET para todas las estaciones meteorológicas
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/StartDate'
      - $ref: '#/components/parameters/EndDate'
      responses:
        '200':
          description: Pronóstico de todas las estaciones recuperado exitosamente
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Parámetros inválidos o faltantes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /aemet/extreme:
    get:
      tags:
      - AEMET
      summary: Get extreme weather values
      operationId: getAemetExtremeValues
      description: Valores extremos (máximos y mínimos) de los parámetros meteorológicos
        de AEMET
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/Parametro'
      - $ref: '#/components/parameters/StationId'
      - $ref: '#/components/parameters/StartDate'
      - $ref: '#/components/parameters/EndDate'
      responses:
        '200':
          description: Valores extremos recuperados exitosamente
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Parámetros inválidos o faltantes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /aemet/alerts/area:
    get:
      tags:
      - AEMET
      summary: Get weather alerts by area
      operationId: getAemetAlertsByArea
      description: Alertas meteorológicas de AEMET filtradas por área geográfica
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/Latitude'
      - $ref: '#/components/parameters/Longitude'
      - $ref: '#/components/parameters/StartDate'
      - $ref: '#/components/parameters/EndDate'
      responses:
        '200':
          description: Alertas por área recuperadas exitosamente
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Parámetros inválidos o faltantes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /ipma/current:
    get:
      tags:
      - IPMA
      summary: Get current IPMA weather
      operationId: getIpmaCurrent
      description: Condiciones meteorológicas actuales proporcionadas por IPMA para
        ubicaciones en Portugal
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/Latitude'
      - $ref: '#/components/parameters/Longitude'
      responses:
        '200':
          description: Clima actual recuperado exitosamente
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Parámetros inválidos o faltantes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /ipma/forecast:
    get:
      tags:
      - IPMA
      summary: Get IPMA weather forecast
      operationId: getIpmaForecast
      description: Pronósticos meteorológicos proporcionados por IPMA para ubicaciones
        en Portugal
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/Latitude'
      - $ref: '#/components/parameters/Longitude'
      - $ref: '#/components/parameters/StartDate'
      - $ref: '#/components/parameters/EndDate'
      responses:
        '200':
          description: Pronóstico meteorológico recuperado exitosamente
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Parámetros inválidos o faltantes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /ipma/alerts/current:
    get:
      tags:
      - IPMA
      summary: Get current IPMA weather alerts
      operationId: getIpmaAlertCurrent
      description: Alertas meteorológicas actuales proporcionadas por IPMA para ubicaciones
        en Portugal
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/Latitude'
      - $ref: '#/components/parameters/Longitude'
      responses:
        '200':
          description: Alertas meteorológicas recuperadas exitosamente
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Parámetros inválidos o faltantes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /ipma/alerts/range:
    get:
      tags:
      - IPMA
      summary: Get IPMA alerts for date range
      operationId: getIpmaAlertRange
      description: Alertas meteorológicas históricas o futuras proporcionadas por
        IPMA para ubicaciones en Portugal
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/Latitude'
      - $ref: '#/components/parameters/Longitude'
      - $ref: '#/components/parameters/StartDate'
      - $ref: '#/components/parameters/EndDate'
      responses:
        '200':
          description: Alertas meteorológicas recuperadas exitosamente
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Parámetros inválidos o faltantes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'