Fetch and stream inventory data

You are viewing in-progress documentation for v2 (Beta). Switch to the stable version for the current production release.

A tree inventory can hold tens of thousands of stems, so its rows are served in partitions — fetch each partition and stack them into one table. This guide walks that loop.

Prerequisites

An API key: my-api-key.
A domain and a completed inventory: your-domain-id and your-inventory-id — e.g. the inventory from Generate a tree inventory from TreeMap.

curl -X 'GET' \
  'https://api-v2-prod-nyvjyh5ywa-uw.a.run.app/domains/your-domain-id/inventories/your-inventory-id/data/metadata' \
  -H 'accept: application/json' \
  -H 'api-key: my-api-key'

{
  "inventory_id": "your-inventory-id",
  "num_partitions": 2,
  "total_rows": 42063,
  "columns": [
    "x",
    "y",
    "fia_species_code",
    "fia_status_code",
    "dbh",
    "height",
    "crown_ratio"
  ],
  "partitions": [
    {
      "index": 0,
      "num_rows": 33415
    },
    {
      "index": 1,
      "num_rows": 8648
    }
  ]
}

num_partitions tells you how many data/{partition_index} calls to make; total_rows is the tree count across all of them; and columns lists the tree attributes each row carries — the same set the partition responses return.

Step 2 — Fetch a partition

GET /inventories/{{INVENTORY_ID}}/data/{partition_index}. Each partition is row-oriented: a columns list and a data array of rows, where each row’s values line up with columns.

curl
Response (abridged)

curl -X 'GET' \
  'https://api-v2-prod-nyvjyh5ywa-uw.a.run.app/domains/your-domain-id/inventories/your-inventory-id/data/0' \
  -H 'accept: application/json' \
  -H 'api-key: my-api-key'

{
  "partition": 0,
  "num_rows": 33415,
  "columns": [
    "x",
    "y",
    "fia_species_code",
    "fia_status_code",
    "dbh",
    "height",
    "crown_ratio"
  ],
  "data": [
    [
      721198.9783081036, 5190613.552297756, 122, 1, 8.128, 4.571999999999999,
      0.08
    ],
    [
      721194.5877259874, 5190600.826157865, 122, 1, 20.573999999999998, 10.9728,
      0.6
    ],
    [
      721176.5454370301, 5190610.849438333, 122, 1, 36.068, 9.753599999999999,
      0.7
    ]
  ]
}

data is shown with three rows above; the real partition holds num_rows (33,415) of them. Each row is [x, y, fia_species_code, fia_status_code, dbh, height, crown_ratio] — coordinates in the domain CRS (meters), dbh in cm, height in m, crown_ratio a 0–1 fraction.

Step 3 — Stream all partitions into a table

The SDK does the partition loop for you: inventory.to_dataframe() fetches every partition and concatenates them into one DataFrame. Over raw HTTP, loop partition_index from 0 to num_partitions and concatenate yourself:

curl
Python SDK

# Discover the partition count, then fetch every partition and stream its rows.
BASE='https://api-v2-prod-nyvjyh5ywa-uw.a.run.app/domains/your-domain-id/inventories/your-inventory-id'

num_partitions=$(curl -s "$BASE/data/metadata" -H 'api-key: my-api-key' | jq '.num_partitions')

for i in $(seq 0 $((num_partitions - 1))); do
  curl -s "$BASE/data/$i" -H 'api-key: my-api-key' | jq -c '.data[]'
done

import fastfuels_sdk.v2 as ff

ff.set_api_key("my-api-key")

inventory = ff.get_inventory("your-domain-id", "your-inventory-id")

# The SDK does the per-partition loop for you: to_dataframe() fetches every
# partition and concatenates them into a single DataFrame — one row per tree,
# columns matching the inventory (x, y, dbh, height, crown_ratio, ...).
trees = inventory.to_dataframe()  # -> DataFrame, shape (total_rows, n_columns)

Common pitfalls

Reading only partition 0. A large inventory spans several partitions; data/0 is just the first slice. Iterate to num_partitions or you’ll silently drop trees.
Hard-coding column order. Build rows against the columns list in the response rather than assuming a fixed order — it’s there so you don’t have to guess.
Inventory not completed. Rows are only available once processing finishes; poll the inventory to completed first.