Thanks to visit codestin.com
Credit goes to github.com

Skip to content

PArns/v4.api.park.fan

BranchesTags

Repository files navigation

🎢 park.fan API v4

Real-time theme park intelligence powered by machine learning

NestJS TypeScript PostgreSQL Docker

Aggregating wait times, weather forecasts, park schedules, and ML-powered predictions for optimal theme park experiences worldwide.

📖 Quick Navigation

✨ Features

  • 🚀 Real-time Wait Times — Live queue data for attractions, shows, and restaurants
  • 🤖 ML Predictions — Machine learning forecasts for wait times and crowd levels
  • 🌤️ Weather Integration — Current conditions and 16-day forecasts for all parks
  • 📅 Park Schedules — Opening hours, special events, and operating calendars
  • 🌍 Multi-Source Data — Aggregated from multiple providers for maximum coverage
  • 📊 Analytics Ready — TimescaleDB-powered time-series data for insights
  • ⚡ High Performance — Redis caching and Bull queue processing
  • 🎯 RESTful API — Clean endpoints with full Swagger/OpenAPI documentation

🛠️ Tech Stack

Category Technology
Backend NestJS 11 · TypeScript (strict mode)
Database PostgreSQL 16 · TimescaleDB
Cache & Queue Redis 7 · Bull Queue
ML Service Python 3.11 · CatBoost · FastAPI
DevOps Docker Compose · GitHub Actions
Testing Jest · Supertest · Testcontainers

🚀 Quick Start

Prerequisites

  • Node.js 20+
  • Docker & Docker Compose
  • Git

Installation

# Clone the repository
git clone https://github.com/PArns/v4.api.park.fan.git
cd v4.api.park.fan

# Install dependencies
npm install

# Copy environment configuration
cp .env.example .env

# Start infrastructure (PostgreSQL + Redis)
npm run docker:up

# Start development server
npm run dev

Access Points

Once running, you can access:

📚 API Documentation

🏥 Health & Monitoring

System health checks and monitoring endpoints.

GET /v1/health              # System health status
GET /v1/health/db           # Database connectivity

Response includes:

  • System uptime
  • Database connection status
  • Last sync timestamps (wait times, park metadata)
  • Active jobs and queue status

🎡 Parks

Core endpoints for park information, weather, schedules, and wait times.

GET /v1/parks                                      # List all parks
GET /v1/parks/:slug                                # Get park by slug
GET /v1/parks/:continent/:country/:city/:parkSlug  # Get park by location
GET /v1/parks/:slug/wait-times                     # Live wait times
GET /v1/parks/:slug/weather                        # Current weather
GET /v1/parks/:slug/weather/forecast               # 16-day forecast
GET /v1/parks/:slug/schedule                       # Operating hours
GET /v1/parks/:slug/schedule/:date                 # Schedule for specific date

Query Parameters:

  • continent, country, city — Filter by location
  • sort — Sort order (name, popularity, etc.)
  • include — Include related data (attractions, schedule, weather)

Example Response:

{
  "id": 1,
  "name": "Magic Kingdom",
  "slug": "magic-kingdom",
  "continent": "North America",
  "country": "United States",
  "city": "Orlando",
  "timezone": "America/New_York",
  "currentStatus": "OPERATING",
  "currentCrowdLevel": "MODERATE",
  "coordinates": { "lat": 28.3772, "lng": -81.5707 }
}

🎢 Attractions

Detailed attraction data with ML predictions and historical analytics.

GET /v1/attractions         # List all attractions
GET /v1/attractions/:slug   # Get attraction details

Response includes:

  • Live wait times and status (OPERATING, CLOSED, DOWN, REFURBISHMENT)
  • 24-hour ML-powered wait time forecasts
  • Daily predictions with confidence scores
  • Historical statistics (average, percentiles)
  • Downtime tracking and reliability metrics

Example Response:

{
  "id": 123,
  "name": "Space Mountain",
  "slug": "space-mountain",
  "parkSlug": "magic-kingdom",
  "category": "RIDE",
  "currentWaitTime": 45,
  "status": "OPERATING",
  "lastUpdate": "2025-12-23T19:30:00Z",
  "forecast": [
    { "hour": "20:00", "predictedWaitTime": 50, "confidence": 0.87 },
    { "hour": "21:00", "predictedWaitTime": 35, "confidence": 0.82 }
  ],
  "stats": {
    "averageWaitTime": 42,
    "p50": 40,
    "p75": 55,
    "p90": 70
  }
}

🌍 Geographic Discovery

Navigate parks by geographic hierarchy for route generation and exploration.

GET /v1/discovery/geo                        # Full geo hierarchy
GET /v1/discovery/continents                 # List continents
GET /v1/discovery/continents/:continent      # Countries in continent

Response Structure:

{
  "continents": [
    {
      "continent": "North America",
      "countries": [
        {
          "country": "United States",
          "cities": [
            {
              "city": "Orlando",
              "parks": [
                {
                  "name": "Magic Kingdom",
                  "url": "/north-america/united-states/orlando/magic-kingdom",
                  "attractions": [...]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

🏰 Destinations

Resort-level aggregation grouping multiple parks.

GET /v1/destinations        # List all destinations
GET /v1/destinations/:slug  # Get destination details

Examples:

  • Walt Disney World (Magic Kingdom, EPCOT, Hollywood Studios, Animal Kingdom)
  • Disneyland Paris (Disneyland Park, Walt Disney Studios Park)

🎭 Shows & Dining

Entertainment and dining options across all parks.

GET /v1/shows               # List all shows
GET /v1/shows/:slug         # Get show details
GET /v1/restaurants         # List all restaurants
GET /v1/restaurants/:slug   # Get restaurant details

Response includes:

  • Showtimes and schedules
  • Operating hours
  • Wait times (for restaurants)
  • Location and park information

🔍 Intelligent Search

Global search with enriched results across parks, attractions, shows, and restaurants.

GET /v1/search?q=disney               # Search all types
GET /v1/search?q=thunder&type=attraction   # Filter by type
GET /v1/search?q=paris                # Search by city

Search Features:

  • Multi-entity search: Parks, attractions, shows, restaurants
  • Geographic search: By city, country, or continent
  • Per-type counts: Shows returned vs total results
  • Enriched results: Coordinates, wait times, park hours, show times
  • Smart filtering: Type-based filtering with max 5 results per type
  • Fast response: Redis-cached for 5min, <3ms cached response

Response Structure:

{
  "query": "disney",
  "counts": {
    "park": {"returned": 5, "total": 13},
    "attraction": {"returned": 5, "total": 156}
  },
  "results": [
    {
      "type": "park",
      "name": "Disneyland Park",
      "status": "OPERATING",
      "load": "normal",
      "parkHours": {...},
      "coordinates": {...}
    },
    {
      "type": "attraction",
      "name": "Space Mountain",
      "waitTime": 45,
      "load": "higher",
      "parentPark": {...}
    }
  ]
}

🎉 Holidays

Public holiday data affecting park crowds and operating hours.

GET /v1/holidays/:isoCountryCode              # Holidays by country
GET /v1/holidays/:isoCountryCode/:year        # Holidays for specific year

📁 Project Structure

v4.api.park.fan/
├── src/
│   ├── config/                    # App configuration & environment
│   ├── common/                    # Shared utilities, filters, interceptors
│   ├── database/                  # Database utilities & migrations
│   ├── queues/                    # Bull queue setup & processors
│   ├── health/                    # Health check endpoints
│   ├── destinations/              # Resort/destination grouping
│   ├── parks/                     # Parks, weather, schedules
│   ├── attractions/               # Attractions & data sources
│   ├── shows/                     # Entertainment shows
│   ├── restaurants/               # Dining locations
│   ├── queue-data/                # Wait time data & history
│   ├── ml/                        # ML prediction integration
│   ├── analytics/                 # Statistics & analytics
│   ├── holidays/                  # Public holiday data
│   ├── date-features/             # Date-based features for ML
│   ├── discovery/                 # Geographic discovery endpoints
│   └── search/                    # Global search functionality
├── ml-service/                    # Python ML service (CatBoost)
│   ├── train.py                   # Model training script
│   ├── inference.py               # FastAPI prediction service
│   ├── features.py                # Feature engineering
│   └── db.py                      # Database connection
├── docker/                        # Docker configurations
├── scripts/                       # Utility & debug scripts
├── migrations/                    # Database migrations
└── test/                          # E2E tests

🐳 Docker Commands

# Start all services (PostgreSQL + Redis)
npm run docker:up

# Stop all services
npm run docker:down

# View logs
npm run docker:logs

# Restart services
npm run docker:restart

# Reset database (WARNING: deletes all data)
npm run db:reset

Production Deployment:

docker-compose -f docker-compose.production.yml up -d

🧪 Testing

# Run unit tests
npm run test

# Run e2e tests
npm run test:e2e

# Run all tests with coverage
npm run test:all:cov

# Watch mode for development
npm run test:watch

# Specific test file
npm run test -- wait-times.processor.spec.ts

Code Quality:

# Lint code
npm run lint

# Format code
npm run format

# Type check
npm run build

🔧 Environment Variables

Application Settings

NODE_ENV=development              # development | production | test
PORT=3000                         # API server port
API_PREFIX=v1                     # API version prefix

Database Configuration

# PostgreSQL with TimescaleDB
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=parkfan
DB_PASSWORD=your_secure_password
DB_DATABASE=parkfan
DB_SYNCHRONIZE=true               # ⚠️ Set to false in production!
DB_LOGGING=false                  # Enable for debugging
DB_SSL_ENABLED=false              # Enable for production

Caching & Queue

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=                   # Optional, recommended for production

# Bull Queue
BULL_PREFIX=parkfan

External APIs

# Google APIs (Geocoding, Places)
GOOGLE_API_KEY=your_google_api_key

# Weather Data
OPEN_WEATHER_API_KEY=your_openweather_key

# Data Sources (optional, for enhanced coverage)
QUEUE_TIMES_API_KEY=              # Queue-Times.com
THEMEPARKS_API_KEY=               # ThemeParks.wiki

ML Service

# ML Service Configuration
ML_SERVICE_URL=http://localhost:8000        # Development
# ML_SERVICE_URL=http://ml-service:8000     # Production (Docker)
MODEL_DIR=/app/models                       # Model storage directory
MODEL_VERSION=v1.1.0                        # Current model version

Sync & Processing

# Data Sync Intervals (cron expressions)
SYNC_WAIT_TIMES_CRON=*/5 * * * *           # Every 5 minutes
SYNC_PARK_METADATA_CRON=0 6 * * *          # Daily at 6 AM
SYNC_WEATHER_CRON=0 * * * *                # Hourly

🤝 Contributing

This is a private project. For questions or collaboration inquiries, please contact the maintainer.

📄 License

UNLICENSED — Private project by Patrick Arns

🙏 Powered By

This project aggregates data from multiple sources:

Special thanks to these services for making real-time theme park data accessible.

Made with ❤️ for theme park enthusiasts worldwide

API Documentation · Frontend

About

api.park.fan

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages