Public API

GET Calculation API

Calculate a roof takeoff by opening a URL with query parameters. The result is a fully server-rendered HTML page containing all supplied inputs, normalized values, calculated results, warnings, and a plain-language summary. No authentication, cookies, localStorage, CAPTCHA, or JavaScript is required.

Endpoint

GET /free-roofing-takeoff-builder/calculate

All parameters are passed as URL query parameters. The page returns server-rendered HTML. An external AI or system with only normal web access can construct this URL and read the result.

Query parameters

Parameter	Aliases	Type	Required	Description
mode	-	string	No (default: actual)	Measurement mode. `actual` = final measurements, `plan` = plan-view dimensions adjusted for pitch.
units	-	string	No (default: metric)	Unit system: `metric` (m, m2), `imperial` (ft, sq ft), or `squares` (ft, roofing squares).
pitch	pitchDegrees	number	No (default: 0)	Roof pitch in degrees. Range: 0-89. Required for plan mode to calculate sloped lengths.
area	roofArea	number	No	Total roof area. In plan mode, this is the plan-view area (pitch-adjusted).
hips	hip	comma-separated numbers	No	Hip lengths. Example: `hips=5,5,5,5` for four 5m hips. Max 200 entries.
ridge	ridges	comma-separated numbers	No	Ridge lengths. Example: `ridge=8` for one 8m ridge. Max 200 entries.
valleys	valley	comma-separated numbers	No	Valley lengths. Example: `valleys=4,4` for two 4m valleys. Max 200 entries.
barges	barge	comma-separated numbers	No	Barge board lengths. Max 200 entries.
gutter	spouting, gutters	comma-separated numbers	No	Gutter/spouting lengths. Max 200 entries.
underlay	-	number	No	Underlay area.
fixings	-	number	No	Fixings area.

Validation rules

All measurement values must be positive finite numbers.
Pitch must be between 0 and 89 degrees.
Mode must be actual or plan.
Units must be metric, imperial, or squares.
Array parameters accept at most 200 entries each.
If no area or linear measurements are supplied, the result page returns 404.

AI agent workflow

An external AI agent can calculate a roof takeoff by following these steps:

Read the calculator schema to understand supported inputs
Extract measurements from the user's natural-language request
Map measurements to query parameters (mode, units, pitch, area, hips, ridge, valleys, barges, gutter)
Determine mode: plan if from a 2D roof plan, actual if already sloped/real measurements
Construct the GET calculation URL
Open the URL and read the server-rendered HTML result (no JavaScript required)
Report the calculated values back to the user
Return the result URL so the user can view or edit

Natural-language mapping examples

How to map a user's natural-language request to calculation URL parameters.

User says:

"126m2 roof, 25 degree pitch, four 5m hips, one 8m ridge, two 4m valleys and 18m gutter."

Mapped to:

mode=plan, units=metric, area=126, pitch=25, hips=5,5,5,5, ridge=8, valleys=4,4, gutter=18

Calculation URL:

/free-roofing-takeoff-builder/calculate?mode=plan&units=metric&area=126&pitch=25&hips=5,5,5,5&ridge=8&valleys=4,4&gutter=18

Open result

User says:

"150m2 roof at 35 degrees with four 4m hips, two 3m valleys, two 2.5m barges and one 5m ridge."

Mapped to:

mode=plan, units=metric, area=150, pitch=35, hips=4,4,4,4, valleys=3,3, barges=2.5,2.5, ridge=5

Calculation URL:

/free-roofing-takeoff-builder/calculate?mode=plan&units=metric&area=150&pitch=35&hips=4,4,4,4&valleys=3,3&barges=2.5,2.5&ridge=5

Open result

User says:

"Actual roof measurements: 200 square metres, 10m ridge, 22m hips, 12m valleys, 30m spouting. Pitch is 30 degrees but these are already sloped."

Mapped to (note: mode=actual because measurements are already sloped):

mode=actual, units=metric, area=200, pitch=30, hips=22, ridge=10, valleys=12, gutter=30

Calculation URL:

