Skip to main content

​
Overview

The reserveParkingSpot endpoint creates a time-limited reservation on an available parking spot. It uses Firestore transactions to prevent race conditions and ensure only one reservation can be made at a time.

​
Endpoint

POST /reserve-parking-spot

​
Authentication

CORS-enabled endpoint. Should be protected with user authentication in production.

​
Request Body

​
spot_id
string
required
The unique identifier of the parking spot to reserve (e.g., “A-01”, “I-16”)
​
license_plate
string
required
Vehicle license plate number for the reservation
​
duration_minutes
integer
required
Duration of the reservation in minutes. Will be converted to an expiration timestamp.

​
Response

​
success
boolean
Indicates whether the reservation was successful
​
message
string
Success message: “Reserva realizada con éxito”
​
error
string
Error message (only present on failure)

​
Success Response

  • 200 OK - Reservation created successfully

​
Error Responses

  • 400 Bad Request - Missing required parameters (spot_id, license_plate, or duration_minutes)
  • 405 Method Not Allowed - Request method is not POST
  • 409 Conflict - Spot cannot be reserved due to:
    • Spot does not exist
    • Spot is already occupied by a vehicle
    • Spot already has an active reservation

​
Transaction Logic

The function uses Firestore transactions to ensure atomic operations:
  1. Read: Fetch current spot data within transaction
  2. Validate: Check spot exists and status is not 0 (Occupied) or 2 (Reserved)
  3. Calculate: Compute expiration time = current time + duration_minutes
  4. Write: Update spot to status 2 with reservation metadata
  5. Commit: Transaction commits only if no conflicts occurred
If another request modifies the spot during the transaction, it will retry automatically.

​
Code Example

curl -X POST https://YOUR_REGION-YOUR_PROJECT.cloudfunctions.net/reserve-parking-spot \
  -H "Content-Type: application/json" \
  -d '{
    "spot_id": "A-05",
    "license_plate": "XYZ789",
    "duration_minutes": 60
  }'

​
Success Response Example

{
  "success": true,
  "message": "Reserva realizada con éxito"
}

​
Error Response Examples

​
Missing Parameters

{
  "error": "Faltan datos: spot_id, license_plate, duration_minutes"
}

​
Spot Already Occupied

{
  "error": "El puesto está ocupado por un vehículo."
}

​
Spot Already Reserved

{
  "error": "El puesto ya tiene una reserva activa."
}

​
Spot Does Not Exist

{
  "error": "El puesto no existe."
}

​
Firestore Data Structure

After successful reservation, the spot document is updated: 
{
  status: 2,
  last_changed: FieldValue.serverTimestamp(),
  reservation_data: {
    license_plate: "XYZ789",
    expires_at: Timestamp, // JavaScript Date object converted to Firestore Timestamp
    duration: 60 // minutes
  }
}

​
Integration with Sensor Data

When a vehicle with a reservation arrives:
  1. Sensor detects vehicle and sends status 0 (Occupied) via Ingest Parking Data
  2. Ingest function recognizes reserved spot and confirms arrival
  3. Status changes from 2 (Reserved) to 0 (Occupied)
  4. Reservation metadata is deleted to save storage

Build docs developers (and LLMs) love

Get started for freeTalk to us