# Road Geometry Calculator: Horizontal & Vertical Curves (`jumblemog/road-geometry-calculator`) Actor

AASHTO road curve design from plain text: stopping sight distance, minimum radius and K for a design speed; horizontal curves with PC/PT stations and stakeout; vertical curves with elevations, high or low point and the length for sight distance, with a chart.

- **URL**: https://apify.com/jumblemog/road-geometry-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

## Road Geometry Calculator: Horizontal & Vertical Curves

**Highway curve design by the AASHTO Green Book, from one line of text.** Type `design speed 60 mph`, `horizontal curve R 1000 ft, delta 40°, PI 25+00, 50 mph` or `crest curve from +2% to -3%, 60 mph, PVI 12+00, elevation 500 ft`. You get back:

- **Design speed values**: stopping sight distance (and on grades from -9% to +9%), side friction, minimum radius for an e max, degree of curve, and the K values for crest and sag vertical curves, matching the Green Book tables.
- **Horizontal curves**: tangent, curve length, long chord, external, middle ordinate, PC and PT stations, and a stakeout table of deflection angles and chords from the PC at even stations. With a design speed: the minimum radius, the superelevation needed and the sight-line offset for stopping sight distance.
- **Vertical curves**: PVC and PVT stations and elevations, elevations along the curve (tangent, offset, curve), the high or low point, K and the rate of change. With a design speed: the length needed for stopping sight distance (or the shortest curve, rounded up, when you leave the length out), the sight distance it provides and the comfort length for sags.
- **A chart**: sight distance and minimum radius against speed, the curve in plan with its PC, PI and PT, or the vertical profile with the tangents and the high or low point.

US customary (mph, ft, 12+34.56 stations) or metric (km/h, m, 1+234.567 stations), as the Green Book does; results come back in the units you wrote.

It's made for:

- Civil engineers and highway designers checking alignments.
- Surveyors staking out curves in the field.
- Civil engineering students working Green Book and FE/PE exam problems.
- AI agents that need correct curve geometry instead of a guess.

