openapi: 3.0.3
info:
  title: SpotHero Parking Availability Reservations API
  description: The SpotHero Parking API provides programmatic access to the largest network of off-street parking facilities in North America. Partners can search for available parking spots, check real-time availability, create and manage reservations, and access facility details including pricing, amenities, and directions. The API supports navigation apps, mobility platforms, connected car dashboards, event ticketing systems, and enterprise fleet management solutions.
  version: 2.0.0
  termsOfService: https://spothero.com/terms
  contact:
    name: SpotHero Partner Support
    email: partner.support@spothero.com
    url: https://spothero.com/developers
  license:
    name: Proprietary
    url: https://spothero.com/terms
servers:
- url: https://api.spothero.com/v2
  description: SpotHero API v2 Production
security:
- ApiKeyAuth: []
tags:
- name: Reservations
  description: Create, manage, and cancel parking reservations
paths:
  /reservations:
    get:
      operationId: list-reservations
      tags:
      - Reservations
      summary: List Reservations
      description: Retrieve a list of parking reservations for the authenticated partner account. Supports filtering by status, date range, and facility.
      parameters:
      - name: status
        in: query
        description: Filter by reservation status
        required: false
        schema:
          type: string
          enum:
          - active
          - completed
          - cancelled
          - upcoming
      - name: starts_after
        in: query
        description: Filter reservations starting after this date
        required: false
        schema:
          type: string
          format: date-time
      - name: starts_before
        in: query
        description: Filter reservations starting before this date
        required: false
        schema:
          type: string
          format: date-time
      - name: facility_id
        in: query
        description: Filter by facility ID
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Maximum number of results to return
        required: false
        schema:
          type: integer
          default: 20
          maximum: 100
      - name: offset
        in: query
        description: Number of results to skip for pagination
        required: false
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: List of reservations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReservationList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      operationId: create-reservation
      tags:
      - Reservations
      summary: Create Reservation
      description: Create a new parking reservation at a specific facility for a given time period. Returns a confirmation with a booking reference and barcode for facility entry.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReservationRequest'
      responses:
        '201':
          description: Reservation created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reservation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: Conflict - facility no longer available for requested time period
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /reservations/{reservation_id}:
    get:
      operationId: get-reservation
      tags:
      - Reservations
      summary: Get Reservation
      description: Retrieve details for a specific parking reservation by its ID.
      parameters:
      - name: reservation_id
        in: path
        description: Unique identifier for the reservation
        required: true
        schema:
          type: string
          example: res_xyz789
      responses:
        '200':
          description: Reservation details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reservation'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    delete:
      operationId: cancel-reservation
      tags:
      - Reservations
      summary: Cancel Reservation
      description: Cancel an existing parking reservation. Cancellation policies and refund eligibility depend on the facility's terms and the time of cancellation relative to the reservation start.
      parameters:
      - name: reservation_id
        in: path
        description: Unique identifier for the reservation
        required: true
        schema:
          type: string
          example: res_xyz789
      responses:
        '200':
          description: Reservation cancelled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reservation'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Conflict - reservation cannot be cancelled (already completed or non-refundable)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    ReservationRequest:
      type: object
      required:
      - facility_id
      - rate_id
      - starts
      - ends
      - driver
      - vehicle
      properties:
        facility_id:
          type: string
          description: Unique identifier for the parking facility
          example: fac_abc123
        rate_id:
          type: string
          description: Unique identifier for the selected rate
          example: rate_early_bird
        starts:
          type: string
          format: date-time
          description: Reservation start time in ISO 8601 format
        ends:
          type: string
          format: date-time
          description: Reservation end time in ISO 8601 format
        driver:
          $ref: '#/components/schemas/Driver'
        vehicle:
          $ref: '#/components/schemas/Vehicle'
        partner_reference:
          type: string
          description: Optional partner-side reference identifier for tracking
          example: order_99887766
    Vehicle:
      type: object
      properties:
        type:
          type: string
          enum:
          - car
          - motorcycle
          - oversized
          default: car
        license_plate:
          type: string
          description: Vehicle license plate number
          example: ABC1234
        state:
          type: string
          description: US state or Canadian province abbreviation
          example: IL
        make:
          type: string
          description: Vehicle manufacturer
          example: Toyota
        model:
          type: string
          description: Vehicle model
          example: Camry
        color:
          type: string
          description: Vehicle color
          example: Blue
    Reservation:
      type: object
      properties:
        reservation_id:
          type: string
          description: Unique SpotHero reservation identifier
          example: res_xyz789
        status:
          type: string
          enum:
          - active
          - completed
          - cancelled
          - upcoming
          description: Current reservation status
        facility_id:
          type: string
          description: Parking facility identifier
        facility_name:
          type: string
          description: Name of the parking facility
        starts:
          type: string
          format: date-time
          description: Reservation start time
        ends:
          type: string
          format: date-time
          description: Reservation end time
        price:
          $ref: '#/components/schemas/Price'
        driver:
          $ref: '#/components/schemas/Driver'
        vehicle:
          $ref: '#/components/schemas/Vehicle'
        barcode:
          type: string
          description: Barcode value for facility access
        barcode_format:
          type: string
          description: Barcode format (e.g., QR, Code128)
          example: QR
        confirmation_code:
          type: string
          description: Human-readable confirmation code
          example: SH-ABC123
        partner_reference:
          type: string
          description: Partner-side reference identifier
        created_at:
          type: string
          format: date-time
          description: Timestamp when reservation was created
        updated_at:
          type: string
          format: date-time
          description: Timestamp when reservation was last updated
    Price:
      type: object
      properties:
        amount:
          type: number
          format: float
          description: Price amount
          example: 15.0
        currency:
          type: string
          description: Currency code (ISO 4217)
          example: USD
        display:
          type: string
          description: Human-readable price string
          example: $15.00
    Driver:
      type: object
      required:
      - first_name
      - last_name
      - email
      properties:
        first_name:
          type: string
          example: Jane
        last_name:
          type: string
          example: Smith
        email:
          type: string
          format: email
          example: jane.smith@example.com
        phone:
          type: string
          example: '+13125551234'
    ReservationList:
      type: object
      properties:
        reservations:
          type: array
          items:
            $ref: '#/components/schemas/Reservation'
        total:
          type: integer
        offset:
          type: integer
        limit:
          type: integer
    Error:
      type: object
      properties:
        code:
          type: string
          description: Error code
        message:
          type: string
          description: Human-readable error message
        details:
          type: object
          description: Additional error details
  responses:
    TooManyRequests:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized - invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request - missing or invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Partner API key issued by SpotHero
externalDocs:
  description: SpotHero Developer Documentation
  url: https://api.spothero.com/v2/docs