response.SDAResponse
response.SDAResponse(raw_data)Represents a response from the Soil Data Access web service.
Attributes
| Name | Description |
|---|---|
| columns | Get column names. |
| data | Get raw data rows. |
| data_quality_score | Get the data quality score (0.0 to 1.0). |
| has_warnings | Check if the response has any validation warnings. |
| is_valid | Check if the response passed validation (no errors). |
| metadata | Get column metadata. |
| validation_result | Get the validation result for this response. |
Methods
| Name | Description |
|---|---|
| find_fallback_columns | Find fallback column names when preferred columns are not available. |
| from_json | Create response from JSON string. |
| get_column_types | Extract column data types from metadata. |
| get_python_types | Get Python-compatible type mapping using unified TypeMap. |
| get_validation_summary | Get a summary of validation results. |
| handle_missing_fields | Handle missing required fields with fallbacks or defaults. |
| is_empty | Check if the response contains any data rows. |
| recover_partial_data | Attempt to recover partial data by skipping malformed records. |
| to_dataframe | Convert to pandas, polars, or geopandas DataFrame with proper type conversion. |
| to_dict | Convert to list of dictionaries with basic type conversion and error recovery. |
| to_geodataframe | Alias for to_geopandas() for compatibility. |
| to_geopandas | Convert to GeoPandas GeoDataFrame if geometry column exists. |
| to_pandas | Convert to pandas DataFrame with proper type conversion. |
| to_polars | Convert to polars DataFrame with proper type conversion. |
| to_records | Alias for to_dict() for compatibility. |
| to_soilprofilecollection | Convert to SoilProfileCollection. |
| validate | Validate the response based on its type. |
find_fallback_columns
response.SDAResponse.find_fallback_columns(
available_columns,
preferred_columns,
fallback_mappings=None,
)Find fallback column names when preferred columns are not available.
Args: available_columns: List of columns actually present in the data preferred_columns: List of preferred column names fallback_mappings: Optional mapping of preferred -> [fallback1, fallback2, …]
Returns: Dictionary mapping preferred column names to available fallback names
from_json
response.SDAResponse.from_json(json_str)Create response from JSON string.
get_column_types
response.SDAResponse.get_column_types()Extract column data types from metadata.
get_python_types
response.SDAResponse.get_python_types()Get Python-compatible type mapping using unified TypeMap.
get_validation_summary
response.SDAResponse.get_validation_summary()Get a summary of validation results.
handle_missing_fields
response.SDAResponse.handle_missing_fields(
data,
required_fields,
fallback_values=None,
)Handle missing required fields with fallbacks or defaults.
Args: data: The data dictionary to check required_fields: List of field names that must be present fallback_values: Optional mapping of field names to fallback values
Returns: Tuple of (processed_data, missing_fields_list)
is_empty
response.SDAResponse.is_empty()Check if the response contains any data rows.
recover_partial_data
response.SDAResponse.recover_partial_data(max_errors=10)Attempt to recover partial data by skipping malformed records.
Args: max_errors: Maximum number of errors to tolerate before giving up
Returns: Tuple of (valid_records, error_records)
to_dataframe
response.SDAResponse.to_dataframe(
library='pandas',
convert_types=True,
geometry_col=None,
crs=None,
)Convert to pandas, polars, or geopandas DataFrame with proper type conversion.
Args: library: Output library - “pandas”, “polars”, “geopandas”, or “geodataframe”. convert_types: Whether to apply type conversion. Defaults to True. geometry_col: Geometry column name (geopandas/geodataframe only). crs: Coordinate Reference System (geopandas/geodataframe only).
to_dict
response.SDAResponse.to_dict()Convert to list of dictionaries with basic type conversion and error recovery.
Returns: List of dictionaries where each dictionary represents a row with column names as keys and converted values as values.
to_geodataframe
response.SDAResponse.to_geodataframe(
convert_types=True,
geometry_col=None,
crs=None,
)Alias for to_geopandas() for compatibility.
to_geopandas
response.SDAResponse.to_geopandas(
convert_types=True,
geometry_col=None,
crs=None,
)Convert to GeoPandas GeoDataFrame if geometry column exists.
This method provides a convenient ergonomic way to transform spatial SDA responses into a :class:geopandas.GeoDataFrame. It automatically detects a geometry column containing WKT (Well-Known Text) representations, converts them to Shapely geometries, and creates a GeoDataFrame with the appropriate CRS.
The resulting GeoDataFrame can be plotted directly with Matplotlib or used with all standard GeoPandas operations.
Example
Using fetch_by_keys (preferred for bulk fetching):
from soildb import fetch_by_keys mukeys = [481608, 481600] response = fetch_by_keys.sync(mukeys, “mupolygon”, include_geometry=True) gdf = response.to_geopandas() gdf.plot(column=“mukey”, legend=True) import matplotlib.pyplot as plt plt.show()
Using spatial_query (for spatial operations):
from soildb import spatial_query bbox = {“xmin”: -94.7, “ymin”: 42.0, “xmax”: -94.6, “ymax”: 42.1} response = spatial_query.sync(bbox, “mupolygon”, return_type=“spatial”) gdf = response.to_geopandas()
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| convert_types | bool | Whether to apply type conversion during DataFrame creation. Defaults to True. |
True |
| geometry_col | str | Name of the geometry column in the response. If None, auto-detects using standard SDA geometry column naming patterns: 1. Geographic columns (*geo, preferred): mupolygongeo, mupointgeo, mulinegeo, sapolygongeo, featpointgeo, featlinegeo 2. Standard geometry column (fallback) 3. Projected columns (*proj, final fallback): mupolygonproj, mupointproj, etc. Comparisons are case-insensitive. Specify this parameter explicitly for custom geometry column names (e.g., geom, shape, wkt) |
None |
| crs | str | Coordinate Reference System (EPSG code or any format supported by geopandas). If None, the CRS is inferred from the geometry column name: - Geographic *geo columns infer “EPSG:4326” (WGS 84) - geometry column infers “EPSG:4326” - Projected *proj columns infer “EPSG:3857” (Web Mercator) Always pass crs explicitly if your WKT coordinates use a non-standard CRS. For example, if a custom query returns WKT with EPSG:5070 coordinates, pass crs="EPSG:5070" to override the default inference. |
None |
Returns
| Name | Type | Description |
|---|---|---|
| geopandas.GeoDataFrame | A GeoDataFrame containing the response data with geometries. |
Raises
| Name | Type | Description |
|---|---|---|
| ImportError | If geopandas or shapely are not installed. |
|
| ValueError | If no geometry column is found in the response data. |
to_pandas
response.SDAResponse.to_pandas(convert_types=True)Convert to pandas DataFrame with proper type conversion.
to_polars
response.SDAResponse.to_polars(convert_types=True)Convert to polars DataFrame with proper type conversion.
to_records
response.SDAResponse.to_records()Alias for to_dict() for compatibility.
to_soilprofilecollection
response.SDAResponse.to_soilprofilecollection(
site_id_col='cokey',
hz_id_col='chkey',
hz_top_col='hzdept_r',
hz_bot_col='hzdepb_r',
site_data=None,
)Convert to SoilProfileCollection.
Requires the soilprofilecollection package: pip install soildb[soil]
Args: site_id_col: Profile/site identifier column. Default “cokey” (SDA component key). hz_id_col: Horizon identifier column. Default “chkey” (SDA horizon key). hz_top_col: Horizon top depth column. Default “hzdept_r”. hz_bot_col: Horizon bottom depth column. Default “hzdepb_r”. site_data: Optional DataFrame with site-level data, joined on site_id_col.
validate
response.SDAResponse.validate(response_type='general')Validate the response based on its type.
Unified validation entry point that routes to appropriate validators.
Args: response_type: Type of response to validate: - “general”: General SDA response validation - “mapunit”: Mapunit-specific validation - “pedon”: Pedon-specific validation
Returns: ValidationResult with comprehensive validation details
Examples: >>> response = SDAResponse(data) >>> result = response.validate(“mapunit”) >>> if result.is_valid(): … print(f”Quality score: {result.data_quality_score}“)