# Traffic Signal Timing Calculator: Webster Cycle, Yellow, LOS (`jumblemog/traffic-signal-calculator`) Actor

Fixed-time traffic signal timing from plain text: Webster's cycle and green splits from phase volumes, ITE yellow and all-red intervals, pedestrian walk and clearance checks, and HCM capacity, v/c, delay and level of service, with a timing diagram.

- **URL**: https://apify.com/jumblemog/traffic-signal-calculator.md
- **Developed by:** [Jumble Mog](https://apify.com/jumblemog) (community)
- **Categories:** AI, Automation, Developer tools
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Traffic Signal Timing Calculator: Webster Cycle, Yellow, LOS

**Fixed-time signal timing from one line of text.** List the phases and their volumes (`phase 1: NB 450 vph 2 lanes, SB 380 vph 2 lanes; phase 2: EB 300 vph, WB 260 vph`), or ask for an approach's clearance intervals (`yellow and all-red for 45 mph, 3% downgrade, 80 ft intersection`). You get back:

- **Cycle and splits**: Webster's optimum cycle from the critical flow ratios and lost time, rounded up to 5 s and kept under a maximum, the shortest cycle for v/c 0.9, and effective and displayed green for each phase.
- **Clearance intervals**: the ITE yellow change interval from approach speed and grade, and the red clearance from the intersection width, or the values you give.
- **Pedestrians**: the green a crossing needs (walk plus flashing don't walk at 3.5 ft/s, with the yellow and all-red as buffer), and the cycle needed when phases fall short.
- **Performance**: capacity, v/c, HCM control delay and level of service for every movement, the critical v/c and the intersection's average delay and LOS.
- **Checks**: give a cycle and greens (`cycle 90 s, greens 40 30`) to rate an existing timing instead of designing one.
- **A chart**: the timing diagram for one cycle with each movement's delay coloured by LOS, or the yellow interval against approach speed.

US units (mph, ft) or metric (km/h, m); volumes in vehicles per hour.

It's made for:

- Traffic engineers and technicians making a first-cut timing or checking one in the field.
- Developers' consultants writing traffic impact studies.
- Transportation engineering students working Webster, clearance interval and LOS problems (and checking PE exam answers).
- AI agents that need correct signal timing numbers instead of a guess.

![A signal timing drawn by this Actor: a 40 s cycle with three phases shown as green, yellow and all-red bars, and below it the control delay of six movements from 15 to 22 s per vehicle coloured by level of service B and C](https://api.apify.com/v2/key-value-stores/Km5b4PG3kYHdZSb1E/records/traffic-signal-calculator-example.png?signature=1tskF3X5855OIKdtMp6Kw)

### How to use it

1. Write **Intersections and approaches**, one per entry. The form has examples.
2. Optionally set the **Units** for speeds and distances written without one (US by default).
3. Click **Start**. Each request is a row in the results, with its summary, chart and report.

#### What you can write

| You write | It means |
|---|---|
| `phase 1: NB 450 vph 2 lanes, SB 380 vph 2 lanes; phase 2: EB 300 vph, WB 260 vph` | Phases (split by `;` or `phase 2:`) and their movements' volumes and lanes |
| `critical flow ratios 0.25, 0.20, 0.15` or `critical lane volumes 650, 420, 300` | The critical values directly |
| `saturation flow 1900`, `PHF 0.92`, `lost time 4 s per phase` (or `12 s total`) | Capacity inputs (defaults 1800 veh/h/lane, PHF 1.0, 4 s per phase) |
| `45 mph`, `3% downgrade`, `70 ft intersection` | Approach speed, grade and width for the yellow and all-red |
| `yellow 4 s, all-red 1.5 s` | Fixed clearance intervals instead |
| `60 ft crosswalk`, `walk 7 s`, `walking speed 3.5 ft/s` | Pedestrian timing |
| `max cycle 120` | The longest cycle allowed (150 s by default) |
| `cycle 90 s, greens 40 30` | A timing to check |
| `yellow and all-red for 45 mph, 80 ft intersection` | Clearance intervals only |

The same as an object: `{"type": "timing", "phases": [{"name": "North-south", "movements": [{"name": "NB", "volume": 620, "lanes": 2}, {"name": "SB", "volume": 540, "lanes": 2}]}, {"name": "East-west", "movements": [{"name": "EB", "volume": 410}, {"name": "WB", "volume": 380}]}], "speed": "40 mph", "width": "60 ft"}`.

### Examples

- The three-phase intersection above, at 45 mph with a 70 ft intersection → Webster 37.8 s, cycle 40 s, greens 7, 10 and 5 s, yellow 4.3 s, all-red 1.4 s; critical v/c 0.56, average delay 16.8 s/veh (LOS B).
- `yellow and all-red for 45 mph, 3% downgrade, 80 ft intersection` → yellow 4.7 s (4.65), all-red 1.6 s (1.52).
- `critical lane volumes 650, 420, 300; saturation flow 1900; max cycle 120` → Webster 82 s, cycle 85 s, greens 34, 21 and 15 s; LOS D.
- `check: cycle 90 s, greens 40 30; NS 600 vph 2 lanes; EW 400 vph 1 lane, PHF 0.92` → EW v/c 0.70, 32.0 s/veh (LOS C); a warning that the greens and clearances add up to 80 s, not 90.

### How-to examples

Each example is a complete input; the results are from runs of the Actor (also listed under **Examples**).

#### How to time a fixed-time traffic signal (Webster's method)

```json
{"requests": ["signal timing: phase 1: NB 450 vph 2 lanes, SB 380 vph 2 lanes; phase 2: EB 300 vph, WB 260 vph; phase 3: NBL 180 vph, SBL 150 vph; 45 mph, 70 ft intersection, 60 ft crosswalk"]}
```

Result: Webster 37.8 s, cycle 40 s, greens 7, 10 and 5 s, yellow 4.3 s and all-red 1.4 s; critical v/c 0.56 and average delay 16.8 s/veh (LOS B).

#### How to calculate yellow and all-red clearance intervals (ITE)

```json
{"requests": ["yellow and all-red for 45 mph, 3% downgrade, 80 ft intersection"]}
```

Result: yellow 4.7 s (4.65) and all-red 1.6 s (1.52).

#### How to check the delay and level of service of an existing timing

```json
{"requests": ["check: cycle 90 s, greens 40 30; NS 600 vph 2 lanes; EW 400 vph 1 lane, PHF 0.92"]}
```

Result: EW v/c 0.70 and 32.0 s/veh (LOS C), with a warning that the greens and clearances add up to 80 s, not 90.

#### How to let an AI agent time signals

Add this Actor to the [Apify MCP server](https://mcp.apify.com) with `https://mcp.apify.com/?tools=jumblemog/traffic-signal-calculator`. The agent lists the phases and volumes in one line and answers with the cycle, the greens, the clearances and the level of service.

### FAQ

**Which methods does it use?** Webster's cycle and splits, the ITE clearance formulas and HCM uniform and incremental delay for the level of service.

**Does it do actuated or coordinated signals?** No. It times one fixed-time intersection, though the cycle and splits are the usual starting point for both.

**Which saturation flow does it use?** 1800 per lane by default, without the full HCM adjustments; give a measured or adjusted value for a better answer.

**Why is my cycle so short?** Light volumes give short cycles. Most agencies set a minimum (often 60 s); use `cycle` to set one.

### Input

| Field | What it is |
|---|---|
| `requests` | The intersections and approaches, as lines of text or objects (up to 200 per run) |
| `units` | For speeds and distances without a unit: `us` (mph, ft) or `metric` (km/h, m) |
| `charts` | Draw a chart for each request (default on) |

### Output

One dataset item per request, also saved together in the run's `OUTPUT` record:

```json
{
  "request": 1, "status": "ok", "type": "timing", "title": "Signal timing, 3 phases",
  "summary": "Cycle 40 s (Webster 38 s), greens 7, 10, 5 s, yellow 4.3 s, all-red 1.4 s; critical v/c 0.56, average delay 16.8 s/veh (LOS B).",
  "timing": {"cycle": 40, "webstersCycle": 37.81, "minimumCycle": 21.25, "lostTime": 12, "sumFlowRatios": 0.3917,
             "criticalVc": 0.56, "yellow": 4.3, "allRed": 1.36, "pedestrianGreen": 18.48, "averageDelay": 16.75,
             "los": "B"},
  "phases": [{"phase": "Phase 1", "flowRatio": 0.125, "effectiveGreen": 8.936, "green": 7.273, "yellow": 4.3,
              "allRed": 1.36, "start": 0, "end": 12.94}, "..."],
  "movements": [{"phase": "Phase 1", "movement": "NB", "volume": 450, "lanes": 2, "flowRatio": 0.125,
                 "capacity": 804.3, "vc": 0.56, "delay": 16.59, "los": "B"}, "..."],
  "units": {"time": "s", "volume": "veh/h", "speed": "mph", "length": "ft", "delay": "s/veh"},
  "imageUrl": "https://api.apify.com/v2/key-value-stores/.../records/001-Signal-timing-3-phases.png"
}
```

Clearance results have `clearance` (yellow and all-red, exact and rounded up to 0.1 s). Every item has `units`, `summary`, `warnings`, `notes` (the method and every assumed value), a Markdown `report` and links to the chart and report. A request that can't be computed has `"status": "failed"` and the reason in `error`, and isn't billed.

### How it works

1. **Flow ratios**: each movement's v/(N·s), with v the hourly volume divided by the PHF; a phase's critical ratio is its largest.
2. **Cycle**: Webster's C0 = (1.5L + 5)/(1 − Y), L the total lost time and Y the sum of critical ratios; rounded up to 5 s, at least 30 s and at most the maximum.
3. **Splits**: effective green (C − L)·yi/Y; displayed green = effective green − yellow − all-red + lost time per phase.
4. **Clearance**: ITE yellow t + v/(2a + 2Gg) with t 1 s and a 10 ft/s² (3.05 m/s²); all-red (W + L)/v with a 20 ft (6.1 m) vehicle.
5. **Delay**: HCM uniform delay 0.5·C·(1 − g/C)²/(1 − min(1, X)·g/C) plus incremental delay 900T\[(X − 1) + √((X − 1)² + 8kIX/(cT))], pretimed k 0.5 over 15 minutes; LOS A to F by delay.

### Pricing

You pay one low price per request, at the prices shown on this page; clearance-only requests cost less. The chart and report are included. Requests that can't be computed are never charged. If you set a maximum cost per run, the Actor stops before a request that wouldn't fit.

### Speed

Each request takes a few milliseconds. A run through the API answers in about 10 seconds, including the cloud container starting.

### Tips and limits

- **Fixed-time** timing for one intersection: actuated control, coordination and offsets aren't covered, though the cycle and splits are the usual starting point for both.
- **Saturation flow** is one value per lane (1800 by default); the full HCM adjustment factors for lane width, heavy vehicles, turns and so on aren't applied, so give a measured or adjusted value when you have one.
- **Webster** overstates the cycle near saturation (sum of ratios over about 0.85); the result warns, and Y of 1 or more can't be timed.
- **Short cycles** come out when volumes are light; most agencies set a minimum (often 60 s) for pedestrians and drivers' expectations; use `cycle` to set one.
- **Limits**: up to 8 phases per intersection and 200 requests per run.

### For AI agents and developers

This Actor works with the [Apify MCP server](https://mcp.apify.com), so AI agents can call it as a tool. Pass `requests` as plain text and read `summary`, `timing`, `phases`, `movements`, `clearance` and `warnings`. A direct API call that waits for the answer:

```bash
curl -X POST "https://api.apify.com/v2/acts/jumblemog~traffic-signal-calculator/run-sync-get-dataset-items?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"requests": ["phase 1: NB 450 vph 2 lanes, SB 380 vph 2 lanes; phase 2: EB 300 vph, WB 260 vph; 45 mph, 70 ft intersection"]}'
```

`run-sync` instead returns the run's `OUTPUT`: the status, the counts and every result as JSON.

In Python, with the `apify-client` package:

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_TOKEN")
run = client.actor("jumblemog/traffic-signal-calculator").call(run_input={
    "requests": [{"type": "timing", "speed": "40 mph", "width": "60 ft", "crosswalk": "50 ft",
                  "phases": [{"movements": [{"name": "NB", "volume": 620, "lanes": 2},
                                            {"name": "SB", "volume": 540, "lanes": 2}]},
                             {"movements": [{"name": "EB", "volume": 410}, {"name": "WB", "volume": 380}]}]}],
})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item["summary"])
```

### Credits

- Charts: [Vega-Lite](https://vega.github.io/vega-lite/) and [vl-convert](https://github.com/vega/vl-convert) (BSD-3-Clause), with the [Inter](https://rsms.me/inter/) font (SIL Open Font License).
- Methods: Webster, *Traffic Signal Settings* (1958); ITE, *Guidelines for Determining Traffic Signal Change and Clearance Intervals*; MUTCD 2009 section 4E.06; Highway Capacity Manual, signalized intersections.

# Actor input Schema

## `requests` (type: `array`):

One request per entry, as a line of text or an object. Timing: phases separated by ';' or 'phase 2:', each with its movements' volumes and lanes ('phase 1: NB 450 vph 2 lanes, SB 380 vph 2 lanes; phase 2: EB 300 vph, WB 260 vph'), or 'critical flow ratios 0.25, 0.20' or 'critical lane volumes 600, 450'; optional saturation flow (1800 veh/h/lane), lost time (4 s per phase, or 'total'), PHF, approach speed, grade and intersection width for the clearance intervals (or 'yellow 4 s, all-red 1 s'), a crosswalk length for pedestrian timing, and a maximum cycle. Give 'cycle 90 s, greens 40 30' to check a timing instead of designing one. Clearance: 'yellow and all-red for 45 mph, 3% downgrade, 80 ft intersection'. Object fields: type (timing or clearance), phases \[{name, movements: \[{name, volume, lanes, saturationFlow}]}], flowRatios, criticalVolumes, saturationFlow, lostTime, lostTotal, phf, cycle, greens, maxCycle, period (minutes), speed, grade (%), width, vehicleLength, reaction, deceleration, yellow, allRed, crosswalk, walk, walkSpeed, units, title, text.

## `units` (type: `string`):

For speeds and distances without a unit. mph or ft switch a request to US units; km/h or m to metric.

## `charts` (type: `boolean`):

The timing diagram with each movement's delay and LOS, or the yellow interval against approach speed.

## Actor input object example

```json
{
  "requests": [
    "signal timing: phase 1: NB 450 vph 2 lanes, SB 380 vph 2 lanes; phase 2: EB 300 vph, WB 260 vph; phase 3: NBL 180 vph, SBL 150 vph; 45 mph, 70 ft intersection, 60 ft crosswalk",
    "yellow and all-red for 45 mph, 3% downgrade, 80 ft intersection",
    "critical flow ratios 0.25, 0.20, 0.15; lost time 12 s total",
    "check: cycle 90 s, greens 40 30; NS 600 vph 2 lanes; EW 400 vph 1 lane, PHF 0.92",
    "intersection: phase A: main street 900 vph 2 lanes; phase B: side street 350 vph, 50 km/h, 20 m wide, crosswalk 14 m",
    {
      "type": "timing",
      "phases": [
        {
          "name": "North-south",
          "movements": [
            {
              "name": "NB",
              "volume": 620,
              "lanes": 2
            },
            {
              "name": "SB",
              "volume": 540,
              "lanes": 2
            }
          ]
        },
        {
          "name": "East-west",
          "movements": [
            {
              "name": "EB",
              "volume": 410,
              "lanes": 1
            },
            {
              "name": "WB",
              "volume": 380,
              "lanes": 1
            }
          ]
        }
      ],
      "saturationFlow": 1850,
      "speed": "40 mph",
      "width": "60 ft",
      "maxCycle": 120
    }
  ],
  "units": "us",
  "charts": true
}
```

# Actor output Schema

## `results` (type: `string`):

One row per request: the summary and chart.

## `output` (type: `string`):

The OUTPUT record: every result in one JSON object.

## `files` (type: `string`):

Charts (PNG and SVG) and Markdown reports in the run's key-value store.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "requests": [
        "signal timing: phase 1: NB 450 vph 2 lanes, SB 380 vph 2 lanes; phase 2: EB 300 vph, WB 260 vph; phase 3: NBL 180 vph, SBL 150 vph; 45 mph, 70 ft intersection, 60 ft crosswalk",
        "yellow and all-red for 45 mph, 3% downgrade, 80 ft intersection",
        "critical flow ratios 0.25, 0.20, 0.15; lost time 12 s total",
        "check: cycle 90 s, greens 40 30; NS 600 vph 2 lanes; EW 400 vph 1 lane, PHF 0.92",
        "intersection: phase A: main street 900 vph 2 lanes; phase B: side street 350 vph, 50 km/h, 20 m wide, crosswalk 14 m",
        {
            "type": "timing",
            "phases": [
                {
                    "name": "North-south",
                    "movements": [
                        {
                            "name": "NB",
                            "volume": 620,
                            "lanes": 2
                        },
                        {
                            "name": "SB",
                            "volume": 540,
                            "lanes": 2
                        }
                    ]
                },
                {
                    "name": "East-west",
                    "movements": [
                        {
                            "name": "EB",
                            "volume": 410,
                            "lanes": 1
                        },
                        {
                            "name": "WB",
                            "volume": 380,
                            "lanes": 1
                        }
                    ]
                }
            ],
            "saturationFlow": 1850,
            "speed": "40 mph",
            "width": "60 ft",
            "maxCycle": 120
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("jumblemog/traffic-signal-calculator").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "requests": [
        "signal timing: phase 1: NB 450 vph 2 lanes, SB 380 vph 2 lanes; phase 2: EB 300 vph, WB 260 vph; phase 3: NBL 180 vph, SBL 150 vph; 45 mph, 70 ft intersection, 60 ft crosswalk",
        "yellow and all-red for 45 mph, 3% downgrade, 80 ft intersection",
        "critical flow ratios 0.25, 0.20, 0.15; lost time 12 s total",
        "check: cycle 90 s, greens 40 30; NS 600 vph 2 lanes; EW 400 vph 1 lane, PHF 0.92",
        "intersection: phase A: main street 900 vph 2 lanes; phase B: side street 350 vph, 50 km/h, 20 m wide, crosswalk 14 m",
        {
            "type": "timing",
            "phases": [
                {
                    "name": "North-south",
                    "movements": [
                        {
                            "name": "NB",
                            "volume": 620,
                            "lanes": 2,
                        },
                        {
                            "name": "SB",
                            "volume": 540,
                            "lanes": 2,
                        },
                    ],
                },
                {
                    "name": "East-west",
                    "movements": [
                        {
                            "name": "EB",
                            "volume": 410,
                            "lanes": 1,
                        },
                        {
                            "name": "WB",
                            "volume": 380,
                            "lanes": 1,
                        },
                    ],
                },
            ],
            "saturationFlow": 1850,
            "speed": "40 mph",
            "width": "60 ft",
            "maxCycle": 120,
        },
    ] }

# Run the Actor and wait for it to finish
run = client.actor("jumblemog/traffic-signal-calculator").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "requests": [
    "signal timing: phase 1: NB 450 vph 2 lanes, SB 380 vph 2 lanes; phase 2: EB 300 vph, WB 260 vph; phase 3: NBL 180 vph, SBL 150 vph; 45 mph, 70 ft intersection, 60 ft crosswalk",
    "yellow and all-red for 45 mph, 3% downgrade, 80 ft intersection",
    "critical flow ratios 0.25, 0.20, 0.15; lost time 12 s total",
    "check: cycle 90 s, greens 40 30; NS 600 vph 2 lanes; EW 400 vph 1 lane, PHF 0.92",
    "intersection: phase A: main street 900 vph 2 lanes; phase B: side street 350 vph, 50 km/h, 20 m wide, crosswalk 14 m",
    {
      "type": "timing",
      "phases": [
        {
          "name": "North-south",
          "movements": [
            {
              "name": "NB",
              "volume": 620,
              "lanes": 2
            },
            {
              "name": "SB",
              "volume": 540,
              "lanes": 2
            }
          ]
        },
        {
          "name": "East-west",
          "movements": [
            {
              "name": "EB",
              "volume": 410,
              "lanes": 1
            },
            {
              "name": "WB",
              "volume": 380,
              "lanes": 1
            }
          ]
        }
      ],
      "saturationFlow": 1850,
      "speed": "40 mph",
      "width": "60 ft",
      "maxCycle": 120
    }
  ]
}' |
apify call jumblemog/traffic-signal-calculator --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,jumblemog/traffic-signal-calculator"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/AuFMmvvArCO8WQcIw/builds/S0xowUMH7uBktcd3t/openapi.json