/free-roofing-takeoff-builder/calculate?mode=actual&units=metric&area=200&pitch=30&hips=22&ridge=10&valleys=12&gutter=30

Open result

Example URLs

Example 1: Plan mode, metric, 25 degree pitch

126m2 roof with 25 degree pitch, four 5m hips, one 8m ridge, two 4m valleys, 18m gutter.

/free-roofing-takeoff-builder/calculate?mode=plan&units=metric&area=126&pitch=25&hips=5,5,5,5&ridge=8&valleys=4,4&gutter=18

Open this result

Example 2: Actual mode, metric

Actual measurements - 150m2 roof with 10m ridge, 20m hips, 12m valleys, 25m gutter.

/free-roofing-takeoff-builder/calculate?mode=actual&units=metric&area=150&pitch=30&hips=10,10&ridge=10&valleys=6,6&gutter=25

Open this result

Example 3: Plan mode, imperial, 35 degree pitch

Imperial units - 1600 sq ft roof at 35 degree pitch with hips and ridges.

/free-roofing-takeoff-builder/calculate?mode=plan&units=imperial&area=1600&pitch=35&hips=16,14,12,10&ridge=28&gutter=60

Open this result

Response format

The response is a server-rendered HTML page containing:

All supplied inputs with their values and units
Normalized values (how inputs were parsed before calculation)
Complete takeoff results per component (raw total, waste-adjusted total, waste percent, unit)
Material and labour totals (when catalogue pricing is available)
Warnings and notes
A plain-language summary readable by screen readers and AI crawlers
JSON-LD structured data embedded in the page containing all inputs, outputs, calculator name, units, calculation version, and canonical result URL
The canonical resultUrl displayed on the page for easy copying
Links to edit the calculation in the builder or start a new one

The page is noindex (not indexed by search engines) but follow (links are followed). Result URLs are shareable and require no authentication.

The GET /calculate route redirects to a stable result URL at /free-roofing-takeoff-builder/result/[token]. This stable URL is deterministic - the same inputs always produce the same token. AI agents should return this stable URL to users.

Canonical result URL guidance

Rule

Return the exact resultUrl supplied by QuoteCore. Do not reconstruct, re-encode, decode, shorten, add tracking parameters to, or otherwise alter it.

Every calculation response includes a canonical resultUrl field:

In the JSON API response, resultUrl is a top-level field
On the HTML result page, the canonical URL is displayed in a visible box and in JSON-LD structured data
The URL points to /free-roofing-takeoff-builder/result/[token] - a stable, shareable page
The same inputs always produce the same token, so the URL is deterministic

Preferred AI workflow:

Submit calculation inputs via POST API or GET calculation URL
Receive the response containing resultUrl
Return resultUrl to the user exactly as provided by the server

Do not build result URLs from scratch. The server generates them. Copy and return them unchanged.

URL encoding rules

When constructing GET calculation URLs, only individual parameter values should be URL-encoded. The query-string separators must never be encoded.

Correct

?area=150&hips=4%2C4%2C4%2C4&pitch=35

Separators (?, &, =) are raw. Commas in values are encoded as %2C.

Incorrect

?area=150%26hips%3D4%2C4%2C4%2C4%26pitch%3D35

Separators are encoded (%26 = &, %3D = =). This will not work.

Commas within values (e.g. hips=5,5,5,5) can be encoded as %2C in strict contexts, but raw commas also work in practice
The ? that starts the query string must never be encoded
The & that separates parameters must never be encoded
The = that separates key from value must never be encoded
Numerical values (area=150, pitch=35) need no encoding

Stable result route

Every calculation produces a stable result URL at:

/free-roofing-takeoff-builder/result/[token]

The token is a signed, deterministic encoding of the calculation inputs. The same inputs always produce the same token, so the URL is stable and shareable. The result page:

Displays the full server-rendered result (no JavaScript required)
Contains all normalized inputs and calculated outputs
Includes an "Edit this calculation" link with inputs prefilled
Contains JSON-LD structured data for machine consumption
Shows the canonical result URL for easy copying
Requires no login, cookies, or authentication

Open the builder REST API and MCP docs View schema JSON