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",
    "__null_dask_index__"
  ],
  "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; columns lists every field each tree row carries.

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

Loop partition_index from 0 to num_partitions and concatenate:

import pandas as pd
import requests

API_KEY = "my-api-key"
DOMAIN_ID = "your-domain-id"
INVENTORY_ID = "your-inventory-id"
BASE = "https://api-v2-prod-nyvjyh5ywa-uw.a.run.app"
HEADERS = {"api-key": API_KEY}

# 1. How many partitions? (Each partition is a chunk of rows.)
meta = requests.get(
    f"{BASE}/domains/{DOMAIN_ID}/inventories/{INVENTORY_ID}/data/metadata",
    headers=HEADERS,
).json()

# 2. Fetch each partition and stack into one DataFrame.
frames = []
for i in range(meta["num_partitions"]):
    part = requests.get(
        f"{BASE}/domains/{DOMAIN_ID}/inventories/{INVENTORY_ID}/data/{i}",
        headers=HEADERS,
    ).json()
    frames.append(pd.DataFrame(part["data"], columns=part["columns"]))

trees = pd.concat(frames, ignore_index=True)
print(len(trees), "trees")          # -> 42063 trees
print(trees["dbh"].describe())      # cm; height in m, crown_ratio 0–1

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.