{ "openapi": "3.0.1", "info": { "title": "USDA Cropland Data Layer Farmland & Land-Cover Screener", "description": "Farmland & land-cover API: batch coordinates to USDA Cropland Data Layer class (Corn, Soybeans, Developed, Forest, Water), an active-cropland flag, and a prime-farmland proxy. For solar-siting, land-use diligence, and farmland-protection screening. Keyless, MCP-ready. Prime-farmland is a proxy.", "version": "1.4", "x-build-id": "kMvFZi0uULEYhFtJB" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/malonestar~usda-cdl-farmland-siting-screener/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-malonestar-usda-cdl-farmland-siting-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~usda-cdl-farmland-siting-screener/runs": { "post": { "operationId": "runs-sync-malonestar-usda-cdl-farmland-siting-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~usda-cdl-farmland-siting-screener/run-sync": { "post": { "operationId": "run-sync-malonestar-usda-cdl-farmland-siting-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": "List of coordinates to classify against the USDA Cropland Data Layer. Each item is an object: {\"lat\": , \"lon\": , \"label\": \"\"}. Coverage is the Contiguous United States only. A point outside CONUS returns a row with coverage_status=\"out_of_coverage\" and every land-cover flag NULL - that is not a finding of \"no farmland\". Each site produces exactly one billable dataset row." }, "year": { "title": "CDL year", "minimum": 1997, "maximum": 2100, "type": "integer", "description": "USDA Cropland Data Layer vintage to sample. LEAVE EMPTY to use the newest vintage USDA publishes, which the actor discovers live on every run from whichever USDA backend answers rather than assuming one. Accepted range follows the service (1997 to the current latest); a year outside it is clamped and the substitution is reported in cdl_year_note." }, "maxAssets": { "title": "Max site lookups", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Safety cap on the number of sites classified per run. Sites beyond this cap are skipped with a warning.", "default": 500 }, "sampleRadiusMeters": { "title": "Area sample radius (metres)", "minimum": 0, "maximum": 5000, "type": "integer", "description": "Optional. When greater than 0, each site also gets a land-cover COMPOSITION over a square box of this half-width (USDA GetCDLStat on CropScape, or computeHistograms on the failover image service) - percent cropland, pasture, forest, wetland, water, developed, plus the dominant class and the top five classes by acreage. A siting decision is about a parcel, not a single 30 m pixel. 0 (default) keeps the point-only behaviour and leaves every area_* field null. Costs one extra upstream call per site; no extra billable rows. NOTE: the USDA GetCDLStat clip service is much slower than the point lookup and does not always answer; each site gets 20 seconds for it and falls back to area_status=\"unavailable\" without affecting the land-cover result. Off by default for that reason.", "default": 0 }, "backend": { "title": "CDL backend", "enum": [ "auto", "cropscape", "pdi_imageserver" ], "type": "string", "description": "Which USDA service answers. \"auto\" (default and recommended) uses the NASS CropScape point service and automatically fails over to the USDA CroplandCROS image service if CropScape cannot be reached or verified - so a CropScape outage degrades the run instead of ending it. Pin a specific backend only if you need every answer to come from one named service; a pinned backend is NEVER silently replaced, so if it is unhealthy the run fails loudly and bills nothing. Both services publish the same annual USDA Cropland Data Layer, but they reproject it differently and their pixel grids are offset by about one pixel, so within roughly 10-30 m of a field boundary they can return adjacent classes. Every row states which one answered in cdl_backend.", "default": "auto" }, "simulateOutage": { "title": "Simulate a backend outage (diagnostic)", "enum": [ "none", "primary", "secondary", "both" ], "type": "string", "description": "Diagnostic only - leave as \"none\" for real screening. Forces one or both USDA backends to be treated as unreachable so the automatic failover path can be exercised on demand: \"primary\" proves a CropScape outage is answered by the image service (rows come back labelled cdl_backend=\"pdi_imageserver\", cdl_backend_failover=true), \"secondary\" proves the reverse, \"both\" proves the run fails loudly and bills nothing when neither service can be verified. It never fabricates data - the named backend is simply not contacted.", "default": "none" } } }, "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 } } } } } } } } } }