API Design

Static Assets

From Tyler's post on the discussion

Static Asset (GCS Bucket/CDN)

• Content: A feedstock_definitions.json file keyed by residue_type.
• Goal: Provides the heavy chemical metadata (Tier 2) without bloating the tiles or hitting the database.

Suggestion instead of GCS: JSON file in repository

Pros:

• Saves on storage costs
• Less infra to create/maintain
• Auditable changes to file

Cons:

• Relies on GitHub's availability for retrieval (tradeoff between GH and a Google Cloud Storage bucket's availability)

Backend (FastAPI)

From Tyler's comment:

Backend API (FastAPI)

* Content: Tier 3 data above
* Goal: Single-record retrieval.
* Why: We need real-time data here. If `cost_per_ton` changes in Postgres, the frontend needs to reflect that immediately without waiting for a tile-gen pipeline to run.

Requirements

• Query Parameters for API calls.
• The residue_type string in the Mapbox Tiles must strictly match the keys in the static JSON lookup. If the tile says "Almond" and the JSON says "Almond Prunings", the client-side join fails. We need a shared Enum definition here.

APIs

GetUsdaCensusData

GET /api/feedstocks/usda/census?usda_crop={usda_crop}&geoid={geoid}&parameter={parameter}

Input

• usda_crop (str)
• geoid (str)
• parameter (str) -- parameter to retrieve from usda_census table

Output

• usda_crop (str) -- landIq usda_crop data
• geoid (str)
• parameter (str) -- parameter requested from usda_census table
• value (float)
• unit (str)
• dimension (str)
• dimension_value (float)
• dimension_unit (str)

Error Cases

• 4xx: CropNotFound -- when usda_crop is not found in the table
• 4xx: ParameterNotFound -- when parameter is not found for a particular usda_crop in the table

GetUsdaCensusDataByResource

GET /api/feedstocks/usda/census?resource={resource}&geoid={geoid}&parameter={parameter}

Input

• resource (str) -- landIq resource data (API will need to convert to usda_crop via main_crop)
• geoid (str)
• parameter (str) -- parameter to retrieve from usda_census table

Output

• resource (str) -- landIq resource data
• geoid (str)
• parameter (str) -- parameter requested from usda_census table
• value (float)
• unit (str)
• dimension (str)
• dimension_value (float)
• dimension_unit (str)

Error Cases

• 4xx: ResourceNotFound -- when resource is not found in the table
• 4xx: ParameterNotFound -- when parameter is not found for a particular resource in the table

ListUsdaCensusData

GET /api/feedstocks/usda/census?usda_crop={usda_crop}&geoid={geoid}

Input

• usda_crop (str)
• geoid (str)

Output

• usda_crop (str) -- landIq usda_crop data
• geoid (str)
• data (list) -- list of parameters, values, and related data
  • parameter (str) -- parameter requested from usda_census table
  • value (float)
  • unit (str)
  • dimension (str)
  • dimension_value (float)
  • dimension_unit (str)

Error Cases

• 4xx: CropNotFound -- when usda_crop is not found in the table

ListUsdaCensusDataByResource

GET /api/feedstocks/usda/census?resource={resource}&geoid={geoid}

Input

• resource (str) -- landIq resource data (API will need to convert to usda_crop via main_crop)
• geoid (str)

Output

• resource (str) -- landIq resource data
• geoid (str)
• data (list) -- list of parameters, values, and related data
  • parameter (str) -- parameter requested from usda_census table
  • value (float)
  • unit (str)
  • dimension (str)
  • dimension_value (float)
  • dimension_unit (str)

Error Cases

• 4xx: ResourceNotFound -- when resource is not found in the table

GetUsdaSurveyData

GET /api/feedstocks/usda/survey?usda_crop={usda_crop}&geoid={geoid}&parameter={parameter}

Input

• usda_crop (str)
• geoid (str)
• parameter (str) -- parameter to retrieve from usda_census table

Output

• usda_crop (str) -- landIq usda_crop data
• geoid (str)
• parameter (str) -- parameter requested from usda_census table
• value (float)
• unit (str)
• dimension (str)
• dimension_value (float)
• dimension_unit (str)

Error Cases

• 4xx: CropNotFound -- when usda_crop is not found in the table
• 4xx: ParameterNotFound -- when parameter is not found for a particular usda_crop in the table

GetUsdaSurveyDataByResource

GET /api/feedstocks/usda/survey?resource={resource}&geoid={geoid}&parameter={parameter}

Input

• resource (str) -- landIq resource data (API will need to convert to usda_crop via main_crop)
• geoid (str)
• parameter (str) -- parameter to retrieve from usda_census table

Output

• resource (str) -- landIq resource data
• geoid (str)
• parameter (str) -- parameter requested from usda_census table
• value (float)
• unit (str)
• dimension (str)
• dimension_value (float)
• dimension_unit (str)

Error Cases

• 4xx: ResourceNotFound -- when resource is not found in the table
• 4xx: ParameterNotFound -- when parameter is not found for a particular resource in the table

ListUsdaSurveyData

GET /api/feedstocks/usda/survey?usda_crop={usda_crop}&geoid={geoid}

Input

• usda_crop (str?)
• geoid (str)

Output

• usda_crop (str) -- landIq usda_crop data
• geoid (str)
• data (list) -- list of parameters, values, and related data
  • parameter (str) -- parameter requested from usda_census table
  • value (float)
  • unit (str)
  • dimension (str)
  • dimension_value (float)
  • dimension_unit (str)

Error Cases

• 4xx: CropNotFound -- when usda_crop is not found in the table

ListUsdaSurveyDataByResource

GET /api/feedstocks/usda/survey?resource={resource}&geoid={geoid}

Input

• resource (str?) -- landIq resource data (API will need to convert to usda_crop via main_crop)
• geoid (str)

Output

• resource (str) -- landIq resource data
• geoid (str)
• data (list) -- list of parameters, values, and related data
  • parameter (str) -- parameter requested from usda_census table
  • value (float)
  • unit (str)
  • dimension (str)
  • dimension_value (float)
  • dimension_unit (str)

Error Cases

• 4xx: ResourceNotFound -- when resource is not found in the table

GetResourceAvailability

GET /api/feedstocks/availability?resource={resource}&geoid={geoid}

Input

• resource (str) -- landIq resource data
• geoid (str)

Output

• resource (str) -- landIq resource data
• geoid (str)
• from_month (int)
• to_month (int)

Error Cases

• 4xx: ResourceNotFound -- when resource is not found in the table

GetAnalysisData

GET /api/feedstocks/analysis?resource={resource}&geoid={geoid}&parameter={parameter}

Input

• resource (str) -- landIq resource data
• geoid (str)
• parameter (str) -- parameter to retrieve from usda_census table

Output

• resource (str) -- landIq resource data
• geoid (str)
• parameter (str) -- parameter requested from usda_census table
• value (float)
• unit (str)

Error Cases

• 4xx: ResourceNotFound -- when resource is not found in the table
• 4xx: ParameterNotFound -- when parameter is not found for a particular resource in the table

ListAnalysisData

GET /api/feedstocks/analysis?resource={resource}&geoid={geoid}

Input

• resource (str) -- landIq resource data
• geoid (str)

Output

• resource (str) -- landIq resource data
• geoid (str)
• data (list) -- list of parameters, values, and related data
  • parameter (str) -- parameter requested from usda_census table
  • value (float)
  • unit (str)

Error Cases

• 4xx: ResourceNotFound -- when resource is not found in the table