{"openapi":"3.1.0","info":{"title":"OpenSoil API","summary":"A provenance-first interface to public soil data.","description":"Experimental read-only API. Normalized records retain provider fields, depth, methods, retrieval time, data kind, transformations, and scientific warnings.","contact":{"name":"OpenSoil","url":"https://docs.opensoil.net/"},"license":{"name":"API code: repository license; source data retains provider terms"},"version":"0.1.0"},"paths":{"/health":{"get":{"tags":["Service"],"summary":"Health","description":"Report application health without calling an upstream provider.","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/v1":{"get":{"tags":["Metadata"],"summary":"Api Metadata","description":"Describe this API version and its current maturity.","operationId":"api_metadata_v1_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiMetadata"}}}}}}},"/v1/providers":{"get":{"tags":["Catalog"],"summary":"Providers","description":"List supported, planned, and researched source systems without overstating support.","operationId":"providers_v1_providers_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProvidersResponse"}}}}}}},"/v1/properties":{"get":{"tags":["Catalog"],"summary":"Properties","description":"List OpenSoil's developing canonical soil-property vocabulary.","operationId":"properties_v1_properties_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PropertiesResponse"}}}}}}},"/v1/soil/location":{"get":{"tags":["Soil"],"summary":"Soil At Location","description":"Return normalized mapped-survey observations for one WGS84 point.","operationId":"soil_at_location_v1_soil_location_get","parameters":[{"name":"latitude","in":"query","required":true,"schema":{"type":"number","maximum":90,"minimum":-90,"description":"WGS84 latitude","title":"Latitude"},"description":"WGS84 latitude"},{"name":"longitude","in":"query","required":true,"schema":{"type":"number","maximum":180,"minimum":-180,"description":"WGS84 longitude","title":"Longitude"},"description":"WGS84 longitude"},{"name":"providers","in":"query","required":false,"schema":{"type":"string","maxLength":40,"default":"usda_sda","title":"Providers"}},{"name":"properties","in":"query","required":false,"schema":{"type":"string","maxLength":200,"default":"ph,organic_matter,sand,silt,clay","title":"Properties"}},{"name":"depth_top_cm","in":"query","required":false,"schema":{"type":"number","maximum":199,"minimum":0,"description":"Top of depth interval in cm","default":0,"title":"Depth Top Cm"},"description":"Top of depth interval in cm"},{"name":"depth_bottom_cm","in":"query","required":false,"schema":{"type":"number","maximum":200,"exclusiveMinimum":0,"description":"Bottom of depth interval in cm","default":200,"title":"Depth Bottom Cm"},"description":"Bottom of depth interval in cm"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationResponse"}}}},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unprocessable Content"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad Gateway"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Gateway Timeout"}}}},"/v1/providers/{provider_id}/raw/location":{"get":{"tags":["Raw provider data"],"summary":"Raw Soil At Location","description":"Return the untouched upstream payload under a clearly labeled wrapper.","operationId":"raw_soil_at_location_v1_providers__provider_id__raw_location_get","parameters":[{"name":"provider_id","in":"path","required":true,"schema":{"type":"string","title":"Provider Id"}},{"name":"latitude","in":"query","required":true,"schema":{"type":"number","maximum":90,"minimum":-90,"description":"WGS84 latitude","title":"Latitude"},"description":"WGS84 latitude"},{"name":"longitude","in":"query","required":true,"schema":{"type":"number","maximum":180,"minimum":-180,"description":"WGS84 longitude","title":"Longitude"},"description":"WGS84 longitude"},{"name":"properties","in":"query","required":false,"schema":{"type":"string","maxLength":200,"default":"ph,organic_matter,sand,silt,clay","title":"Properties"}},{"name":"depth_top_cm","in":"query","required":false,"schema":{"type":"number","maximum":199,"minimum":0,"description":"Top of depth interval in cm","default":0,"title":"Depth Top Cm"},"description":"Top of depth interval in cm"},{"name":"depth_bottom_cm","in":"query","required":false,"schema":{"type":"number","maximum":200,"exclusiveMinimum":0,"description":"Bottom of depth interval in cm","default":200,"title":"Depth Bottom Cm"},"description":"Bottom of depth interval in cm"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RawProviderResponse"}}}},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unprocessable Content"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad Gateway"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Gateway Timeout"}}}}},"components":{"schemas":{"ApiMetadata":{"properties":{"name":{"type":"string","title":"Name"},"version":{"type":"string","title":"Version"},"project_status":{"type":"string","const":"experimental","title":"Project Status"},"documentation_url":{"type":"string","title":"Documentation Url"},"openapi_url":{"type":"string","title":"Openapi Url"},"supported_providers":{"items":{"type":"string"},"type":"array","title":"Supported Providers"},"warning":{"type":"string","title":"Warning"}},"additionalProperties":false,"type":"object","required":["name","version","project_status","documentation_url","openapi_url","supported_providers","warning"],"title":"ApiMetadata"},"CacheMetadata":{"properties":{"hit":{"type":"boolean","title":"Hit"},"stored_at":{"type":"string","format":"date-time","title":"Stored At"},"age_seconds":{"type":"integer","title":"Age Seconds"}},"additionalProperties":false,"type":"object","required":["hit","stored_at","age_seconds"],"title":"CacheMetadata"},"DepthInterval":{"properties":{"top_cm":{"type":"number","title":"Top Cm"},"bottom_cm":{"type":"number","title":"Bottom Cm"}},"additionalProperties":false,"type":"object","required":["top_cm","bottom_cm"],"title":"DepthInterval"},"ErrorBody":{"properties":{"code":{"type":"string","title":"Code"},"message":{"type":"string","title":"Message"},"request_id":{"type":"string","title":"Request Id"},"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider"},"retryable":{"type":"boolean","title":"Retryable","default":false}},"additionalProperties":false,"type":"object","required":["code","message","request_id"],"title":"ErrorBody"},"ErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/ErrorBody"}},"additionalProperties":false,"type":"object","required":["error"],"title":"ErrorResponse"},"HealthResponse":{"properties":{"status":{"type":"string","const":"healthy","title":"Status"},"service":{"type":"string","title":"Service"},"version":{"type":"string","title":"Version"}},"additionalProperties":false,"type":"object","required":["status","service","version"],"title":"HealthResponse"},"LicenseRecord":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"}},"additionalProperties":false,"type":"object","title":"LicenseRecord"},"LocationQuery":{"properties":{"latitude":{"type":"number","title":"Latitude"},"longitude":{"type":"number","title":"Longitude"},"providers":{"items":{"type":"string"},"type":"array","title":"Providers"},"properties":{"items":{"type":"string"},"type":"array","title":"Properties"},"depth_top_cm":{"type":"number","title":"Depth Top Cm"},"depth_bottom_cm":{"type":"number","title":"Depth Bottom Cm"}},"additionalProperties":false,"type":"object","required":["latitude","longitude","providers","properties","depth_top_cm","depth_bottom_cm"],"title":"LocationQuery"},"LocationResponse":{"properties":{"api_version":{"type":"string","title":"Api Version"},"status":{"type":"string","const":"experimental","title":"Status"},"query":{"$ref":"#/components/schemas/LocationQuery"},"data_kind":{"type":"string","const":"mapped_survey","title":"Data Kind"},"observations":{"items":{"$ref":"#/components/schemas/SoilObservation"},"type":"array","title":"Observations"},"map_units":{"items":{"$ref":"#/components/schemas/MapUnitSummary"},"type":"array","title":"Map Units"},"cache":{"$ref":"#/components/schemas/CacheMetadata"},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings"}},"additionalProperties":false,"type":"object","required":["api_version","status","query","data_kind","observations","map_units","cache","warnings"],"title":"LocationResponse"},"MapUnitSummary":{"properties":{"area_symbol":{"type":"string","title":"Area Symbol"},"map_unit_key":{"type":"string","title":"Map Unit Key"},"map_unit_symbol":{"type":"string","title":"Map Unit Symbol"},"map_unit_name":{"type":"string","title":"Map Unit Name"}},"additionalProperties":false,"type":"object","required":["area_symbol","map_unit_key","map_unit_symbol","map_unit_name"],"title":"MapUnitSummary"},"ObservationLocation":{"properties":{"latitude":{"type":"number","title":"Latitude"},"longitude":{"type":"number","title":"Longitude"},"horizontal_accuracy_m":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Horizontal Accuracy M"}},"additionalProperties":false,"type":"object","required":["latitude","longitude"],"title":"ObservationLocation"},"PropertiesResponse":{"properties":{"properties":{"items":{"$ref":"#/components/schemas/PropertyRecord"},"type":"array","title":"Properties"},"warning":{"type":"string","title":"Warning"}},"additionalProperties":false,"type":"object","required":["properties","warning"],"title":"PropertiesResponse"},"PropertyRecord":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"standard_unit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Standard Unit"},"accepted_aliases":{"items":{"type":"string"},"type":"array","title":"Accepted Aliases"},"conversion_notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Conversion Notes"},"method_dependency_warning":{"type":"string","title":"Method Dependency Warning"},"status":{"type":"string","enum":["researching","planned","experimental","supported","temporarily_unavailable","deprecated"],"title":"Status"}},"additionalProperties":false,"type":"object","required":["id","name","description","standard_unit","accepted_aliases","conversion_notes","method_dependency_warning","status"],"title":"PropertyRecord"},"PropertyReference":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"}},"additionalProperties":false,"type":"object","required":["id","name"],"title":"PropertyReference"},"ProviderRecord":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"organization":{"type":"string","title":"Organization"},"coverage":{"type":"string","title":"Coverage"},"data_kind":{"type":"string","title":"Data Kind"},"status":{"type":"string","enum":["researching","planned","experimental","supported","temporarily_unavailable","deprecated"],"title":"Status"},"access_method":{"type":"string","title":"Access Method"},"documentation_url":{"type":"string","title":"Documentation Url"},"source_url":{"type":"string","title":"Source Url"},"license":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"License"},"authentication":{"type":"string","title":"Authentication"},"operational":{"type":"boolean","title":"Operational"},"supported_properties":{"items":{"type":"string"},"type":"array","title":"Supported Properties"},"limitations":{"items":{"type":"string"},"type":"array","title":"Limitations"}},"additionalProperties":false,"type":"object","required":["id","name","organization","coverage","data_kind","status","access_method","documentation_url","source_url","authentication","operational"],"title":"ProviderRecord"},"ProvidersResponse":{"properties":{"providers":{"items":{"$ref":"#/components/schemas/ProviderRecord"},"type":"array","title":"Providers"}},"additionalProperties":false,"type":"object","required":["providers"],"title":"ProvidersResponse"},"RawProviderResponse":{"properties":{"provider":{"type":"string","title":"Provider"},"status":{"type":"string","const":"experimental","title":"Status"},"query":{"$ref":"#/components/schemas/LocationQuery"},"retrieved_at":{"type":"string","format":"date-time","title":"Retrieved At"},"cache":{"$ref":"#/components/schemas/CacheMetadata"},"upstream_response":{"additionalProperties":true,"type":"object","title":"Upstream Response"},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings"}},"additionalProperties":false,"type":"object","required":["provider","status","query","retrieved_at","cache","upstream_response","warnings"],"title":"RawProviderResponse"},"SoilObservation":{"properties":{"property":{"$ref":"#/components/schemas/PropertyReference"},"value":{"type":"number","title":"Value"},"unit":{"type":"string","title":"Unit"},"depth":{"$ref":"#/components/schemas/DepthInterval"},"data_kind":{"type":"string","enum":["observed","modeled","mapped_survey","derived","user_supplied"],"title":"Data Kind"},"measurement_method":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Measurement Method"},"source":{"$ref":"#/components/schemas/SourceProvenance"},"location":{"$ref":"#/components/schemas/ObservationLocation"},"uncertainty":{"$ref":"#/components/schemas/Uncertainty"},"license":{"$ref":"#/components/schemas/LicenseRecord"},"transformations":{"items":{"$ref":"#/components/schemas/Transformation"},"type":"array","title":"Transformations"},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings"},"survey_context":{"$ref":"#/components/schemas/SurveyContext"}},"additionalProperties":false,"type":"object","required":["property","value","unit","depth","data_kind","measurement_method","source","location","uncertainty","license","transformations","warnings","survey_context"],"title":"SoilObservation"},"SourceProvenance":{"properties":{"provider":{"type":"string","title":"Provider"},"organization":{"type":"string","title":"Organization"},"record_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Record Id"},"retrieved_at":{"type":"string","format":"date-time","title":"Retrieved At"},"original_property_name":{"type":"string","title":"Original Property Name"},"original_value":{"type":"number","title":"Original Value"},"original_unit":{"type":"string","title":"Original Unit"},"original_depth":{"$ref":"#/components/schemas/DepthInterval"},"original_measurement_method":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Original Measurement Method"},"citation":{"type":"string","title":"Citation"},"source_url":{"type":"string","title":"Source Url"},"spatial_resolution":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Spatial Resolution"}},"additionalProperties":false,"type":"object","required":["provider","organization","record_id","retrieved_at","original_property_name","original_value","original_unit","original_depth","original_measurement_method","citation","source_url"],"title":"SourceProvenance"},"SurveyContext":{"properties":{"area_symbol":{"type":"string","title":"Area Symbol"},"map_unit_key":{"type":"string","title":"Map Unit Key"},"map_unit_symbol":{"type":"string","title":"Map Unit Symbol"},"map_unit_name":{"type":"string","title":"Map Unit Name"},"component_key":{"type":"string","title":"Component Key"},"component_name":{"type":"string","title":"Component Name"},"component_percent":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Component Percent"},"horizon_key":{"type":"string","title":"Horizon Key"},"horizon_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Horizon Name"}},"additionalProperties":false,"type":"object","required":["area_symbol","map_unit_key","map_unit_symbol","map_unit_name","component_key","component_name","component_percent","horizon_key","horizon_name"],"title":"SurveyContext"},"Transformation":{"properties":{"operation":{"type":"string","title":"Operation"},"from_unit":{"type":"string","title":"From Unit"},"to_unit":{"type":"string","title":"To Unit"},"formula":{"type":"string","title":"Formula"}},"additionalProperties":false,"type":"object","required":["operation","from_unit","to_unit","formula"],"title":"Transformation"},"Uncertainty":{"properties":{"lower":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Lower"},"upper":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Upper"},"method":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Method"}},"additionalProperties":false,"type":"object","title":"Uncertainty"}}}}