Geosetta API Documentation
Welcome to the Geosetta API Documentation. Our platform offers unparalleled access to a wealth of public geotechnical data, empowering your projects with accurate and comprehensive subsurface information. By becoming a sponsor of Geosetta, you not only contribute to the advancement and accessibility of geotechnical data but also gain exclusive API access. This access allows for seamless integration of our extensive data repository into your systems, facilitating more informed decision-making and innovative solutions in your field. Sponsoring Geosetta is more than just a partnership; it's an opportunity to be at the forefront of geotechnical data utilization and to support the ongoing mission of making this valuable data openly accessible to professionals and researchers worldwide. Join us in this endeavor and unlock the full potential of geotechnical data with Geosetta.
🆕 Preliminary Site Assessment Appendix API - Generate Professional Appendices for Engineering Reports
Generate preliminary site assessment appendices for any user-defined polygon. These appendices are designed to supplement professional engineering reports with geological data, soil information, nearby boreholes, and ML predictions.
Features:
- Professional appendix format suitable for inclusion in engineering reports
- Preliminary site characterization with geological and soil data
- ML predictions for SPT N-values and groundwater depth
- Nearby historical boreholes (5-mile radius)
- USGS geology and SoilsGrid data integration
- Clear disclaimers emphasizing preliminary nature
- Two output formats: JSON data or PDF (base64 encoded)
import requests
import json
api_key = "your_api_key_here"
# Define your polygon (GeoJSON format)
polygon_geojson = {
"type": "Polygon",
"coordinates": [[
[-78.4300, 38.1150], # Northwest corner
[-78.4250, 38.1150], # Northeast corner
[-78.4250, 38.1100], # Southeast corner
[-78.4300, 38.1100], # Southwest corner
[-78.4300, 38.1150] # Close polygon
]]
}
# Request body
request_body = {
"geojson": json.dumps(polygon_geojson),
"format": "pdf" # Options: "pdf" for PDF report, "json" for raw data
}
# Make the request
response = requests.post(
"https://geosetta.org/web_map/api/generate_site_report/",
json=request_body,
headers={
"Authorization": f"Bearer {api_key}", # Or use "X-API-Key": api_key
"Content-Type": "application/json"
}
)
# Check the response
if response.status_code == 200:
result = response.json()
if result['status'] == 'success':
if request_body['format'] == 'pdf':
# Decode base64 PDF
import base64
pdf_data = base64.b64decode(result['pdf'])
# Save to file
with open('site_assessment_appendix.pdf', 'wb') as f:
f.write(pdf_data)
print(f"Appendix PDF saved! Size: {result['metadata']['size_bytes']} bytes")
print(f"Filename: {result['metadata']['filename']}")
else:
# JSON data format
print("Report data received:")
print(f"Polygon area: {result['data']['polygon']['area']['acres']:.2f} acres")
print(f"Geology: {result['data']['geology']['formation']}")
print(f"Nearby boreholes: {result['data']['boreholes']['total_count']}")
else:
print(f"Error: {response.status_code}")
print(response.json())
Response Format (PDF mode):
{
"status": "success",
"pdf": "JVBERi0xLjQKJcfs...", // Base64 encoded PDF
"metadata": {
"filename": "geosetta_site_assessment_appendix_20241205_143022.pdf",
"size_bytes": 98765,
"generation_time": 6.23,
"report_version": "1.0"
},
"disclaimer": {
"text": "This report is for preliminary planning purposes only...",
"terms_url": "https://geosetta.org/terms",
"must_accept": true
}
}
Response Format (JSON mode):
{
"status": "success",
"data": {
"polygon": {
"centroid": {"lat": 38.1125, "lon": -78.4275},
"area": {"acres": 123.45, "hectares": 49.98, "square_meters": 499776},
"address": "Near Charlottesville, VA 22903",
"elevation_ft": 485.2
},
"geology": {
"formation": "Granite",
"age": "Paleozoic",
"major_components": ["Granite", "Gneiss"],
"usgs_url": "https://ngmdb.usgs.gov/..."
},
"soils": {
"soil_type": "Alfisols",
"wrb_class": "Luvisols",
"properties": {
"clay_content": 25.5,
"sand_content": 35.2,
"organic_carbon": 1.8
},
"usda_soil_survey_url": "https://websoilsurvey.sc.egov.usda.gov/..."
},
"predictions": {
"predictions_by_depth": [
{
"depth_ft": 0,
"spt_n": "10-25",
"soil_description": "Medium dense sandy CLAY"
},
// ... more depth predictions to 50 ft
],
"groundwater": {
"depth_label": "Medium (10-50 ft)",
"deviation_label": "Moderate (5-20 ft variation)"
}
},
"boreholes": {
"total_count": 15,
"closest_distance_miles": 0.8,
"all_boreholes": [
{
"functional_key": "38.1234;-78.4321",
"distance_miles": 0.8,
"provider": "VDOT",
"depth_ft": 45,
"pdf_link": "https://geosetta.org/web_map/map/#18/38.1234/-78.4321"
}
// ... more boreholes
]
},
"metadata": {
"collection_time": 5.89,
"timestamp": "2024-12-05T14:30:22Z"
}
},
"disclaimer": {
"text": "This data is for preliminary planning only...",
"terms_url": "https://geosetta.org/terms",
"must_accept": true
}
}
Appendix Contents Include:
- Site Location: Area calculations, nearest address, centroid elevation
- Geological Assessment: USGS formation data, rock types, age
- Soil Analysis: SoilsGrid WRB classification, engineering properties
- Predicted Subsurface Profile: SPT N-values and soil descriptions to 50 ft
- Groundwater Predictions: Depth category and seasonal variation
- Nearby Historical Boreholes: Within 5-mile radius with clickable map links
- Data Sources & References: Complete citations and contact information
API Endpoint to retrive historic Data around Radius:
api_key = "your_api_key_here"
# Your payload and API key
json_payload = {
"deliverableType": "Return_Historic_Data_In_Radius",
"data": {
"points": [
{
"latitude": 39.21884440935613,
"longitude": -76.84346423232522,
"radius_m": 1000
}
]
}
}
# Make the request
response = requests.post(
"https://geosetta.org/web_map/api_key/",
json=json_payload, # Directly send the json_payload
headers={
"Authorization": f"Bearer {api_key}" # Set the API key in the Authorization header
}
)
# Check the response
if response.status_code == 200:
print("API request successful:")
print(response.json())
response_data = response.json() # Convert the Response object to a dictionary
points_in_radius = response_data['results']['points_in_radius']
print(points_in_radius)
else:
print("API request failed:")
print(f"Status code: {response.status_code}")
print(response.text)
The server will respond with a JSON object like this:
{'message': 'Data processed successfully.', 'results': {'points_in_radius': {'type': 'FeatureCollection', 'features': [{'type': 'Point', 'coordinates': [-76.8445259, 39.22082777], 'properties': {'content': ' Geosetta History
\n Source: MDOT
(lat,lng): 39.2208278 , -76.8445259 elev ft: 335.20\n Total Depth: 25.0 ft
Available Deliverables:
\n \n Monthly Precipitation History NOAA
\n \n \n \n
\n View Borehole Log with RSLog\n
\n '}}, {'type': 'Point', 'coordinates': [-76.84413791, 39.22100078], 'properties': {'content': ' Geosetta History
\n Source: MDOT
(lat,lng): 39.2210008 , -76.8441379 elev ft: 346.00\n Total Depth: 5.0 ft
Available Deliverables:
\n \n Monthly Precipitation History NOAA
\n \n \n \n
\n View Borehole Log with RSLog\n
\n '}}, {'type': 'Point', 'coordinates': [-76.8453399, 39.22108078], 'properties': {'content': ' Geosetta History
\n Source: MDOT
(lat,lng): 39.2210808 , -76.8453399 elev ft: 338.10\n Total Depth: 20.0 ft
Available Deliverables:
\n \n Monthly Precipitation History NOAA
\n \n \n \n
\n View Borehole Log with RSLog\n
\n '}}]}}, 'disclaimer': 'The information provided by this API has been made available by various DOTs and other public agencies. The predictive models presented herein are based on machine learning tools applied to the data. The predicted subsurface conditions are a probabilistic model and do not depict the actual conditions at the site. No claim as to the accuracy of the data and predictive model is made or implied. No other representation, expressed or implied, is included or intended and no warranty or guarantee is included or intended in any Geosetta data or models. The User understands these limitations and that Geosetta is a tool for planning subsurface investigations and not a substitute for it. In no event shall Geosetta or the Data Owners be liable to the User or another Party for any incidental, consequential, special, exemplary or indirect damages, lost business profits or lost data arising out of or in any way related to the use of information or data obtained from the Geosetta.org website or API.'}
{'type': 'FeatureCollection', 'features': [{'type': 'Point', 'coordinates': [-76.8445259, 39.22082777], 'properties': {'content': ' Geosetta History
\n Source: MDOT
(lat,lng): 39.2208278 , -76.8445259 elev ft: 335.20\n Total Depth: 25.0 ft
Available Deliverables:
\n \n Monthly Precipitation History NOAA
\n \n \n \n
\n View Borehole Log with RSLog\n
\n '}}, {'type': 'Point', 'coordinates': [-76.84413791, 39.22100078], 'properties': {'content': ' Geosetta History
\n Source: MDOT
(lat,lng): 39.2210008 , -76.8441379 elev ft: 346.00\n Total Depth: 5.0 ft
Available Deliverables:
\n \n Monthly Precipitation History NOAA
\n \n \n \n
\n View Borehole Log with RSLog\n
\n '}}, {'type': 'Point', 'coordinates': [-76.8453399, 39.22108078], 'properties': {'content': ' Geosetta History
\n Source: MDOT
(lat,lng): 39.2210808 , -76.8453399 elev ft: 338.10\n Total Depth: 20.0 ft
Available Deliverables:
\n \n Monthly Precipitation History NOAA
\n \n \n \n
\n View Borehole Log with RSLog\n
\n '}}]}
API Endpoint to retrieve data predictions (Note you can predict up to 50 points per request with a maximum depth of 100 feet.):
New Feature: Groundwater Predictions
Each point now includes groundwater depth and seasonal variation predictions powered by machine learning models:
- Depth Categories:
- 0 = Shallow (≤10 ft)
- 1 = Medium (10-50 ft)
- 2 = Deep (>50 ft)
- Seasonal Deviation Categories:
- 0 = Low variation (≤5 ft)
- 1 = Moderate variation (5-20 ft)
- 2 = High variation (>20 ft)
- Probabilities: Confidence percentages for each category (shallow/medium/deep for depth, low/moderate/high for variation)
api_key = "your_api_key_here"
# Your payload and API key
json_payload = {
"deliverableType": "SPT_Point_Prediction",
"data": {
"points": [
{
"latitude": 39.387080,
"longitude": -76.813480,
"depth": 50,
"surfaceelevation": None # Optional: if not provided, will be calculated automatically
},
{
"latitude": 39.4,
"longitude": -76.8,
"depth": 30
# surfaceelevation will be calculated automatically if not provided
}
]
}
}
# Make the request
response = requests.post(
"https://geosetta.org/web_map/api_key/",
json=json_payload, # Directly send the json_payload
headers={
"Authorization": f"Bearer {api_key}" # Set the API key in the Authorization header
}
)
# Check the response
if response.status_code == 200:
print("API request successful:")
print(response.json())
else:
print("API request failed:")
print(f"Status code: {response.status_code}")
print(response.text)
The server will respond with a JSON object like this:
{
"message": "Data processed successfully.",
"results": [
{
"point": {
"latitude": 39.387080,
"longitude": -76.813480,
"depth": 50,
"surfaceelevation": null,
"minimum_distance_from_trained_point_(mi)": 2.13
},
"profiles": [
{
"depth": 0,
"dominant_grain_size": "SAND",
"dominant_N_value": "10-25"
},
{
"depth": 1,
"dominant_grain_size": "SAND",
"dominant_N_value": "10-25"
},
// ... depth profiles continue for each foot up to the requested depth
{
"depth": 50,
"dominant_grain_size": "CLAY",
"dominant_N_value": "26-41"
}
],
"groundwater": {
"depth_category": 1,
"depth_label": "Medium (10-50 ft)",
"depth_probabilities": {
"shallow": 23.7,
"medium": 55.9,
"deep": 20.4
},
"deviation_category": 1,
"deviation_label": "Moderate (5-20 ft variation)",
"deviation_probabilities": {
"low": 44.9,
"moderate": 50.2,
"high": 4.9
}
}
},
{
"point": {
"latitude": 39.4,
"longitude": -76.8,
"depth": 30,
"surfaceelevation": null,
"minimum_distance_from_trained_point_(mi)": 1.87
},
"profiles": [
{
"depth": 0,
"dominant_grain_size": "SILT",
"dominant_N_value": "1-9"
},
{
"depth": 1,
"dominant_grain_size": "SILT",
"dominant_N_value": "10-25"
},
// ... depth profiles continue for each foot up to the requested depth
{
"depth": 30,
"dominant_grain_size": "SAND",
"dominant_N_value": "10-25"
}
],
"groundwater": {
"depth_category": 0,
"depth_label": "Shallow (≤10 ft)",
"depth_probabilities": {
"shallow": 65.2,
"medium": 28.4,
"deep": 6.4
},
"deviation_category": 0,
"deviation_label": "Low (≤5 ft variation)",
"deviation_probabilities": {
"low": 72.1,
"moderate": 21.3,
"high": 6.6
}
}
}
],
"disclaimer": "The information provided by this API has been made available by various DOTs and other public agencies. The predictive models presented herein are based on machine learning tools applied to the data. The predicted subsurface conditions are a probabilistic model and do not depict the actual conditions at the site. No claim as to the accuracy of the data and predictive model is made or implied. No other representation, expressed or implied, is included or intended and no warranty or guarantee is included or intended in any Geosetta data or models. The User understands these limitations and that Geosetta is a tool for planning subsurface investigations and not a substitute for it. In no event shall Geosetta or the Data Owners be liable to the User or another Party for any incidental, consequential, special, exemplary or indirect damages, lost business profits or lost data arising out of or in any way related to the use of information or data obtained from the Geosetta.org website or API."
}
This endpoint generates a link to geosetta that will show provided project data alongside public history in geosetta for visualization.
api_key = "your_api_key_here"
# Your payload and API key
json_payload = {
"deliverableType": "Project_Link",
"data": {
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"coordinates": [
[
[
-123.119842,
49.323426
],
[
-123.117503,
49.323421
],
[
-123.117524,
49.322477
],
[
-123.118871,
49.322239
],
[
-123.120083,
49.322294
],
[
-123.119842,
49.323426
]
]
],
"type": "Polygon"
},
"properties": {
"Project Title": "RSLog Example Project #1 (Imperial) ",
"Project Number": "EX20-001",
"Client": "ABC Client Company Ltd."
}
},
{
"type": "Feature",
"geometry": {
"coordinates": [
-123.11768,
49.32323
],
"type": "Point"
},
"properties": {
"Name": "AH20-4a",
"Depth": "13 ft",
"Groundwater Depth": "",
"Project Ref.": "RSLog Example Project #1 (Imperial) (EX20-001)"
}
},
{
"type": "Feature",
"geometry": {
"coordinates": [
-123.11934,
49.32298
],
"type": "Point"
},
"properties": {
"Name": "testy",
"Depth": "1 ft",
"Groundwater Depth": "",
"Project Ref.": "RSLog Example Project #1 (Imperial) (EX20-001)"
}
},
{
"type": "Feature",
"geometry": {
"coordinates": [
-123.11843,
49.3227
],
"type": "Point"
},
"properties": {
"Name": "AH21-01",
"Depth": "38.5 ft",
"Groundwater Depth": "",
"Project Ref.": "RSLog Example Project #1 (Imperial) (EX20-001)"
}
},
{
"type": "Feature",
"geometry": {
"coordinates": [
-123.11978,
49.32242
],
"type": "Point"
},
"properties": {
"Name": "AH20-3",
"Depth": "30 ft",
"Groundwater Depth": "16.2 ft",
"Project Ref.": "RSLog Example Project #1 (Imperial) (EX20-001)"
}
}
]
}
}
# Make the request
response = requests.post(
"https://geosetta.org/web_map/api_key/",
json={
"json_data": json.dumps(json_payload) # Encode the dictionary as a JSON string
},
headers={
"Authorization": f"Bearer {api_key}" # Set the API key in the Authorization header
}
)
# Check the response
if response.status_code == 200:
print("API request successful:")
print(response.json())
else:
print("API request failed:")
print(f"Status code: {response.status_code}")
print(response.text)
The server will respond with a JSON object like this:
{'message': 'Data processed successfully.', 'results': 'https://geosetta.org/web_map/map/jqM826', 'disclaimer': 'The information provided by this API has been made available by various DOTs and other public agencies. The predictive models presented herein are based on machine learning tools applied to the data. The predicted subsurface conditions are a probabilistic model and do not depict the actual conditions at the site. No claim as to the accuracy of the data and predictive model is made or implied. No other representation, expressed or implied, is included or intended and no warranty or guarantee is included or intended in any Geosetta data or models. The User understands these limitations and that Geosetta is a tool for planning subsurface investigations and not a substitute for it. In no event shall Geosetta or the Data Owners be liable to the User or another Party for any incidental, consequential, special, exemplary or indirect damages, lost business profits or lost data arising out of or in any way related to the use of information or data obtained from the Geosetta.org website or API.'}
API endpoint retrieves the distance from a pre-trained point. It's important to note that not all data on Geosetta has been included in the training process. Therefore, the distance provided is relative to the nearest location that has been used in our training dataset.
api_key = "your_api_key_here"
# Your payload and API key
json_payload = {
"deliverableType": "Distance_From_Trained_Point",
"data": {
"points": [
{
"latitude": 39.387080,
"longitude": -76.813480,
"depth": 50
},
{
"latitude": 39.4,
"longitude": -76.8,
"depth": 30
}
]
}
}
# Make the request
response = requests.post(
"https://geosetta.org/web_map/api_key/",
json={
"json_data": json.dumps(json_payload) # Encode the dictionary as a JSON string
},
headers={
"Authorization": f"Bearer {api_key}" # Set the API key in the Authorization header
}
)
# Check the response
if response.status_code == 200:
print("API request successful:")
print(response.json())
else:
print("API request failed:")
print(f"Status code: {response.status_code}")
print(response.text)
The server will respond with a JSON object like this:
{'message': 'Data processed successfully.', 'results': {'minimum_distance_from_trained_point_(mi)': 2.13}, 'disclaimer': 'The information provided by this API has been made available by various DOTs and other public agencies. The predictive models presented herein are based on machine learning tools applied to the data. The predicted subsurface conditions are a probabilistic model and do not depict the actual conditions at the site. No claim as to the accuracy of the data and predictive model is made or implied. No other representation, expressed or implied, is included or intended and no warranty or guarantee is included or intended in any Geosetta data or models. The User understands these limitations and that Geosetta is a tool for planning subsurface investigations and not a substitute for it. In no event shall Geosetta or the Data Owners be liable to the User or another Party for any incidental, consequential, special, exemplary or indirect damages, lost business profits or lost data arising out of or in any way related to the use of information or data obtained from the Geosetta.org website or API.'}
API endpoint to convert a pdf boring log to a DIGGS file.
import requests
import json
api_key = "your_api_key_here"
# Example PDF file path
pdf_file_path = '/content/example_boring_log.pdf'
# Your payload and API key
json_payload = {
"deliverableType": "Pdf_Extraction",
"data": {
}
}
# Make the request
with open(pdf_file_path, 'rb') as pdf_file:
response = requests.post(
"https://geosetta.org/web_map/api_key/",
files={'file': pdf_file},
data={
'json_data': json.dumps(json_payload)
},
headers={
"Authorization": f"Bearer {api_key}" # Set the API key in the Authorization header
}
)
# Check the response
if response.status_code == 200:
print("API request successful:")
# Save the zip file content to a file
zip_file_path = '/content/processed_results.zip'
with open(zip_file_path, 'wb') as zip_file:
zip_file.write(response.content)
print(f"Zip file saved to {zip_file_path}")
else:
print("API request failed:")
print(f"Status code: {response.status_code}")
print(response.text)
The server will respond with a JSON object like this:
API request successful:
Zip file saved to /content/processed_results.zip