# USGS Karst Sinkhole Risk Screener — Geohazard by Coordinate (`malonestar/karst-sinkhole-risk-screener`) Actor Karst & sinkhole-risk screener: batch point-in-polygon over the USGS national CONUS\_Karst compilation (7 layers: carbonate, evaporite, sandstone karst + pseudokarst). Returns in\_karst\_terrain, karst type, near-surface vs buried, rock unit, and an editorial sinkhole-risk tier per coordinate. - **URL**: https://apify.com/malonestar/karst-sinkhole-risk-screener.md - **Developed by:** [Kyle Maloney](https://apify.com/malonestar) (community) - **Categories:** Real estate, Developer tools, Agents - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $4.40 / 1,000 results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## USGS Karst Sinkhole Risk Screener — Geohazard by Coordinate Batch karst and pseudokarst susceptibility screen. Send a list of coordinates, get back a point-in-polygon check against all 7 relevant layers of the USGS **CONUS_Karst** compilation (the national soluble-rock/karst map behind USGS Open-File Report 2014-1156, Weary & Doctor) — carbonate karst, evaporite karst, sandstone karst, subsurface evaporite basins, a broad gypsum extent, and two non-carbonate pseudokarst mechanisms (soil piping, volcanic lava tubes). Each asset gets a plain-English risk note, a `sinkhole_risk_context` tier (Elevated / Moderate / None mapped), and a `geotech_phase1_flag` for due-diligence checklists. **Be honest about what this is:** this is a *regional geology susceptibility screen*, not a site-specific sinkhole prediction, a geotechnical investigation, or an insurance/engineering determination. USGS karst polygons are drawn at state/formation scale. A "clear" result does not rule out an undocumented local sinkhole. A "hit" does not mean collapse is imminent. Every row carries a `disclaimer` field saying exactly that — read it before you build anything on top of this actor's output. ### Who this is for - **Phase-I ESA / environmental consultants** — karst and sinkhole potential is a standard checklist item (ASTM E1527); this turns a manual USGS map lookup into a batch API call. - **Geotechnical engineers & CRE lenders** — flag a portfolio of sites for soluble-bedrock foundation risk before ordering a full subsurface investigation. - **Sinkhole/subsidence insurance underwriters** (especially FL, TX, MO, PA, TN, KY) — a fast first-pass screen ahead of full underwriting. - **Land developers & real-estate due diligence teams** siting anything from a single pad site to a subdivision. - **AI agents / MCP tool chains** doing automated site-diligence workflows — chain this with the portfolio's landslide, seismic, and levee screeners for a full geohazard sweep from one set of coordinates. ### Example input ```json { "assets": [ { "lat": 28.54, "lon": -81.38, "label": "Orlando, FL" }, { "lat": 37.5, "lon": -85.6, "label": "Mammoth Cave region, KY" }, { "lat": 32.0, "lon": -104.0, "label": "Delaware Basin, TX/NM" }, { "lat": 39.7392, "lon": -104.9903, "label": "Denver, CO (buried evaporite basin)" }, { "lat": 44.5, "lon": -113.5, "label": "Craters of the Moon area, ID" } ], "radiusMiles": 2, "maxAssets": 500 } ```` ### Output fields (one row per asset) | Field | Meaning | |---|---| | `asset_label`, `asset_lat`, `asset_lon` | Echo of the input site. | | `in_karst_terrain` | TRUE if the exact coordinate falls inside a mapped karst/pseudokarst polygon (authoritative point-in-polygon test). | | `primary_karst_class` / `primary_karst_label` | The highest-severity matched layer (carbonate/evaporite karst rank above sandstone karst, which ranks above subsurface basins, extents, and pseudokarst). | | `near_surface` | TRUE = soluble rock at/near the land surface (the classic active-dissolution condition). FALSE = buried under insoluble cover. Null when not applicable or no hit. | | `karst_type_detail` | The raw USGS description decoded for the primary hit (rock type, depth-of-burial, climate; or basin/lithology for subsurface layers). | | `rock_unit`, `mapped_state` | Named formation and state, where the source data carries them. | | `layers_matched`, `layers_matched_count` | Every karst/pseudokarst layer that hits at this exact coordinate (units can overlap). | | `pseudokarst_flag` | TRUE if the hit is soil-piping or lava-tube pseudokarst rather than true soluble-rock karst. | | `nearby_karst_within_radius`, `nearby_karst_types` | When the exact point is clear, whether mapped karst falls within `radiusMiles` — catches near-boundary sites given how coarsely national karst polygons are drawn. | | `sinkhole_risk_context` | Editorial tier: **Elevated** (soluble rock at/near surface), **Moderate** (karst/pseudokarst present but buried, regional, or non-carbonate), **None mapped**. | | `geotech_phase1_flag` | TRUE when this site should be a karst/sinkhole line item in Phase-I due diligence. | | `note` | Plain-English one-line summary. | | `disclaimer`, `source_url`, `checked_at` | Standing caveat, the USGS FeatureServer used, and the run timestamp. | | `error` | Per-asset error (bad coordinate or upstream query failure); null when OK. | ### Use as an MCP tool This actor is Pay-Per-Event priced on the automatic Result event, which makes it directly callable by AI agents (Claude, Cursor, etc.) via `mcp.apify.com`. Field-level output descriptions are written so an agent can reason about `sinkhole_risk_context` and `geotech_phase1_flag` without extra prompting — useful as a grounding tool in a larger site-diligence or underwriting agent. ### FAQ **Does this predict an actual sinkhole at my address?** No. It screens against a national, regional-scale geologic compilation. Use it to triage which sites need a real geotechnical/karst investigation, not as a substitute for one. **Why does Orlando, FL come back "Moderate" instead of "Elevated" when Florida is famous for sinkholes?** Because the USGS map classifies much of central Florida's carbonate bedrock as *buried* under insoluble sediment (cover-collapse country), not exposed at the surface. Buried soluble rock still carries real subsidence risk — it's just a different collapse mechanism (cover-collapse vs. surface dissolution) than bare, near-surface carbonate karst in places like the Kentucky/Missouri karst belt, which this actor scores Elevated. **What counts as "pseudokarst"?** Terrain that behaves like karst (collapse-prone voids) but isn't dissolved soluble rock — soil piping in non-carbonate sediments, and lava tubes in volcanic terrain. Flagged separately via `pseudokarst_flag`. **Does this cover Alaska or Hawaii?** No — the USGS CONUS\_Karst compilation is CONUS-only. A non-CONUS coordinate returns a valid `None mapped` clear row, not an error. **What does a "clear" result cost?** Nothing beyond the tiny actor-start — billing is the automatic Result event per pushed row (Pay-Per-Event), so an empty/clear screen doesn't inflate your bill. # Actor input Schema ## `assets` (type: `array`): List of sites to screen for karst/pseudokarst susceptibility. Each item is an object with numeric lat and lon (WGS84 decimal degrees) and an optional label. One billable result row is returned per asset, even when the site is clear. ## `radiusMiles` (type: `number`): For sites where the exact coordinate is clear, how far (miles) to search for mapped karst terrain nearby (flags near-boundary situations). Clamped to 0.1-25 miles. Not used when the coordinate itself is already inside a mapped karst layer. ## `maxAssets` (type: `integer`): Safety cap on how many assets to screen in one run. ## Actor input object example ```json { "assets": [ { "lat": 28.54, "lon": -81.38, "label": "Orlando, FL (buried carbonate karst)" }, { "lat": 39.7392, "lon": -104.9903, "label": "Denver, CO (buried evaporite basin)" } ], "radiusMiles": 2, "maxAssets": 500 } ``` # Actor output Schema ## `results` (type: `string`): The default dataset. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "assets": [ { "lat": 28.54, "lon": -81.38, "label": "Orlando, FL (buried carbonate karst)" }, { "lat": 39.7392, "lon": -104.9903, "label": "Denver, CO (buried evaporite basin)" } ], "radiusMiles": 2, "maxAssets": 500 }; // Run the Actor and wait for it to finish const run = await client.actor("malonestar/karst-sinkhole-risk-screener").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "assets": [ { "lat": 28.54, "lon": -81.38, "label": "Orlando, FL (buried carbonate karst)", }, { "lat": 39.7392, "lon": -104.9903, "label": "Denver, CO (buried evaporite basin)", }, ], "radiusMiles": 2, "maxAssets": 500, } # Run the Actor and wait for it to finish run = client.actor("malonestar/karst-sinkhole-risk-screener").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "assets": [ { "lat": 28.54, "lon": -81.38, "label": "Orlando, FL (buried carbonate karst)" }, { "lat": 39.7392, "lon": -104.9903, "label": "Denver, CO (buried evaporite basin)" } ], "radiusMiles": 2, "maxAssets": 500 }' | apify call malonestar/karst-sinkhole-risk-screener --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=malonestar/karst-sinkhole-risk-screener", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "USGS Karst Sinkhole Risk Screener — Geohazard by Coordinate", "description": "Karst & sinkhole-risk screener: batch point-in-polygon over the USGS national CONUS_Karst compilation (7 layers: carbonate, evaporite, sandstone karst + pseudokarst). Returns in_karst_terrain, karst type, near-surface vs buried, rock unit, and an editorial sinkhole-risk tier per coordinate.", "version": "1.0", "x-build-id": "RrO2bfyEGbeYo9zZY" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/malonestar~karst-sinkhole-risk-screener/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-malonestar-karst-sinkhole-risk-screener", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/malonestar~karst-sinkhole-risk-screener/runs": { "post": { "operationId": "runs-sync-malonestar-karst-sinkhole-risk-screener", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/malonestar~karst-sinkhole-risk-screener/run-sync": { "post": { "operationId": "run-sync-malonestar-karst-sinkhole-risk-screener", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "assets": { "title": "Assets (coordinates to screen)", "type": "array", "description": "List of sites to screen for karst/pseudokarst susceptibility. Each item is an object with numeric lat and lon (WGS84 decimal degrees) and an optional label. One billable result row is returned per asset, even when the site is clear.", "default": [ { "lat": 28.54, "lon": -81.38, "label": "Orlando, FL (buried carbonate karst)" }, { "lat": 39.7392, "lon": -104.9903, "label": "Denver, CO (buried evaporite basin)" } ] }, "radiusMiles": { "title": "Nearby-karst search radius (miles)", "minimum": 0.1, "maximum": 25, "type": "number", "description": "For sites where the exact coordinate is clear, how far (miles) to search for mapped karst terrain nearby (flags near-boundary situations). Clamped to 0.1-25 miles. Not used when the coordinate itself is already inside a mapped karst layer.", "default": 2 }, "maxAssets": { "title": "Max assets", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Safety cap on how many assets to screen in one run.", "default": 500 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```