{
  "openapi": "3.0.1",
  "info": {
    "title": "Depth to Groundwater Screener - USGS Water Levels, Phase I ESA",
    "description": "Depth to groundwater near any US coordinate from USGS monitoring wells. Returns depth below land surface in feet, the measurement date, its age, datum and approval status, plus shallowest and median depth in radius. Stale, dry, pumping and artesian readings are labelled, never passed off as current.",
    "version": "1.0",
    "x-build-id": "fAQqpccotwxRve2ue"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/malonestar~usgs-groundwater-depth-screener/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-malonestar-usgs-groundwater-depth-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~usgs-groundwater-depth-screener/runs": {
      "post": {
        "operationId": "runs-sync-malonestar-usgs-groundwater-depth-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~usgs-groundwater-depth-screener/run-sync": {
      "post": {
        "operationId": "run-sync-malonestar-usgs-groundwater-depth-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",
        "required": [
          "assets"
        ],
        "properties": {
          "assets": {
            "title": "Sites to screen",
            "type": "array",
            "description": "One object per site: {\"lat\": 40.7891, \"lon\": -73.1350, \"label\": \"Long Island NY site\", \"radiusMiles\": 1}. lat/lon are WGS84 decimal degrees and are validated numerically before any query is built. label is free text echoed on every output row. radiusMiles is optional and overrides the run-level radius for that site only."
          },
          "radiusMiles": {
            "title": "Search radius (miles)",
            "minimum": 1,
            "maximum": 25,
            "type": "integer",
            "description": "Run-level search radius in statute miles, used for any site that does not carry its own radiusMiles. Accepts 1 to 25; ASTM E1527-21 physical-setting review commonly uses 0.5 or 1 mile. If omitted the actor uses 1 mile. A square bounding box fetches candidates and every candidate is then re-filtered by true haversine distance, so this is a real circle."
          },
          "includeWellDetail": {
            "title": "Emit one row per monitoring location as well as the site summary",
            "type": "boolean",
            "description": "When true, each site summary row is followed by one row per USGS monitoring location inside the radius, nearest first, with the well's depth, aquifer, land-surface altitude and datum, its most recent static water level, that reading's date, age, approval status and condition qualifiers. When false (the actor's behaviour if omitted) only the one summary row per site is emitted. Every row is a billable result, so leave this off for large-radius portfolio screens."
          },
          "maxWellsPerAsset": {
            "title": "Max monitoring-location rows per site",
            "minimum": 1,
            "maximum": 2000,
            "type": "integer",
            "description": "Caps how many per-location detail rows are emitted for each site when includeWellDetail is on. Locations are always emitted nearest-first, so the cap keeps the closest ones. If omitted the actor uses 50."
          },
          "maxAssets": {
            "title": "Max sites per run",
            "minimum": 1,
            "maximum": 200,
            "type": "integer",
            "description": "Safety cap on how many sites a single run will screen. Extra sites are skipped with a warning in the log. If omitted the actor uses 25."
          },
          "includeHistory": {
            "title": "Fetch the full reading history for the nearest wells",
            "type": "boolean",
            "description": "When true the actor also retrieves the complete depth-to-water record for the nearest few locations and reports the observed minimum, maximum, median and total fluctuation - the seasonal range dewatering and basement design actually need, which a single latest reading cannot give you. Costs one extra USGS request per well. If omitted this is off."
          },
          "historyWellCount": {
            "title": "How many nearby wells to fetch history for",
            "minimum": 1,
            "maximum": 25,
            "type": "integer",
            "description": "Number of nearest locations (that have any water-level data) to retrieve a full history for when includeHistory is on. If omitted the actor uses 3."
          },
          "maxAgeYearsForCurrent": {
            "title": "Age beyond which a reading is treated as stale (years)",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "USGS groundwater records are historical - many wells were last measured decades ago. A reading older than this many years is counted as stale, and a site where EVERY reading is older gets all_readings_stale = true. This never suppresses a reading; it labels it. If omitted the actor uses 5 years."
          },
          "shallowGroundwaterThresholdFeet": {
            "title": "Shallow-groundwater threshold (feet below land surface)",
            "minimum": 1,
            "maximum": 500,
            "type": "integer",
            "description": "Depth at or above which the shallowest measured water level raises shallow_groundwater_flag. If omitted the actor uses 15 feet. The flag is null - never false - whenever no usable static depth was found, so a site with no data is never reported as having deep groundwater."
          },
          "apiKey": {
            "title": "Your USGS Water Data API key (optional)",
            "type": "string",
            "description": "Optional. The USGS OGC API is keyless, but the anonymous quota is 1,000 requests per hour PER IP ADDRESS and Apify runs from shared addresses, so a busy hour can return HTTP 429 through no fault of your run. A free key from https://api.waterdata.usgs.gov/signup/ moves you to a private quota. Leave blank to use the anonymous quota."
          },
          "skipDriftChecks": {
            "title": "Skip the live upstream integrity checks",
            "type": "boolean",
            "description": "Diagnostic only. The actor normally verifies the live API before emitting anything: the four required collections are present, parameter code 72019 still means depth below land surface in feet, two pinned canary wells return their pinned identity and earliest measurement, a mid-Pacific negative control returns zero, and a cursor walk is proved to terminate. Skipping them removes the guarantee that the answers came from an undegraded source."
          },
          "simulateOutage": {
            "title": "Force a source failure (diagnostic)",
            "enum": [
              "none",
              "measurements",
              "locations",
              "both"
            ],
            "type": "string",
            "description": "Permanent diagnostic seam used to prove the failure path without waiting for a real outage. 'measurements' fails the water-level read, 'locations' fails the monitoring-location read, 'both' fails both, 'none' is the normal behaviour. With 'both' the run fails loudly and emits nothing."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}