---
title: "Areas, perimeters and lengths from points read off a plan, sketch or photo, scaled by one known reference"
method: POST
path: "/sketch"
tags: ["House and canvas"]
---

# Areas, perimeters and lengths from points read off a plan, sketch or photo, scaled by one known reference

`POST /sketch`

## Request

- Base URL: `https://api.craftquantities.com/v1`
- URL: `https://api.craftquantities.com/v1/sketch`
- Auth: none declared

Points in the image's pixels and one reference; no image is sent. Returns the figures in both systems with an uncertainty band, closure and crossing checks, and a link that opens the scaled shapes on the canvas.

## Query parameters

- `detail` 'full' | 'summary': full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read.
- `format` 'json' | 'md'

## Request body

- object
  - `shapes` object[], required: The outlines and lines read off the image, in its pixels.
    - `kind` 'area' | 'length', required: area: a closed outline (a floor, a slab, a roof plane on plan); length: a line or a path (a fence, a footing, a run).
    - `name` string
    - `points` object[], required: In order round the outline or along the path.
      - `x` number, required
      - `y` number, required
    - `closed` boolean: A length only: the path closes back to its first point.
    - `as` 'measure' | 'room' | 'slab' | 'floor' | 'patio' | 'deck' | 'driveway' | 'landscaping' | 'roof' | 'fence' | 'footing' | 'retaining-wall': What it is drawn as on the canvas: a kept measure (the default), or a room (walls round it), slab, floor, patio, deck, driveway, landscaping or roof outline; a fence, footing or retaining wall path. A component is listed with its materials.
    - `calculator` object: A calculator the figure goes into, run on the figure and on both ends of its band (at most 10 per request).
      - `slug` string, required
      - `input` string, required: The id of the calculator's input that takes the figure.
      - `figure` 'area' | 'perimeter' | 'length'
      - `inputs` object: The calculator's input values, by input id (an unknown id is refused with the accepted ids). A length, area, volume or other measured input takes "12 ft", "3.5 m", "8' 3 1/2\"" or {"value": 12, "unit": "ft"}; a count or percentage takes a number; a select takes one of its option values. Inputs left out take the value the calculator's page opens on.
  - `reference` object, required: ONE known size in the same image: a figured dimension, or an object of known size by its four corners.
    - `dimension` object
      - `from` object, required: A point in the image's own pixels: x to the right, y down from the top-left corner.
        - `x` number, required
        - `y` number, required
      - `to` object, required: A point in the image's own pixels: x to the right, y down from the top-left corner.
        - `x` number, required
        - `y` number, required
      - `length` union, required
        - number
        - string
        - object
          - `value` number, required
          - `unit` string
      - `tolerance` union: How far the figure itself may be off (a dimension rounded to the nearest 10 mm: 5 mm).
        - number
        - string
        - object
          - `value` number, required
          - `unit` string
    - `object` 'card' | 'a4' | 'letter' | 'custom': card: ISO/IEC 7810 ID-1 (85.60 × 53.98 mm); a4: 210 × 297 mm; letter: 8.5 × 11 in; custom: width and height given.
    - `width` union
      - number
      - string
      - object
        - `value` number, required
        - `unit` string
    - `height` union
      - number
      - string
      - object
        - `value` number, required
        - `unit` string
    - `corners` object[]: Top-left, top-right, bottom-right, bottom-left; the width runs from the first to the second.
      - `x` number, required
      - `y` number, required
  - `pixelError` number: How far any point may be off, in pixels: it sets the band.
  - `system` 'metric' | 'imperial': The unit system inputs left out open in, and the one the page link opens in. The answer comes in both.
  - `inputUnits` 'base': Send "base" to pass bare numbers on dimensioned inputs in base units (m, m², L, kg …), as the published test vectors are written. Without it a length, area or volume must carry its unit.

## Response `200`

The scale, each shape's figures and band, and the canvas link.

- union
  - object
    - `engine` object, required
    - `system` 'metric' | 'imperial', required
    - `scale` object, required
    - `shapes` object[], required
      - `name` string, required
      - `kind` 'area' | 'length', required
      - `as` string, required
      - `points` integer, required
      - `closed` boolean, required
      - `closure` string
      - `area` object
        - `m2` number, required
        - `ft2` number, required
        - `low` object, required
        - `high` object, required
        - `text` string, required
      - `perimeter` object
        - `m` number, required
        - `ft` number, required
        - `low` object, required
        - `high` object, required
        - `text` string, required
      - `length` object
        - `m` number, required
        - `ft` number, required
        - `low` object, required
        - `high` object, required
        - `text` string, required
      - `uncertaintyPercent` object, required
      - `calculator` object
    - `rows` object[]
    - `notMeasured` string[]: What the canvas could not measure among the components drawn, and why (a patio, deck or driveway outline that is not square-cornered is drawn, not measured).
    - `document` object, required
    - `links` object, required
      - `canvas` string, required
      - `drawing` string, nullable, required: Opens the scaled shapes on the canvas; the drawing rides in the fragment, so nothing is uploaded.
      - `page` string, required: The site's Photo Takeoff page, whose geometry this is.
    - `drawingLink` string, required
    - `accuracy` string[], required
    - `privacy` string, required
    - `citation` object, required
      - `author` string, required
      - `title` string, required
      - `version` string, nullable
      - `sourcesChecked` string, nullable
      - `url` string, required
      - `accessDate` string, nullable, required
      - `formats` object, required
        - `plain` string, required
        - `apa` string, required
        - `harvard` string, required
        - `bibtex` string, required
    - `licence` object, required
      - `name` string, required
      - `url` string, required
      - `attribution` string, required
    - `notice` string, required
  - object
    - `detail` 'summary', required
    - `tool` string, required
    - `title` string, required
    - `lines` object[], required: The result lines, as the report's table gives them.
    - `notes` string[], required: What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary.
    - `citation` string, required: The one citation line, built from the answer's own data.
    - `url` string, nullable, required
    - `open` string, nullable, required
    - `more` string, nullable, required

## Other responses

- `400`: The request was refused; every problem is listed.
- `404`: The request was refused; every problem is listed.
- `413`: The request was refused; every problem is listed.

---

[API](https://skmtc.dev/craftquantities/apis/craft-quantities-engine-api.md) · [All operations](https://skmtc.dev/craftquantities/apis/craft-quantities-engine-api/llms.txt) · [OpenAPI document](https://skmtc.dev/craftquantities/apis/craft-quantities-engine-api/revisions/a69883abc23b?raw)