Fetch and stream inventory data
You are viewing in-progress documentation for v2. 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.
Prerequisites
Section titled “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.
Step 1 — Discover the partitions
Section titled “Step 1 — Discover the partitions”curl -X 'GET' \ 'https://api.fastfuels.silvxlabs.com/v2/domains/your-domain-id/inventories/your-inventory-id/data/metadata' \ -H 'accept: application/json' \ -H 'api-key: my-api-key'import fastfuels_sdk.v2 as ff
ff.set_api_key("my-api-key")
inventory = ff.get_inventory("your-domain-id", "your-inventory-id")
metadata = inventory.get_data_metadata()print(metadata.num_partitions, metadata.total_rows){ "inventory_id": "your-inventory-id", "num_partitions": 2, "total_rows": 44099, "columns": [ "tree_id", "x", "y", "fia_species_code", "fia_status_code", "dbh", "height", "crown_ratio", "crown_base_height" ], "partitions": [ { "index": 0, "num_rows": 35186 }, { "index": 1, "num_rows": 8913 } ]}num_partitions is the number of data/{partition_index} calls to make.
total_rows is the tree count across all of them. columns lists the tree
attributes each row carries — the same set the partition responses return.
Step 2 — Fetch a partition
Section titled “Step 2 — Fetch a partition”GET /domains/{domain_id}/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 -X 'GET' \ 'https://api.fastfuels.silvxlabs.com/v2/domains/your-domain-id/inventories/your-inventory-id/data/0' \ -H 'accept: application/json' \ -H 'api-key: my-api-key'partition = inventory.get_data_partition(0)print(partition.columns, partition.num_rows){ "partition": 0, "num_rows": 35186, "columns": [ "tree_id", "x", "y", "fia_species_code", "fia_status_code", "dbh", "height", "crown_ratio", "crown_base_height" ], "data": [ [ 1, 721162.5666811031, 5190632.831300038, 122, 1, 10.16, 6.705599999999999, 0.1, 4.964729905932686 ], [ 2, 721158.5199696932, 5190631.885708452, 122, 1, 8.128, 4.571999999999999, 0.08, 3.3713714507465364 ], [ 3, 721167.5709544135, 5190640.285039947, 122, 1, 10.16, 6.705599999999999, 0.1, 4.964729905932686 ] ]}data is shown with three rows above. The real partition holds num_rows
(≈35,200) of them. In this TreeMap inventory, each row is [tree_id, x, y, fia_species_code, fia_status_code, dbh, height, crown_ratio, crown_base_height]. The columns depend on the inventory’s source. For their
units, see the column table.
Step 3 — Stream all partitions into a table
Section titled “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 − 1 and concatenate yourself:
# Discover the partition count, then fetch every partition and stream its rows.BASE='https://api.fastfuels.silvxlabs.com/v2/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[]'doneimport 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 (tree_id, x, y, dbh, height, ...).trees = inventory.to_dataframe() # -> DataFrame, shape (total_rows, n_columns)Common pitfalls
Section titled “Common pitfalls”- Reading only partition 0. A large inventory spans several partitions.
data/0is only the first slice. Read every partition listed inpartitionsor you’ll silently drop trees. - Hard-coding column order. Build rows against the
columnslist in the response. - Inventory not
completed. Rows are only available once processing finishes. Poll the inventory tocompletedfirst.