![A crest vertical curve drawn by this Actor, from +2% to -3% over 760 ft for 60 mph: the dashed tangents meet at the PVI 12+00.00 at elevation 500 ft, and the blue parabola runs from the PVC 8+20.00 through the high point at 11+24.00, elevation 495.44 ft, to the PVT 15+80.00](https://api.apify.com/v2/key-value-stores/Km5b4PG3kYHdZSb1E/records/road-geometry-calculator-example.png?signature=1P6QqWzJ1wuSpN8KWgRcV)

### How to use it

1. Write **Design speeds and curves**, one per entry. The form has examples.
2. Optionally set the **Units** for requests written without one.
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 |
|---|---|
| `60 mph`, `100 km/h` | The design speed |
| `e max 6%` | Maximum superelevation (8% by default) |
| `downgrade 5%`, `grade +4%` | Grade for the stopping sight distance |
| `reaction time 2 s` | Brake reaction time (2.5 s by default) |
| `R 1000 ft`, `radius 300 m`, `4° curve` | Radius, or degree of curve (arc definition) |
| `delta 40°`, `deflection 35°20'15"` | Deflection (central) angle |
| `PI 25+00`, `PI 1+234.567` | PI station |
| `every 25 ft`, `interval 20 m` | Stakeout or elevation interval (50 ft or 20 m by default) |
| `from +2% to -3%`, `g1 -4%, g2 +1.5%` | Grades into and out of a vertical curve |
| `L 600 ft`, `K 151` | Vertical curve length, or K |
| `PVI 12+00, elevation 500 ft` | PVI station and elevation |

The same as an object: `{"type": "horizontal", "degree": 4, "delta": "25d30'", "pi": "40+00", "speed": "55 mph"}` or `{"type": "vertical", "g1": 2, "g2": -3, "speed": "60 mph", "pvi": "12+00", "elevation": "500 ft"}`.

### Examples

- `design speed 60 mph` → stopping sight distance 570 ft; minimum radius 1200 ft at e max 8%; K 151 crest, 136 sag.
- `100 km/h, e max 6%` → 185 m; minimum radius 437 m; K 52 crest, 45 sag.
- `horizontal curve R 1000 ft, delta 40°, PI 25+00, 50 mph` → T 363.97, L 698.13, LC 684.04, E 64.18, M 60.31 ft; PC 21+36.03, PT 28+34.16; radius OK (758 ft needed).
- `crest curve from +2% to -3%, 60 mph, PVI 12+00, elevation 500 ft` → L 760 ft; PVC 8+20.00 el. 492.400, PVT 15+80.00 el. 488.600; high point at 11+24.00, el. 495.440.
- `sag vertical curve g1 -4%, g2 +1.5%, L 200 m, PVI 2+500, elev 120 m, 90 km/h` → low point at 2+545.455, el. 121.091; too short for 90 km/h (K 38 needed).

### How-to examples

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

#### How to find the stopping sight distance and minimum radius for a design speed

```json
{"requests": ["design speed 60 mph"]}
```

Result: stopping sight distance 570 ft; minimum radius 1200 ft at e max 8%; K 151 for crest and 136 for sag curves. In metric, `100 km/h, e max 6%` gives 185 m, 437 m and K 52 / 45.

#### How to calculate a horizontal curve's elements and stations

```json
{"requests": ["horizontal curve R 1000 ft, delta 40°, PI 25+00, 50 mph"]}
```

Result: T 363.97, L 698.13, LC 684.04, E 64.18 and M 60.31 ft; PC 21+36.03 and PT 28+34.16; the radius is OK (758 ft needed).

#### How to design a crest vertical curve

```json
{"requests": ["crest curve from +2% to -3%, 60 mph, PVI 12+00, elevation 500 ft"]}
```

Result: L 760 ft; PVC 8+20.00 at el. 492.400 and PVT 15+80.00 at el. 488.600; the high point is at 11+24.00, el. 495.440.

#### How to let an AI agent do highway curve design

Add this Actor to the [Apify MCP server](https://mcp.apify.com) with `https://mcp.apify.com/?tools=jumblemog/road-geometry-calculator`. The agent passes the speed or the curve in one line and answers with the Green Book values, curve elements and stations.

### FAQ

**Which standard does it follow?** AASHTO's *A Policy on Geometric Design of Highways and Streets* (the Green Book, 2018). State DOT manuals, TAC, DMRB and Austroads can differ.

**Does it check sag curves?** Yes: `sag vertical curve g1 -4%, g2 +1.5%, L 200 m, PVI 2+500, elev 120 m, 90 km/h` gives the low point at 2+545.455 and says the curve is too short (K 38 needed).

**Does it give stake-out data?** Yes: stations and deflection angles from the PC for horizontal curves, and elevations along vertical curves.

**What isn't covered?** Spirals, compound and reverse curves, superelevation runoff and widening. Give each simple curve on its own.

### Input

| Field | What it is |
|---|---|
| `requests` | The design speeds and curves, as lines of text or objects (up to 200 per run) |
| `units` | For requests without a unit: `m` (metric) or `ft` (US) |
| `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": 3, "status": "ok", "type": "horizontal", "title": "Horizontal curve R 1000 ft, Δ 40°00'00.00\"",
  "summary": "T 363.97, L 698.13, LC 684.04, E 64.18, M 60.31 ft; PC 21+36.03, PT 28+34.16; R ≥ 757.58 ft for 50 mph: OK.",
  "curve": {"radius": 1000.0, "delta": 40.0, "deltaDms": "40°00'00.00\"", "degreeOfCurve": 5.7296, "tangent": 363.97,
            "length": 698.13, "longChord": 684.04, "external": 64.178, "middleOrdinate": 60.307},
  "stations": {"pc": "21+36.03", "pi": "25+00.00", "pt": "28+34.16", "pcValue": 2136.03, "ptValue": 2834.16},
  "stakeout": [{"station": "21+50.00", "arc": 13.97, "deflection": "0°24'00.78\"", "chord": 13.97}, "..."],
  "check": {"speed": 50.0, "emax": 8.0, "fmax": 0.14, "minRadius": 757.58, "radiusOk": true,
            "superelevationAtFmax": 2.67, "stoppingSightDistance": 425.0, "sightLineOffset": 22.493},
  "units": {"length": "ft", "speed": "mph", "grade": "%", "angle": "°", "station": "100 ft"},
  "imageUrl": "https://api.apify.com/v2/key-value-stores/.../records/003-Horizontal-curve-R-1000-ft.png"
}
```

Design speeds have `design` and `grades`; vertical curves have `curve`, `stations`, `elevations` and, with a speed, `check`. Every item has `units`, `summary`, `warnings`, `notes` (the method and assumptions), 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

All from AASHTO *A Policy on Geometric Design of Highways and Streets* (the Green Book, 2018):

1. **Stopping sight distance**: 1.47·V·t + 1.075·V²/a (US) or 0.278·V·t + 0.039·V²/a (metric), t = 2.5 s and a = 11.2 ft/s² (3.4 m/s²), rounded up to 5; on grades V²/(30(a/32.2 ± G)).
2. **Minimum radius**: V²/(15(e + f)) or V²/(127(e + f)) with the side friction factors of Table 3-7.
3. **Horizontal curves**: T = R·tan(Δ/2), L = π·R·Δ/180, LC = 2R·sin(Δ/2), E = R(sec(Δ/2) − 1), M = R(1 − cos(Δ/2)); deflections from the PC are arc/(2R); the sight-line offset is R(1 − cos(S/2R)).
4. **Vertical curves**: the equal-tangent parabola y = y_PVC + g1·x + (A/2L)·x², with the high or low point at x = −g1·L/A. Crest lengths for stopping sight distance use a 3.5 ft eye and 2.0 ft object (1.08 m and 0.60 m); sag lengths use headlight sight distance; K = L/|A|, rounded as in the Green Book tables.

### Pricing

You pay one low price per request, at the prices shown on this page; design-speed values cost less than curves. 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

- **Spirals** (transition curves), compound and reverse curves, superelevation runoff and widening aren't covered; give each simple curve on its own.
- **Sight-line offset** assumes the sight distance fits within the curve; when it's longer, the tangents matter and the note says so.
- **Degree of curve** uses the arc definition (100 ft of arc); railways use the chord definition.
- **Local standards** (state DOT manuals, TAC, DMRB, Austroads) can differ from the Green Book; check the values your agency requires.
- **Limits**: design speeds 15 to 80 mph or 20 to 130 km/h; 200 requests per run; tables up to 400 rows.

### 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`, `design`, `curve`, `stations`, `check` and `warnings`. A direct API call that waits for the answer:

```bash
curl -X POST "https://api.apify.com/v2/acts/jumblemog~road-geometry-calculator/run-sync-get-dataset-items?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"requests": ["crest curve from +2% to -3%, 60 mph, PVI 12+00, elevation 500 ft"]}'
```

`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/road-geometry-calculator").call(run_input={
    "requests": [{"type": "horizontal", "radius": "300 m", "delta": "35°20'15\"", "pi": "1+234.567", "speed": "80 km/h"}],
})
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: AASHTO, *A Policy on Geometric Design of Highways and Streets*, 7th edition (2018), chapter 3.

# Actor input Schema

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

One request per entry, as a line of text or an object. Design speed ('60 mph', '100 km/h', with 'e max 6%', 'downgrade 5%', 'reaction time 2 s'): stopping sight distance, minimum radius, side friction and K for crest and sag curves. Horizontal curve: the radius ('R 1000 ft', 'radius 300 m') or degree of curve ('4° curve'), the deflection angle ('delta 40°', 'deflection 35°20'15"') and the PI station ('PI 25+00', 'PI 1+234.567'): tangent, length, long chord, external, middle ordinate, PC and PT stations and a stakeout table ('every 25 ft'); add a design speed to check the radius, superelevation and sight-line offset. Vertical curve: both grades ('from +2% to -3%', 'g1 -4%, g2 +1.5%'), the length ('L 600 ft') or K, the PVI station and elevation ('PVI 12+00, elevation 500 ft'): PVC and PVT, elevations along the curve, the high or low point; with a design speed, the length needed for stopping sight distance (leave the length out to get the shortest). Object fields: type (design, horizontal or vertical), speed, emax, grade, reactionTime, deceleration, radius, degree, delta, pi, interval, g1, g2, length, k, pvi, elevation, kind, units, title, text.

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

For requests without a unit. mph, ft or 12+34.56 stations switch to US units on their own, km/h, m or 1+234.567 stations to metric.

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

Stopping sight distance and minimum radius by speed, the curve in plan, or the vertical curve's profile.

## Actor input object example

```json
{
  "requests": [
    "design speed 60 mph",
    "100 km/h, e max 6%",
    "horizontal curve R 1000 ft, delta 40°, PI 25+00, 50 mph",
    "radius 300 m, deflection 35°20'15\", PI 1+234.567, 80 km/h",
    "crest curve from +2% to -3%, 60 mph, PVI 12+00, elevation 500 ft",
    "sag vertical curve g1 -4%, g2 +1.5%, L 200 m, PVI 2+500, elev 120 m, 90 km/h",
    {
      "type": "horizontal",
      "degree": 4,
      "delta": "25d30'",
      "pi": "40+00",
      "speed": "55 mph"
    }
  ],
  "units": "m",
  "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": [
        "design speed 60 mph",
        "100 km/h, e max 6%",
        "horizontal curve R 1000 ft, delta 40°, PI 25+00, 50 mph",
        "radius 300 m, deflection 35°20'15\", PI 1+234.567, 80 km/h",
        "crest curve from +2% to -3%, 60 mph, PVI 12+00, elevation 500 ft",
        "sag vertical curve g1 -4%, g2 +1.5%, L 200 m, PVI 2+500, elev 120 m, 90 km/h",
        {
            "type": "horizontal",
            "degree": 4,
            "delta": "25d30'",
            "pi": "40+00",
            "speed": "55 mph"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("jumblemog/road-geometry-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": [
        "design speed 60 mph",
        "100 km/h, e max 6%",
        "horizontal curve R 1000 ft, delta 40°, PI 25+00, 50 mph",
        "radius 300 m, deflection 35°20'15\", PI 1+234.567, 80 km/h",
        "crest curve from +2% to -3%, 60 mph, PVI 12+00, elevation 500 ft",
        "sag vertical curve g1 -4%, g2 +1.5%, L 200 m, PVI 2+500, elev 120 m, 90 km/h",
        {
            "type": "horizontal",
            "degree": 4,
            "delta": "25d30'",
            "pi": "40+00",
            "speed": "55 mph",
        },
    ] }

# Run the Actor and wait for it to finish
run = client.actor("jumblemog/road-geometry-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": [
    "design speed 60 mph",
    "100 km/h, e max 6%",
    "horizontal curve R 1000 ft, delta 40°, PI 25+00, 50 mph",
    "radius 300 m, deflection 35°20'\''15\\", PI 1+234.567, 80 km/h",
    "crest curve from +2% to -3%, 60 mph, PVI 12+00, elevation 500 ft",
    "sag vertical curve g1 -4%, g2 +1.5%, L 200 m, PVI 2+500, elev 120 m, 90 km/h",
    {
      "type": "horizontal",
      "degree": 4,
      "delta": "25d30'\''",
      "pi": "40+00",
      "speed": "55 mph"
    }
  ]
}' |
apify call jumblemog/road-geometry-calculator --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,jumblemog/road-geometry-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/nVzNqSZlU9ji3YGoq/builds/LUkWPHaZ6jHsXysow/openapi.json
