Ground Extracted Fields

The Ground API maps each field extracted by Extract back to the blocks it was quoted from in the Parse response, and returns each one with its id, page number, and bounding box. A block is one piece of content Parse detected on a page, such as a paragraph, a table, a single table cell, or a figure. Extract already locates every value in the Markdown text through range grounding. Ground turns those text locations into visual ones, so you can highlight values on a rendering of the page, build review interfaces where a person clicks a field and sees where it came from, attach citations to extracted data, or crop the region a value appears in. Ground runs synchronously and consumes no credits.

How Ground Works

Both objects you send describe positions in the same Markdown string. A field’s ranges say which characters the value was quoted from. A block’s grounding.range says which characters the block covers. Ground overlaps the two and returns every block a field’s ranges fall inside. The join is stateless. Nothing is stored server-side, and the block ids in the response resolve only against the structure you send in the same request. You send two objects you already have from earlier responses:

extraction_metadata: the per-field metadata returned by Extract, whose leaves are {value, ranges} objects.
structure: the block tree returned by Parse, whose blocks each carry a grounding object.

Pair the Extraction with Its Own Parse

The extraction_metadata must come from an Extract call that ran on the markdown of the same Parse response the structure came from. Re-parsing invalidates an older extraction, because block ranges shift between parses even of the same file. If the locations come back wrong, see Troubleshoot Grounding. Ground cannot detect a mismatched pair, so check it in code. The Extract response’s metadata.doc_id carries the job_id of the parse whose markdown it read:

assert extract_response.metadata.doc_id == parse_response.metadata.job_id

Call the Ground API

Send both objects to the ground endpoint with a POST request. The endpoint accepts a JSON body (used by the libraries below) or multipart form data with each field JSON-serialized (used in the cURL example). The cURL example assumes you saved the Parse response to parse.json and the Extract response to extract.json.

jq '.structure' parse.json > structure.json
jq '.extraction_metadata' extract.json > extraction-metadata.json

curl -X POST 'https://api.ade.landing.ai/v2/ground' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'extraction_metadata=<extraction-metadata.json' \
  -F 'structure=<structure.json'

from pathlib import Path
from landingai_ade import LandingAIADE

client = LandingAIADE()

parse_response = client.v2.parse(
    document=Path("document.pdf"),
    model="dpt-3-pro-latest",
)

extract_response = client.v2.extract(
    markdown=parse_response.markdown,
    schema={
        "type": "object",
        "properties": {
            "report_number": {"type": "string", "description": "The report number"},
            "serial_number": {"type": "string", "description": "The serial number of the instrument under test"},
            "purchase_order": {"type": "string", "description": "The purchase order number"},
        },
    },
)

ground_response = client.v2.ground(
    extraction_metadata=extract_response.extraction_metadata,
    structure=parse_response.structure,
)
print(ground_response.grounding)

import fs from "fs";
import LandingAIADE from "landingai-ade";

const client = new LandingAIADE();

const parseResponse = await client.v2.parse({
  document: fs.createReadStream("document.pdf"),
  model: "dpt-3-pro-latest",
});

const extractResponse = await client.v2.extract({
  markdown: parseResponse.markdown,
  schema: {
    type: "object",
    properties: {
      report_number: { type: "string", description: "The report number" },
      serial_number: { type: "string", description: "The serial number of the instrument under test" },
      purchase_order: { type: "string", description: "The purchase order number" },
    },
  },
});

const groundResponse = await client.v2.ground({
  extraction_metadata: extractResponse.extraction_metadata,
  structure: parseResponse.structure,
});
console.log(groundResponse.grounding);

For the full request and response contract, see the API reference.

The Grounding Tree

The response’s grounding field mirrors your extraction_metadata tree: nested objects and arrays keep their shape, so a nested field like issuer.name resolves to grounding.issuer.name. Each {value, ranges} leaf is replaced by one of three values:

Leaf value	What it means
A list of blocks	The blocks the field’s ranges overlap, in reading order.
`null`	The field’s `ranges` was `null`, so nothing in the document was quoted for it. Either the model synthesized the value or it did not find one. There is no source passage to look up.
`[]`	The ranges were valid but overlapped no block. This usually means the `extraction_metadata` and `structure` are from different parses. See Pair the Extraction with Its Own Parse.

Matching Blocks

Only content blocks are returned. The page nodes in the structure never appear, because pages are containers rather than content. Each returned block reports its own page number in grounding.page instead. A field with multiple ranges pools the blocks from all of them, without duplicates. A single range can still match more than one block: a value inside a table matches both the table and the table_cell that contains it, so you can highlight the whole table or just the cell. Each entry in the list identifies one block from the structure you sent:

Field	Description
`block_id`	The block’s `id` in the `structure` tree, such as `text-1` or `table_cell-3`. Use it to look the block up. Block ids resolve only against the `structure` sent in the same request.
`type`	The block’s type. See Block Types.
`parent_id`	The id of the enclosing block. Present only on nested blocks: a `table_cell` names its `table`.
`grounding`	The block’s own `{page, range, box}` object, copied unchanged from the `structure`. The `box` is in normalized page coordinates. See Working with Boxes for converting it to pixels.
`atomic_grounding`	The matching subset of the block’s own `atomic_grounding` entries. See Matches Inside a Block.

Matches Inside a Block

The grounding on a returned block covers the whole block. When the block also carries atomic_grounding, the response narrows the location to the individual entries the field’s ranges overlap, each with its own, tighter box. Each entry is an {index, page, range, box} object, and carries a confidence score as well on a parse. The index is the entry’s position in the block’s own atomic_grounding array, so you can match it back to the block’s full list. A returned block can also carry no entries at all:

Value	What it means
`[]`	The block’s range matched, but no individual entry did. Highlight the block’s own `box` instead. A `table_cell` reports this on a parse, which gives cells no finer detail than the cell itself.
No `atomic_grounding` key	The block has no `atomic_grounding` of its own. A `table` never does.

Example Response

This response grounds three fields extracted from a one-page PDF parsed with . The report_number was quoted from a text block, so the returned block carries the matching line entry. The serial_number sits in a table, so its range matches both the table and the table_cell that contains it. The report has no purchase order, so purchase_order has no source passage and its grounding is null.

{
  "grounding": {
    "report_number": [
      {
        "block_id": "text-0",
        "type": "text",
        "grounding": {
          "page": 1,
          "range": { "start": 43, "end": 143 },
          "box": { "xmin": 0.7558, "ymin": 0.06102, "xmax": 0.91343, "ymax": 0.11799 }
        },
        "atomic_grounding": [
          {
            "index": 0,
            "page": 1,
            "range": { "start": 43, "end": 67 },
            "box": { "xmin": 0.77067, "ymin": 0.06525, "xmax": 0.90643, "ymax": 0.07522 }
          }
        ]
      }
    ],
    "serial_number": [
      {
        "block_id": "table-0",
        "type": "table",
        "grounding": {
          "page": 1,
          "range": { "start": 298, "end": 719 },
          "box": { "xmin": 0.09481, "ymin": 0.23333, "xmax": 0.90513, "ymax": 0.34713 }
        }
      },
      {
        "block_id": "table_cell-7",
        "type": "table_cell",
        "parent_id": "table-0",
        "grounding": {
          "page": 1,
          "range": { "start": 482, "end": 493 },
          "box": { "xmin": 0.7532, "ymin": 0.26184, "xmax": 0.90513, "ymax": 0.29022 }
        },
        "atomic_grounding": []
      }
    ],
    "purchase_order": null
  },
  "metadata": {
    "job_id": "ground-01m1n7d2apjktw530s7bnfmnst",
    "duration_ms": 118,
    "openapi_spec": "https://api.ade.landing.ai/openapi.json",
    "billing": {
      "service_tier": "priority",
      "total_credits": 0.0
    }
  }
}

Metadata

The metadata field provides information about the request:

Field	Type	Description
`job_id`	string	The unique identifier for this request, prefixed `ground-`.
`duration_ms`	number	The end-to-end request duration in milliseconds.
`openapi_spec`	string	The URL of the OpenAPI spec that describes this API. Use it for inspection or client generation.
`billing`	object	Billing details: `service_tier` reports `priority`, and `total_credits` is always `0.0`. Grounding consumes no credits.

Limits

The Ground API is synchronous only. There is no Ground Jobs API, because the join completes quickly and the response arrives inline.
There is no model parameter. The join is a deterministic overlap computation, so there is no model version to pin.
The Ground API is not available for organizations with Zero Data Retention enabled. Requests from ZDR-enabled organizations return a 501 error. See Troubleshoot Grounding.

Get Started

Client Libraries

Parsing

Extraction

Grounding

General

Security

Administration

Pricing & Credits

Ground Extracted Fields

How Ground Works

Pair the Extraction with Its Own Parse

Call the Ground API

The Grounding Tree

Matching Blocks

Matches Inside a Block

Example Response

Metadata

Limits

​How Ground Works

​Pair the Extraction with Its Own Parse

​Call the Ground API

​The Grounding Tree

​Matching Blocks

​Matches Inside a Block

​Example Response

​Metadata

​Limits

How Ground Works

Pair the Extraction with Its Own Parse

Call the Ground API

The Grounding Tree

Matching Blocks

Matches Inside a Block

Example Response

Metadata

Limits