AlertCamp Stats API

openapi: 3.2.0
info:
  title: AlertCamp Stats API
  description: Service d'alertes de disponibilité SEPAQ pour le camping au Québec
  version: 0.1.0
tags:
- name: Stats
paths:
  /api/v1/stats/public:
    get:
      tags:
      - Stats
      summary: Get Public Stats
      description: 'Public, unauthenticated marketing stats for the website.


        Figures come from ``compute_public_stats`` (see its docstring for what

        is counted). Cached for ``_PUBLIC_STATS_TTL_SECONDS``.'
      operationId: get_public_stats_api_v1_stats_public_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicStatsResponse'
  /api/v1/stats/cancellations:
    get:
      tags:
      - Stats
      summary: Get Cancellation Stats
      description: 'Get aggregate cancellation statistics.


        Returns overview metrics, per-park breakdown, day-of-week distribution,

        and lead time buckets for the specified rolling window.'
      operationId: get_cancellation_stats_api_v1_stats_cancellations_get
      parameters:
      - name: days
        in: query
        required: false
        schema:
          type: integer
          maximum: 365
          minimum: 1
          description: Rolling window in days
          default: 30
          title: Days
        description: Rolling window in days
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-dev-user-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Dev-User-Id
      - name: x-app-version
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-App-Version
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancellationStatsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ParkCancellationStats:
      properties:
        park_id:
          type: string
          title: Park Id
        park_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Park Name
        cancellation_count:
          type: integer
          title: Cancellation Count
      type: object
      required:
      - park_id
      - park_name
      - cancellation_count
      title: ParkCancellationStats
      description: Per-park cancellation counts.
    CancellationStatsResponse:
      properties:
        overview:
          $ref: '#/components/schemas/CancellationOverview'
        by_park:
          items:
            $ref: '#/components/schemas/ParkCancellationStats'
          type: array
          title: By Park
        by_day_of_week:
          items:
            $ref: '#/components/schemas/DayOfWeekStats'
          type: array
          title: By Day Of Week
        by_hour_of_day:
          items:
            $ref: '#/components/schemas/HourOfDayStats'
          type: array
          title: By Hour Of Day
        lead_time_distribution:
          items:
            $ref: '#/components/schemas/LeadTimeBucket'
          type: array
          title: Lead Time Distribution
        by_detection_month:
          items:
            $ref: '#/components/schemas/MonthStats'
          type: array
          title: By Detection Month
        by_camping_month:
          items:
            $ref: '#/components/schemas/MonthStats'
          type: array
          title: By Camping Month
        rebooking_speed_by_park:
          items:
            $ref: '#/components/schemas/ParkRebookingSpeed'
          type: array
          title: Rebooking Speed By Park
        alert_success_rate:
          $ref: '#/components/schemas/AlertSuccessRate'
      type: object
      required:
      - overview
      - by_park
      - by_day_of_week
      - by_hour_of_day
      - lead_time_distribution
      - by_detection_month
      - by_camping_month
      - rebooking_speed_by_park
      - alert_success_rate
      title: CancellationStatsResponse
      description: Full cancellation statistics response.
    ParkRebookingSpeed:
      properties:
        park_id:
          type: string
          title: Park Id
        park_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Park Name
        avg_rebooking_delay_minutes:
          anyOf:
          - type: number
          - type: 'null'
          title: Avg Rebooking Delay Minutes
        median_rebooking_delay_minutes:
          anyOf:
          - type: number
          - type: 'null'
          title: Median Rebooking Delay Minutes
        sample_size:
          type: integer
          title: Sample Size
      type: object
      required:
      - park_id
      - park_name
      - avg_rebooking_delay_minutes
      - median_rebooking_delay_minutes
      - sample_size
      title: ParkRebookingSpeed
      description: Rebooking speed metrics per park.
    AlertSuccessRate:
      properties:
        total_alerts:
          type: integer
          title: Total Alerts
        alerts_with_matches:
          type: integer
          title: Alerts With Matches
        success_rate:
          type: number
          title: Success Rate
      type: object
      required:
      - total_alerts
      - alerts_with_matches
      - success_rate
      title: AlertSuccessRate
      description: Alert success rate over a period.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CancellationOverview:
      properties:
        total_cancellations:
          type: integer
          title: Total Cancellations
        total_rebooked:
          type: integer
          title: Total Rebooked
        rebooking_rate:
          type: number
          title: Rebooking Rate
        avg_nights:
          anyOf:
          - type: number
          - type: 'null'
          title: Avg Nights
        avg_rebooking_delay_minutes:
          anyOf:
          - type: number
          - type: 'null'
          title: Avg Rebooking Delay Minutes
        median_rebooking_delay_minutes:
          anyOf:
          - type: number
          - type: 'null'
          title: Median Rebooking Delay Minutes
        avg_days_until:
          anyOf:
          - type: number
          - type: 'null'
          title: Avg Days Until
        period_start:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Period Start
        period_end:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Period End
      type: object
      required:
      - total_cancellations
      - total_rebooked
      - rebooking_rate
      - avg_nights
      - avg_rebooking_delay_minutes
      - median_rebooking_delay_minutes
      - avg_days_until
      - period_start
      - period_end
      title: CancellationOverview
      description: Aggregate overview of cancellation events.
    HourOfDayStats:
      properties:
        hour:
          type: integer
          title: Hour
        cancellation_count:
          type: integer
          title: Cancellation Count
      type: object
      required:
      - hour
      - cancellation_count
      title: HourOfDayStats
      description: Cancellation counts by hour of the day (Eastern time).
    MonthStats:
      properties:
        month:
          type: integer
          title: Month
        cancellation_count:
          type: integer
          title: Cancellation Count
      type: object
      required:
      - month
      - cancellation_count
      title: MonthStats
      description: Cancellation counts by month (1=January ... 12=December).
    LeadTimeBucket:
      properties:
        bucket:
          type: string
          title: Bucket
        count:
          type: integer
          title: Count
      type: object
      required:
      - bucket
      - count
      title: LeadTimeBucket
      description: Lead time distribution bucket.
    PublicStatsResponse:
      properties:
        cancellation_alerts_sent:
          type: integer
          title: Cancellation Alerts Sent
        active_alerts:
          type: integer
          title: Active Alerts
        campers:
          type: integer
          title: Campers
        since:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Since
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
      - cancellation_alerts_sent
      - active_alerts
      - campers
      - since
      - updated_at
      title: PublicStatsResponse
      description: 'Public marketing stats — safe to expose unauthenticated on the website.


        All figures are aggregate, contain no user-identifying data, and are

        intended for headline copy (e.g. "we''ve sent campers N cancellation

        alerts").'
    DayOfWeekStats:
      properties:
        day_of_week:
          type: integer
          title: Day Of Week
        cancellation_count:
          type: integer
          title: Cancellation Count
      type: object
      required:
      - day_of_week
      - cancellation_count
      title: DayOfWeekStats
      description: Cancellation counts by day of the week.