Metadata-Version: 2.4
Name: timeplus-taxi-simulator
Version: 0.1.0
Summary: A generator for simulated NYC taxi data streams
Author-email: Gang Tao <gang@timeplus.com>
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Taxi Route Simulator

A generator for simulated NYC taxi data streams.

## Installation

```bash
pip install .
```

## Usage

### Command Line

Run the simulator and output JSON lines to stdout:

```bash
taxi-sim
```

### Python API

```python
from taxi_simulator import stream_taxi_data

for event in stream_taxi_data(num_cars=5, speed_kmh=80):
    print(f"Car {event['car_id']} is at {event['latitude']}, {event['longitude']}")
    
    if event['speed_kmh'] > 100:
        print("Warning: Speeding!")
```

## Parameters

| Parameter | Default | Description |
|-----------|---------|-------------|
| `num_cars` | 10 | Number of simulated cars |
| `speed_kmh` | 60.0 | Base speed in km/h (actual speed varies ±20%) |
| `update_interval` | 0.5 | Time between updates in seconds |
| `realtime_factor` | 5.0 | Speed multiplier for simulation |
| `custom_routes_file` | None | Path to custom routes JSON file |

## Output Format

Each event is a dictionary with the following fields:

```json
{
  "car_id": "car_0001",
  "time": "2024-01-15T12:30:45.123456+00:00",
  "longitude": -73.976964,
  "latitude": 40.755987,
  "speed_kmh": 62.4
}
```

## Custom Routes

You can provide your own routes file in JSON format. The simulator supports various GeoJSON-like structures and will automatically extract coordinate arrays. Example:

```json
[
  {
    "geometry": {
      "coordinates": [[-73.976, 40.755], [-73.975, 40.756]]
    }
  }
]
```

