ParkStream API

Operations

Original Idea

Parking Spot Finder API A backend API that aggregates real-time parking availability from garages, meters, and lots for cities and navigation apps.

Product Requirements Document (PRD): ParkStream API

1. Executive Summary

ParkStream API is a high-concurrency, real-time data infrastructure platform designed to aggregate fragmented parking availability data from municipal meters, private garages, and IoT-enabled lots. By providing a unified, standardized geospatial API, ParkStream enables navigation apps, fleet managers, and smart city planners to access live occupancy, pricing, and location data through a single integration point, reducing urban congestion and optimizing search time for drivers.

2. Problem Statement

Drivers currently waste an average of 17 hours per year searching for parking, contributing to 30% of urban traffic congestion. Data regarding parking availability is highly fragmented: cities use various Open Data portals, private garage operators use proprietary hardware, and street meters often lack real-time connectivity. Developers lack a "single source of truth" to build efficient navigation and logistics tools.

3. Goals & Success Metrics

  • Latency: Maintain a P99 response time of <100ms for geospatial radius searches.
  • Data Accuracy: Achieve >95% correlation between API reported status and physical spot occupancy.
  • Reliability: Maintain 99.99% uptime for the core ingestion and query engines.
  • Scalability: Support 100,000+ concurrent sensor updates per second.
  • Developer Adoption: Onboard 50+ enterprise developers within the first 6 months.

4. User Personas

  • Devin (Navigation App Developer): Needs low-latency, reliable geospatial data to provide "parking near destination" features to millions of end-users.
  • Lydia (Logistics/Fleet Manager): Needs historical and real-time data to optimize delivery routes and reduce "idling" fines for urban delivery vans.
  • Suresh (Smart City Planner): Needs aggregated occupancy trends to adjust dynamic pricing and urban curb-side policies.
  • Marco (IoT Hardware Provider): Needs a simple, secure way to push high-frequency sensor data into a centralized cloud ecosystem.

5. User Stories

  • As a Developer, I want to query parking spots within a 500m radius of a coordinate so that I can show my users the nearest available space.
  • As a Fleet Manager, I want to filter for spots with specific height clearances so that my large delivery trucks don't get stuck.
  • As an IoT Provider, I want to push occupancy updates via HMAC-signed webhooks so that the data remains secure and authenticated.
  • As a City Planner, I want to access historical occupancy heatmaps so that I can justify new parking infrastructure investments.

6. Functional Requirements

6.1 Core Data Ingestion

  • Multi-Protocol Support: Support data ingestion via MQTT 5.0, Webhooks, and scheduled Socrata/CKAN ETL jobs.
  • Standardization: Automatically map incoming third-party data to the APDS (ISO 5206-1:2023) standardized JSON schema.
  • Conflict Resolution: Implement logic to handle overlapping data sources (e.g., a city sensor and a garage API reporting on the same location).

6.2 Geospatial Search API

  • Radius Search: Query available spots within a user-defined radius (meters/km).
  • Bounding Box: Search within specific geographic boundaries (GeoJSON polygons).
  • Filtering: Filter by parking_type (Street, Garage, Private), pricing, and ev_charging_availability.

6.3 Developer Dashboard

  • Self-Service Keys: Generate, revoke, and rotate API keys with SHA-256 hashing.
  • Analytics: Real-time visualization of request volume, rate-limit status, and latency.
  • Billing: Integration with Stripe for tier-based usage billing.

6.4 Management & Security

  • Multi-tenancy: Logical isolation of data and usage quotas per API consumer.
  • Rate Limiting: Implement sliding-window rate limiting based on subscription tiers (Free, Pro, Enterprise).

7. Technical Requirements

7.1 Tech Stack (2026 Standards)

  • Backend: Go 1.26 (utilizing "Green Tea" GC and new expression support for high-concurrency ingestion).
  • Frontend: Next.js 16.1.x (using Turbopack and React 19 stable integration for the developer dashboard).
  • Database: PostgreSQL 18 with PostGIS 3.6.x (utilizing native Asynchronous I/O and ST_DWithin optimizations).
  • Caching/Real-time: Redis 8.0 (utilizing the new Query Engine for microsecond-latency availability caching).
  • Infrastructure: AWS EKS (Kubernetes 1.34) on Amazon Linux 2023 nodes.
  • Ingestion: MQTT 5.0 via paho.golang for IoT sensor streams.

7.2 Integrations

  • City Data: Socrata/CKAN Open Data Portals.
  • Enrichment: Google Maps Places API for metadata (business names, photos).
  • Auth: Auth0 for OIDC-based dashboard login.
  • Security: HMAC signature verification for all incoming webhooks.

8. Data Model

8.1 ParkingLocation (PostGIS)

  • location_id: UUID (Primary Key)
  • coordinates: GEOGRAPHY(POINT, 4326)
  • name: String
  • capacity: Integer
  • parking_type: Enum (STREET, GARAGE, LOT)
  • metadata: JSONB (dimensions, clearance, EV info)

8.2 AvailabilityStatus (Redis + PostGIS)

  • location_id: UUID (Foreign Key)
  • current_occupancy: Integer
  • is_full: Boolean
  • last_updated: Timestamp (High-resolution)

8.3 PricingRule (Standardized APDS)

  • rule_id: UUID
  • location_id: UUID
  • base_rate: Decimal
  • currency: String (ISO 4217)
  • dynamic_multiplier: Decimal

9. API Specification (Draft)

9.1 Search Nearby Parking

GET /v1/search?lat={lat}&lng={lng}&radius={meters}&type={type} Response:

{
  "results": [
    {
      "id": "loc_98765",
      "name": "Market St Garage",
      "distance": 150.5,
      "available_spots": 12,
      "total_capacity": 200,
      "pricing": {"rate": 5.00, "currency": "USD", "unit": "hour"},
      "coordinates": {"lat": 37.7749, "lng": -122.4194}
    }
  ]
}

9.2 Ingest Sensor Update (Webhook)

POST /v1/ingest/status Headers: X-Signature-SHA256: <hmac_hash> Payload:

{
  "sensor_id": "sn_001",
  "location_id": "loc_98765",
  "timestamp": "2026-02-15T14:00:01Z",
  "event": "occupied"
}

10. UI/UX Requirements

  • Dashboard Layout: Sidebar navigation with a "Health Score" for the user's API keys.
  • Component Library: Use Shadcn UI for layouts and Tremor for the API usage charts.
  • Real-time Monitoring: A "Live Stream" view showing successful vs. failed requests using Next.js Server Actions and Suspense.
  • Key Management: A "reveal on click" security pattern for sensitive API secrets.

11. Non-Functional Requirements

  • Security: TLS 1.3 enforced; HMAC-SHA256 for IoT integrity; SHA-256 for key storage.
  • Scalability: Horizontal Pod Autoscaling (HPA) in EKS based on CPU/Request count.
  • Observability: Prometheus/Grafana for metric tracking; OpenTelemetry for trace spans across Go microservices.
  • Compliance: GDPR/CCPA compliant (all parking session data is anonymized).

12. Out of Scope

  • User App: We are NOT building a driver-facing mobile app (B2B only).
  • Hardware: We are NOT manufacturing IoT sensors.
  • Enforcement: We are NOT providing tools for parking ticket issuance.

13. Risks & Mitigations

  • Risk: Latency spikes during peak commute hours.
    • Mitigation: Use Redis 8.0 geospatial caching and PostGIS 3.6 read-replicas.
  • Risk: Unreliable city data feeds.
    • Mitigation: Implement a "Confidence Score" for each location based on the last-updated timestamp.
  • Risk: API Key Scraping.
    • Mitigation: Enforce strict HMAC verification and IP-whitelisting for Enterprise tiers.

14. Implementation Tasks

Phase 1: Project Setup

  • [ ] Initialize Go 1.26 backend with Fiber v3 framework.
  • [ ] Initialize Next.js 16.1.x dashboard with Tailwind CSS and Shadcn.
  • [ ] Configure PostgreSQL 18 with PostGIS 3.6 extension on AWS RDS (or EKS).
  • [ ] Set up CI/CD pipeline targeting AWS EKS 1.34.

Phase 2: Ingestion & Core Data

  • [ ] Implement APDS-compliant data entities in PostGIS.
  • [ ] Build MQTT 5.0 subscriber with Shared Subscription load balancing.
  • [ ] Implement HMAC signature verification middleware for webhooks.
  • [ ] Create ETL scripts for Socrata city data portals.

Phase 3: Geospatial API & Performance

  • [ ] Implement ST_DWithin radius search endpoint in Go.
  • [ ] Integrate Redis 8.0 for high-frequency availability caching.
  • [ ] Configure PgBouncer for connection pooling to Postgres.
  • [ ] Implement sliding-window rate limiting using NVIDIA/go-ratelimit.

Phase 4: Developer Dashboard

  • [ ] Build API Key management UI with Next.js Server Actions.
  • [ ] Integrate Tremor charts for real-time usage analytics.
  • [ ] Implement Stripe Billing integration for usage-based tiers.
  • [ ] Set up Auth0 OIDC authentication for dashboard users.

Phase 5: Advanced Features & Launch

  • [ ] Implement Predictive Availability using a baseline Random Forest model.
  • [ ] Build "Curb Data Specification" (CDS) export functionality.
  • [ ] Conduct load testing (aiming for 10k RPS).
  • [ ] Finalize API Documentation via Swagger/OpenAPI 3.1.