{ "openapi": "3.0.1", "info": { "title": "Historical Topographic Map Chronology - ASTM Phase I ESA 8.3.4", "description": "Builds the full USGS historical topographic map chronology for any coordinate and runs an ASTM E1527-21 Sec. 8.3.4 historical records review: five-year interval coverage back to 1940, with data gaps explicitly identified. Every map year, scale, quadrangle and download URL. Keyless USGS data.", "version": "1.1", "x-build-id": "34zh5gcD6Or2r6k4P" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/malonestar~usgs-historical-topo-records-review/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-malonestar-usgs-historical-topo-records-review", "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-historical-topo-records-review/runs": { "post": { "operationId": "runs-sync-malonestar-usgs-historical-topo-records-review", "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-historical-topo-records-review/run-sync": { "post": { "operationId": "run-sync-malonestar-usgs-historical-topo-records-review", "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 review", "type": "array", "description": "Properties to build a topographic map chronology for. Each item is an object: {\"lat\": , \"lon\": , \"label\": \"\"}. Each site produces exactly ONE billable dataset row no matter how many maps cover it. An invalid coordinate produces an ERROR row and the run continues; if the USGS source fails for EVERY site the run is failed so nothing is billed." }, "bufferMiles": { "title": "Search buffer (miles)", "minimum": 0, "maximum": 25, "type": "integer", "description": "0 (recommended) asks USGS for the maps whose own footprint COVERS the property - a true point-in-quadrangle test, which is the defensible answer for an ASTM 8.3.4 review. A value above 0 widens the search to any map sheet intersecting a box of that half-width around the point, which brings in adjoining quadrangles and CHANGES what the coverage counts mean. The value used is reported on every row in buffer_miles and query_geometry." }, "includeUsTopo": { "title": "Include the modern US Topo series (2009-present)", "type": "boolean", "description": "ON by default. Adds the current USGS US Topo series so the chronology reaches the present instead of stopping in the 1990s where the historical collection ends. Does NOT change your billing - still one row per site. Its own coverage is reported separately in the us_topo_* columns, and if it fails the ASTM verdict fields go null rather than reporting a gap that US Topo might have filled." }, "reviewStartYear": { "title": "ASTM review start year", "minimum": 1880, "maximum": 2026, "type": "integer", "description": "First year of the ASTM E1527-21 Sec. 8.3.4 review window. 1940 is the standard baseline; set it earlier if the property has an obvious first developed use before 1940, since the standard requires going back to whichever is earlier. Map years found BEFORE this year are still reported, in pre_review_window_map_years." }, "reviewEndYear": { "title": "ASTM review end year", "minimum": 1880, "maximum": 2027, "type": "integer", "description": "Last year of the review window. Leave unset to use the current year, which is what a present-day Phase I reviews back from. Note that the most recent interval is often uncovered even at a well-mapped site: US Topo revises a quadrangle roughly every three years and the current cycle may not have reached it yet." }, "intervalYears": { "title": "Review interval (years)", "minimum": 1, "maximum": 25, "type": "integer", "description": "Length of each coverage interval. ASTM E1527-21 Sec. 8.3.4 calls for approximately five-year intervals, which is the default. Buckets are anchored at the review start year." }, "maxMapsListed": { "title": "Max individual maps listed per row", "minimum": 0, "maximum": 2000, "type": "integer", "description": "Caps the size of the per-row `maps` inventory array. The year-by-year `chronology` and every count are ALWAYS computed over the complete result regardless of this cap, and maps_truncated_in_row tells you when the inventory array was trimmed. Set 0 to omit the inventory entirely and keep only the chronology." }, "maxAssets": { "title": "Max sites per run", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Safety cap on how many sites are reviewed in one run. Sites beyond the cap are skipped with a warning naming how many were left out; they are NOT in the dataset and are not billed." }, "verifyUpstream": { "title": "Verify the USGS source before reviewing (recommended)", "type": "boolean", "description": "ON by default. Before any of your sites are touched, the run confirms USGS still publishes the two collection tags, probes a positive canary in Denver that must return decades of maps back to 1890, probes a US Topo canary, and probes a mid-Pacific negative control that must return exactly zero. If USGS renamed the collection or stopped applying the spatial filter, every site would otherwise report 'no maps cover this property' on a green run. Costs four extra requests." }, "simulateOutage": { "title": "Simulate a source outage (diagnostic)", "enum": [ "none", "historical", "us_topo", "both", "drift_negative_control", "drift_load_bearing" ], "type": "string", "description": "Diagnostic seam for proving the failure paths without waiting for a real outage. 'none' is normal operation. The three source options force a site lookup to fail through the same code path a genuine outage takes. The two drift options force an upstream-verification probe to time out: the negative-control option must still SUCCEED with drift_gate_status=verified_degraded, and the load-bearing option must FAIL, emitting nothing and billing nothing. Leave on 'none' for real work." } } }, "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 } } } } } } } } } }