openapi: 3.0.3
info:
  title: SpotHero Parking Availability 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: Availability
  description: Check real-time parking availability
paths:
  /facilities/{facility_id}/availability:
    get:
      operationId: get-facility-availability
      tags:
      - Availability
      summary: Get Facility Availability
      description: Check real-time availability for a specific parking facility during a given time period. Returns current capacity, available spaces, and pricing for the requested window.
      parameters:
      - name: facility_id
        in: path
        description: Unique identifier for the parking facility
        required: true
        schema:
          type: string
          example: fac_abc123
      - name: starts
        in: query
        description: Start time for availability check in ISO 8601 format
        required: true
        schema:
          type: string
          format: date-time
      - name: ends
        in: query
        description: End time for availability check in ISO 8601 format
        required: true
        schema:
          type: string
          format: date-time
      - name: vehicle_type
        in: query
        description: Type of vehicle
        required: false
        schema:
          type: string
          enum:
          - car
          - motorcycle
          - oversized
          - monthly
          default: car
      responses:
        '200':
          description: Availability information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Availability'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  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'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Availability:
      type: object
      properties:
        facility_id:
          type: string
          description: Unique facility identifier
        available:
          type: boolean
          description: Whether parking is available for the requested time period
        spaces_available:
          type: integer
          description: Estimated number of available spaces
        price:
          $ref: '#/components/schemas/Price'
        rates:
          type: array
          items:
            $ref: '#/components/schemas/Rate'
    Rate:
      type: object
      properties:
        rate_id:
          type: string
          description: Unique rate identifier
        name:
          type: string
          description: Rate name/description
          example: Early Bird Rate
        type:
          type: string
          enum:
          - hourly
          - daily
          - monthly
          - event
          - overnight
          description: Rate type
        price:
          $ref: '#/components/schemas/Price'
        starts:
          type: string
          format: date-time
          description: Rate validity start time
        ends:
          type: string
          format: date-time
          description: Rate validity end time
        vehicle_types:
          type: array
          items:
            type: string
          description: Vehicle types this rate applies to
    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
    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
  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