---
title: "Locate a provenance span on the original page (bounding boxes)"
method: GET
path: "/v1/documents/{id}/span-geometry"
tags: ["Documents"]
---

# Locate a provenance span on the original page (bounding boxes)

`GET /v1/documents/{id}/span-geometry`

## Request

- Base URL: `https://api.talonic.com`
- URL: `https://api.talonic.com/v1/documents/{id}/span-geometry`
- Auth: HTTP bearer

Resolves a provenance `text` quote to rectangles on the ORIGINAL page of the
document — the server-side path for scanned (image-only) PDFs and image
uploads, where no client-side text-layer match is possible. The document's
own text layer is used when it has one; otherwise the page is OCR'd for word
boxes and the span is aligned to them. Results are cached per document.

Rectangles are **page fractions** in `[0, 1]` with a top-left origin. Render
your own copy of `page_index` at any DPI (or use the image as is) and multiply
by the rendered width and height:
`box = (left × W, top × H, width × W, height × H)`. For an image the fractions
are relative to the stored pixel grid — draw against the raw pixels (EXIF
orientation not applied). Render PDFs with a tool that honors the page's
`/Rotate`, as the server does.

Gate on `method`: `pdf_text_layer` and `ocr_word_boxes` are the exact span
window, `section` is the enclosing line (a region hint), `llm_vision` is a
model-located box verified against the page's own words, `page` means the page
was located but no rectangle aligned (`rects` empty), and `none` means nothing
was located (`page_index` null). An empty result is an honest miss — show no
highlight rather than a wrong one.

This is an interactive, per-click endpoint: a cold page costs several seconds
of OCR and pages are processed one at a time per API instance. One call per
organization is in flight at a time on this route; a concurrent second call
receives `429` with `Retry-After: 5`. Call it when a user selects a field, not
in bulk across a corpus. `text` longer than the configured maximum (500
characters by default) is truncated before matching.

## Path parameters

- `id` string, uuid, required

## Query parameters

- `text` string, required
- `page` integer

## Response `200`

Located rectangles, or an honest miss.

- object
  - `document_id` string, uuid, required
  - `page_index` integer, nullable, required: 0-based page the rectangles belong to; null when nothing was located.
  - `rects` object[], required: Page-fraction rectangles, one per text line. Empty for `page` and `none`.
    - `left` number, required
    - `top` number, required
    - `width` number, required
    - `height` number, required
  - `method` 'pdf_text_layer' | 'ocr_word_boxes' | 'section' | 'llm_vision' | 'page' | 'none', required

## Other responses

- `400`: Missing or repeated `text`, or `page` is not a single non-negative integer.
- `401`: Missing or invalid API key.
- `404`: The requested resource was not found.
- `429`: Another span-geometry call for this organization is in flight (`Retry-After: 5`), or the rate limit was exceeded.

---

[API](https://skmtc.dev/talonic/apis/talonic-api.md) · [All operations](https://skmtc.dev/talonic/apis/talonic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/talonic/apis/talonic-api/revisions/678fe5f8c9c3?raw)