{
  "openapi": "3.1.0",
  "info": {
    "title": "SoilPoint API",
    "version": "1.0.0",
    "description": "USDA-NRCS SSURGO soil properties for any US latitude/longitude as JSON. Free, no key required. US coverage only; survey-scale data provided as-is, not for regulatory use. Not a USDA-endorsed product.",
    "contact": {
      "email": "admin@orbitly.tech"
    }
  },
  "externalDocs": {
    "description": "API reference (Markdown)",
    "url": "https://soilpoint.dev/docs.md"
  },
  "servers": [
    {
      "url": "https://soilpoint.dev"
    }
  ],
  "paths": {
    "/v1/soil": {
      "get": {
        "operationId": "getSoil",
        "summary": "Soil at a US coordinate",
        "description": "Dominant soil component at the point, with 0-30 cm depth-weighted properties and NCCPI.",
        "parameters": [
          {
            "name": "lat",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number",
              "minimum": -90,
              "maximum": 90
            },
            "description": "Latitude, WGS84 decimal degrees",
            "example": 37.368402
          },
          {
            "name": "lon",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number",
              "minimum": -180,
              "maximum": 180
            },
            "description": "Longitude, WGS84 decimal degrees",
            "example": -121.771
          }
        ],
        "security": [
          {},
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Soil for the point",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Soil"
                }
              }
            }
          },
          "400": {
            "description": "INVALID: missing or out-of-range lat/lon",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "INVALID_API_KEY: the x-api-key header doesn't match an active key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "NO_SOIL_DATA: ocean, outside the US, or a survey gap",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "RATE_LIMITED: 60/min and 1,000/day per IP without a key; 300/min and 20,000/day with one",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "502": {
            "description": "SDA_UPSTREAM_ERROR: USDA Soil Data Access failed or timed out and the point isn't cached; retry later",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Optional. Free key from the homepage; raises the rate limits."
      }
    },
    "schemas": {
      "Soil": {
        "type": "object",
        "required": [
          "lat",
          "lon",
          "mukey",
          "mapUnitName",
          "soilSeries",
          "componentKind",
          "componentPct",
          "texture",
          "drainageClass",
          "hydrologicGroup",
          "awc",
          "ph",
          "organicMatter",
          "nccpi",
          "nccpiClass",
          "depthWindowCm",
          "dataVintage",
          "stale",
          "cachedAt",
          "dataSource",
          "surveyDisclaimer"
        ],
        "properties": {
          "lat": {
            "type": "number",
            "description": "Latitude from the request"
          },
          "lon": {
            "type": "number",
            "description": "Longitude from the request"
          },
          "mukey": {
            "type": "string",
            "description": "SSURGO map unit key"
          },
          "mapUnitName": {
            "type": "string",
            "description": "Map unit name, e.g. \"Diablo clay, 15 to 30 percent slopes\""
          },
          "soilSeries": {
            "type": [
              "string",
              "null"
            ],
            "description": "Soil series of the dominant component"
          },
          "componentKind": {
            "type": "string",
            "description": "\"Series\" for named soils, \"Miscellaneous area\" for urban land, water and the like"
          },
          "componentPct": {
            "type": "number",
            "description": "Share of the map unit the dominant component covers (0-100)"
          },
          "texture": {
            "type": [
              "string",
              "null"
            ],
            "description": "USDA textural class of the surface horizon, e.g. \"Clay\""
          },
          "drainageClass": {
            "type": [
              "string",
              "null"
            ],
            "description": "USDA drainage class, e.g. \"Well drained\""
          },
          "hydrologicGroup": {
            "type": [
              "string",
              "null"
            ],
            "description": "NRCS hydrologic soil group: A, B, C, D or dual (e.g. \"B/D\")"
          },
          "awc": {
            "type": [
              "number",
              "null"
            ],
            "description": "Available water capacity (cm/cm), depth-weighted over 0-30 cm"
          },
          "ph": {
            "type": [
              "number",
              "null"
            ],
            "description": "pH (1:1 water), depth-weighted over 0-30 cm"
          },
          "organicMatter": {
            "type": [
              "number",
              "null"
            ],
            "description": "Organic matter (% by weight), depth-weighted over 0-30 cm"
          },
          "nccpi": {
            "type": [
              "number",
              "null"
            ],
            "description": "National Commodity Crop Productivity Index (0-1); null for non-cropland and unrated areas"
          },
          "nccpiClass": {
            "type": [
              "string",
              "null"
            ],
            "description": "NCCPI class as SSURGO rates it, e.g. \"High inherent productivity\", \"Not rated\""
          },
          "depthWindowCm": {
            "type": "array",
            "items": {
              "type": "integer"
            },
            "minItems": 2,
            "maxItems": 2,
            "description": "Depth window for the weighted values, [0, 30]"
          },
          "dataVintage": {
            "type": [
              "string",
              "null"
            ],
            "description": "SSURGO survey version date for the area",
            "format": "date"
          },
          "stale": {
            "type": "boolean",
            "description": "Reserved for answers served from cache during a USDA outage; currently always false"
          },
          "cachedAt": {
            "type": [
              "string",
              "null"
            ],
            "description": "When SoilPoint fetched this answer from USDA",
            "format": "date-time"
          },
          "dataSource": {
            "type": "string",
            "description": "\"USDA-NRCS SSURGO via Soil Data Access\""
          },
          "surveyDisclaimer": {
            "type": "string",
            "description": "As-is, US only, not for regulatory use"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}