openapi: 3.1.0
info:
  title: Soil Data API (Loam)
  version: "1.0"
  description: >
    Soil data by latitude/longitude. Returns the USDA SSURGO soil map unit at a
    point — components, depth-resolved horizon properties (texture, pH, organic
    matter, available water capacity, saturated hydraulic conductivity),
    drainage class, hydrologic group, and farmland class — as one clean,
    aggregated JSON object. Data is from USDA-NRCS SSURGO via Soil Data Access
    (public domain). Coverage: United States and territories. Informational
    only; describes a map unit (area), not a point measurement.
  license:
    name: MIT
servers:
  - url: https://loam.rgtz.dev
    description: Production (custom domain)
paths:
  /v1/soil:
    get:
      operationId: getSoil
      summary: Soil profile at a coordinate.
      description: >
        Returns the SSURGO soil map unit covering the given point, with its
        components and depth-resolved horizons, plus depth-weighted 0–30 cm
        roll-ups. Sold via RapidAPI.
      parameters:
        - name: lat
          in: query
          required: true
          description: Latitude in decimal degrees (WGS84).
          schema: { type: number, minimum: -90, maximum: 90, example: 42.03 }
        - name: lon
          in: query
          required: true
          description: Longitude in decimal degrees (WGS84).
          schema: { type: number, minimum: -180, maximum: 180, example: -93.65 }
      responses:
        "200":
          description: Soil profile for the map unit at the point.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/SoilProfile" }
        "400":
          description: Missing or invalid coordinates.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "403":
          description: Request did not come through the RapidAPI gateway.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "404":
          description: No SSURGO coverage at this location.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "502":
          description: Upstream Soil Data Access query failed.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
  /health:
    get:
      operationId: getHealth
      summary: Liveness check (no auth).
      responses:
        "200":
          description: Service is up.
  /v1/manifest:
    get:
      operationId: getManifest
      summary: Machine-readable capability manifest (no auth).
      responses:
        "200":
          description: Capability manifest.
components:
  securitySchemes:
    RapidAPIKey:
      type: apiKey
      in: header
      name: X-RapidAPI-Key
  schemas:
    Horizon:
      type: object
      properties:
        name: { type: [string, "null"], example: "Ap" }
        top_cm: { type: [number, "null"], example: 0 }
        bot_cm: { type: [number, "null"], example: 20 }
        texture: { type: [string, "null"], example: "loam" }
        sand_pct: { type: [number, "null"], example: 31 }
        silt_pct: { type: [number, "null"], example: 43 }
        clay_pct: { type: [number, "null"], example: 26 }
        organic_matter_pct: { type: [number, "null"], example: 6 }
        ph: { type: [number, "null"], example: 6.2 }
        available_water_capacity: { type: [number, "null"], example: 0.21 }
        ksat_um_s: { type: [number, "null"], example: 9.17 }
        cec_meq_100g: { type: [number, "null"] }
        bulk_density_g_cm3: { type: [number, "null"] }
    Component:
      type: object
      properties:
        name: { type: [string, "null"], example: "Nicollet" }
        percent: { type: [number, "null"], example: 85 }
        major: { type: boolean }
        kind: { type: [string, "null"], example: "Series" }
        drainage_class: { type: [string, "null"], example: "Somewhat poorly drained" }
        hydrologic_group: { type: [string, "null"], example: "B/D" }
        taxonomic_order: { type: [string, "null"], example: "Mollisols" }
        taxonomic_class: { type: [string, "null"] }
        slope_pct: { type: [number, "null"], example: 2 }
        runoff_class: { type: [string, "null"] }
        nonirrigated_capability_class: { type: [string, "null"] }
        irrigated_capability_class: { type: [string, "null"] }
        horizons:
          type: array
          items: { $ref: "#/components/schemas/Horizon" }
    SoilProfile:
      type: object
      properties:
        disclaimer: { type: string }
        source:
          type: object
          properties:
            name: { type: string }
            url: { type: string }
            license: { type: string }
            citation: { type: string }
        location:
          type: object
          properties:
            lat: { type: [number, "null"] }
            lon: { type: [number, "null"] }
        mapunit:
          type: object
          properties:
            mukey: { type: [string, "null"], example: "2800480" }
            name: { type: [string, "null"], example: "Nicollet loam, 1 to 3 percent slopes" }
            symbol: { type: [string, "null"] }
            farmland_class: { type: [string, "null"], example: "All areas are prime farmland" }
        dominant_component: { $ref: "#/components/schemas/Component" }
        components:
          type: array
          items: { $ref: "#/components/schemas/Component" }
        summary:
          type: object
          properties:
            dominant_component: { type: [string, "null"] }
            surface_texture: { type: [string, "null"] }
            drainage_class: { type: [string, "null"] }
            hydrologic_group: { type: [string, "null"] }
            depth_window_cm:
              type: array
              items: { type: number }
              example: [0, 30]
            avg_texture: { type: [string, "null"] }
            avg_sand_pct: { type: [number, "null"] }
            avg_silt_pct: { type: [number, "null"] }
            avg_clay_pct: { type: [number, "null"] }
            avg_organic_matter_pct: { type: [number, "null"] }
            avg_ph: { type: [number, "null"] }
            avg_available_water_capacity: { type: [number, "null"] }
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code: { type: string }
            message: { type: string }
            hint: { type: [string, "null"] }
            request_id: { type: string }
        request_id: { type: string }
security:
  - RapidAPIKey: []
