rootfast

§API · v1

The Rootfast API

A small, JSON-only HTTP API over USDA PLANTS data. No keys, no rate limits in v1, no terms beyond attribution. Try every example below — it hits the live service.

Base URL · https://api.rootfast.org

§1Service health & version

GET

/healthz

Returns dataset version and applied schema migration. Useful as a liveness check.

Request

curl 'https://api.rootfast.org/healthz'

Response · 200

{
  "ok": true,
  "dataset_version": "0.0.1",
  "schema_version": "001"
}

Try it → https://api.rootfast.org/healthz

§2One plant, in full

GET

/v1/plants/{usda_symbol}

Returns a plant record with growth habit, duration, native status by region, every USDA characteristic, and all Montana counties where the taxon is recorded. Resolves synonyms transparently.

Request

curl 'https://api.rootfast.org/v1/plants/PIPO'

Response · 200

{
  "plant": {
    "usda_symbol": "PIPO",
    "scientific_name": "Pinus ponderosa Lawson & C. Lawson",
    "scientific_name_canonical": "Pinus ponderosa",
    "common_name": "ponderosa pine",
    "family": "Pinaceae Spreng. ex Rudolphi",
    "gbif_taxon_key": 5285053,
    "gbif_match_type": "EXACT",
    "rank": "Species",
    "...": "..."
  },
  "growth_habits": ["Tree"],
  "durations": ["Perennial"],
  "native_status": [
    { "region_code": "L48", "status": "Native" },
    { "region_code": "CAN", "status": "Native" }
  ],
  "characteristics": { "drought_tolerance": "High", "...": "..." },
  "counties": [
    { "county_fips": "30031", "county_name": "Gallatin", "state_code": "MT", "nativity": "Native" }
  ]
}

Try it → https://api.rootfast.org/v1/plants/PIPO

§3Plants in a county

GET

/v1/counties/{county_fips}/plants

All taxa recorded in the given county, with nativity. FIPS is the 5-digit Census code (Gallatin County, MT is 30031).

Request

curl 'https://api.rootfast.org/v1/counties/30031/plants'

Response · 200

{
  "county": {
    "county_fips": "30031",
    "county_name": "Gallatin",
    "state_code": "MT"
  },
  "count": 1362,
  "plants": [
    {
      "usda_symbol": "ABLA",
      "scientific_name": "Abies lasiocarpa (Hook.) Nutt.",
      "common_name": "subalpine fir",
      "family": "Pinaceae Spreng. ex Rudolphi",
      "nativity": "Native"
    }
  ]
}

Try it → https://api.rootfast.org/v1/counties/30031/plants

§4List of states

GET

/v1/states

Every state with ingested data, plus county and taxon counts. Today this returns Montana only — nationwide ingest is on the roadmap (see /about).

Request

curl 'https://api.rootfast.org/v1/states'

Response · 200

{
  "count": 1,
  "states": [
    {
      "state_code": "MT",
      "state_name": "Montana",
      "state_fips": "30",
      "country": "US",
      "county_count": 56,
      "taxa_count": 3215
    }
  ]
}

Try it → https://api.rootfast.org/v1/states

§5State header

GET

/v1/states/{state_code}

Single-state header with county and taxon counts. State code is the two-letter postal abbreviation (case-insensitive).

Request

curl 'https://api.rootfast.org/v1/states/MT'

Response · 200

{
  "state": {
    "state_code": "MT",
    "state_name": "Montana",
    "state_fips": "30",
    "country": "US",
    "county_count": 56,
    "taxa_count": 3215
  }
}

Try it → https://api.rootfast.org/v1/states/MT

§6Plants in a state

GET

/v1/states/{state_code}/plants

Every taxon in the state, aggregated across counties. county_count is how many counties the taxon appears in; native_counties / introduced_counties / both_counties give the breakdown. nativity is the state-level rollup: "Native" if no introduced records, "Introduced" if no native records, "Both" if mixed or any county records "Both".

Request

curl 'https://api.rootfast.org/v1/states/MT/plants'

Response · 200

{
  "state": {
    "state_code": "MT",
    "state_name": "Montana",
    "state_fips": "30",
    "country": "US"
  },
  "counts": { "taxa": 3215, "counties": 56 },
  "plants": [
    {
      "usda_symbol": "PIPO",
      "scientific_name": "Pinus ponderosa Lawson & C. Lawson",
      "common_name": "ponderosa pine",
      "family": "Pinaceae Spreng. ex Rudolphi",
      "photo_thumb_url": null,
      "county_count": 22,
      "native_counties": 22,
      "introduced_counties": 0,
      "both_counties": 0,
      "nativity": "Native"
    }
  ]
}

Try it → https://api.rootfast.org/v1/states/MT/plants

§7Counties in a state

GET

/v1/states/{state_code}/counties

Lightweight listing of every county in the state with its taxa count. Useful for state-overview pages and county pickers.

Request

curl 'https://api.rootfast.org/v1/states/MT/counties'

Response · 200

{
  "state": { "state_code": "MT", "state_name": "Montana", "state_fips": "30", "country": "US" },
  "count": 56,
  "counties": [
    {
      "county_fips": "30001",
      "county_name": "Beaverhead",
      "state_code": "MT",
      "centroid_lat": 45.07,
      "centroid_lon": -112.86,
      "taxa_count": 755
    }
  ]
}

Try it → https://api.rootfast.org/v1/states/MT/counties

§EErrors

Errors are plain.

Every error returns a JSON body of { "error": "<message>" }. The HTTP status carries the meaning.

400
Malformed request (e.g. missing lat/lng).
404
Unknown plant symbol, county FIPS, or route.
500
Database or upstream error — should be rare. Include the request URL when reporting.

§LLicense & attribution

Use it freely. Cite the sources.

The Rootfast dataset is derived from public-domain federal data. The original source records are in the public domain. The merged dataset and this API are published as a public good. No API key is required and there is no commercial gating planned.

  • · USDA PLANTS — public domain
  • · GBIF Backbone Taxonomy — CC0
  • · Rootfast code — MIT
  • · Rootfast data — CC0

If you build something with this — a tool, a garden plan, a research paper — we would love to hear about it.