openapi: 3.0.3
info:
title: SpotHero Parking 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: [email protected]
url: https://spothero.com/developers
license:
name: Proprietary
url: https://spothero.com/terms
externalDocs:
description: SpotHero Developer Documentation
url: https://api.spothero.com/v2/docs
servers:
- url: https://api.spothero.com/v2
description: SpotHero API v2 Production
tags:
- name: Search
description: Search for available parking locations and facilities
- name: Facilities
description: Retrieve facility details, amenities, pricing, and directions
- name: Availability
description: Check real-time parking availability
- name: Reservations
description: Create, manage, and cancel parking reservations
- name: Rates
description: Retrieve pricing and rate information
security:
- ApiKeyAuth: []
paths:
/search:
get:
operationId: search-parking
tags:
- Search
summary: Search Parking Locations
description: >-
Search for available parking locations near a given address, coordinates, or point of
interest. Returns a list of facilities with availability and pricing for the requested
time period.
parameters:
- name: latitude
in: query
description: Latitude of the search center point
required: false
schema:
type: number
format: float
example: 41.8827
- name: longitude
in: query
description: Longitude of the search center point
required: false
schema:
type: number
format: float
example: -87.6233
- name: address
in: query
description: Street address or point of interest name to search near
required: false
schema:
type: string
example: '233 S Wacker Dr, Chicago, IL 60606'
- name: starts
in: query
description: Parking start time in ISO 8601 format
required: true
schema:
type: string
format: date-time
example: '2026-06-01T09:00:00Z'
- name: ends
in: query
description: Parking end time in ISO 8601 format
required: true
schema:
type: string
format: date-time
example: '2026-06-01T17:00:00Z'
- name: radius
in: query
description: Search radius in miles (default 0.5)
required: false
schema:
type: number
format: float
default: 0.5
example: 1.0
- name: vehicle_type
in: query
description: Type of vehicle
required: false
schema:
type: string
enum: [car, motorcycle, oversized, monthly]
default: car
- name: limit
in: query
description: Maximum number of results to return
required: false
schema:
type: integer
default: 20
maximum: 100
- name: sort
in: query
description: Sort order for results
required: false
schema:
type: string
enum: [distance, price, rating]
default: distance
responses:
'200':
description: Successful search results
content:
application/json:
schema:
$ref: '#/components/schemas/SearchResults'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/facilities/{facility_id}:
get:
operationId: get-facility
tags:
- Facilities
summary: Get Facility
description: >-
Retrieve detailed information about a specific parking facility including address,
amenities, operating hours, pricing, and directions.
parameters:
- name: facility_id
in: path
description: Unique identifier for the parking facility
required: true
schema:
type: string
example: 'fac_abc123'
responses:
'200':
description: Facility details
content:
application/json:
schema:
$ref: '#/components/schemas/Facility'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/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'
/facilities/{facility_id}/rates:
get:
operationId: get-facility-rates
tags:
- Rates
summary: Get Facility Rates
description: >-
Retrieve pricing rates for a specific parking facility. Returns hourly, daily,
monthly, and event rates where available.
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 rate calculation in ISO 8601 format
required: false
schema:
type: string
format: date-time
- name: ends
in: query
description: End time for rate calculation in ISO 8601 format
required: false
schema:
type: string
format: date-time
responses:
'200':
description: Rate information
content:
application/json:
schema:
$ref: '#/components/schemas/RateList'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/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:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: Partner API key issued by SpotHero
schemas:
SearchResults:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/SearchResult'
total:
type: integer
description: Total number of facilities matching the search criteria
offset:
type: integer
description: Current offset for pagination
limit:
type: integer
description: Maximum results per page
SearchResult:
type: object
properties:
facility_id:
type: string
description: Unique facility identifier
example: 'fac_abc123'
name:
type: string
description: Facility name
example: 'Millennium Park Garage'
address:
$ref: '#/components/schemas/Address'
distance_miles:
type: number
format: float
description: Distance from search center in miles
example: 0.3
price:
$ref: '#/components/schemas/Price'
availability:
$ref: '#/components/schemas/AvailabilitySummary'
amenities:
type: array
items:
type: string
description: List of facility amenities
example: ['covered', 'handicap_accessible', 'ev_charging']
rating:
type: number
format: float
description: Average customer rating (0-5)
example: 4.2
Facility:
type: object
properties:
facility_id:
type: string
description: Unique facility identifier
example: 'fac_abc123'
name:
type: string
description: Facility name
example: 'Millennium Park Garage'
description:
type: string
description: Facility description and access instructions
address:
$ref: '#/components/schemas/Address'
coordinates:
$ref: '#/components/schemas/Coordinates'
phone:
type: string
description: Facility phone number
example: '+13125551234'
hours:
$ref: '#/components/schemas/OperatingHours'
amenities:
type: array
items:
type: string
description: List of available amenities
capacity:
type: integer
description: Total parking capacity
example: 500
entry_instructions:
type: string
description: Instructions for entering the facility
exit_instructions:
type: string
description: Instructions for exiting the facility
rating:
type: number
format: float
description: Average customer rating (0-5)
review_count:
type: integer
description: Number of customer reviews
operator:
type: string
description: Parking operator name
facility_type:
type: string
enum: [garage, lot, street, valet]
description: Type of parking facility
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'
AvailabilitySummary:
type: object
properties:
available:
type: boolean
description: Whether parking is available
spaces_available:
type: integer
description: Approximate number of open spaces
RateList:
type: object
properties:
facility_id:
type: string
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
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'
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
ReservationList:
type: object
properties:
reservations:
type: array
items:
$ref: '#/components/schemas/Reservation'
total:
type: integer
offset:
type: integer
limit:
type: integer
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: '[email protected]'
phone:
type: string
example: '+13125551234'
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'
Price:
type: object
properties:
amount:
type: number
format: float
description: Price amount
example: 15.00
currency:
type: string
description: Currency code (ISO 4217)
example: 'USD'
display:
type: string
description: Human-readable price string
example: '$15.00'
Address:
type: object
properties:
street:
type: string
example: '233 S Wacker Dr'
city:
type: string
example: 'Chicago'
state:
type: string
example: 'IL'
zip:
type: string
example: '60606'
country:
type: string
example: 'US'
Coordinates:
type: object
properties:
latitude:
type: number
format: float
example: 41.8827
longitude:
type: number
format: float
example: -87.6233
OperatingHours:
type: object
description: Operating hours for each day of the week
properties:
monday:
$ref: '#/components/schemas/DayHours'
tuesday:
$ref: '#/components/schemas/DayHours'
wednesday:
$ref: '#/components/schemas/DayHours'
thursday:
$ref: '#/components/schemas/DayHours'
friday:
$ref: '#/components/schemas/DayHours'
saturday:
$ref: '#/components/schemas/DayHours'
sunday:
$ref: '#/components/schemas/DayHours'
is_24_hours:
type: boolean
description: Whether the facility operates 24 hours a day
DayHours:
type: object
properties:
open:
type: string
description: Opening time in HH:MM format
example: '06:00'
close:
type: string
description: Closing time in HH:MM format
example: '22:00'
closed:
type: boolean
description: Whether the facility is closed this day
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:
BadRequest:
description: Bad request - missing or invalid parameters
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'
TooManyRequests:
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error'