{ "openapi": "3.0.1", "info": { "title": "Oil & Gas Well Permits Search & Monitor API (ND/CO)", "description": "Search and monitor US oil & gas well permits and wells from official state ArcGIS sources (North Dakota / Bakken, Colorado). Filter by state, operator, status, well type and county, and track newly issued drilling permits for lead gen. Keyless, official sources.", "version": "1.0", "x-build-id": "AyLl6eOomrNYPGFmL" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/malonestar~oil-gas-well-permits/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-malonestar-oil-gas-well-permits", "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~oil-gas-well-permits/runs": { "post": { "operationId": "runs-sync-malonestar-oil-gas-well-permits", "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~oil-gas-well-permits/run-sync": { "post": { "operationId": "run-sync-malonestar-oil-gas-well-permits", "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": [ "states" ], "properties": { "states": { "title": "States", "type": "array", "description": "REQUIRED. Two-letter state codes to search. Configured: ND (North Dakota / Bakken), CO (Colorado). Name the states explicitly — there is no default, so a run can never quietly answer about one basin when you meant several.", "items": { "type": "string" } }, "operator": { "title": "Operator name contains", "type": "string", "description": "Return only wells whose operator name contains this text (case-insensitive), e.g. Continental, Chevron." }, "status": { "title": "Well / permit status (exact)", "type": "string", "description": "Filter by exact status code. North Dakota uses codes like LOC (permitted location), A (active), DRY, PA (plugged & abandoned). Colorado uses codes like AL. Empty = all statuses." }, "wellType": { "title": "Well type contains", "type": "string", "description": "Filter by well type keyword (North Dakota only), e.g. OG (oil & gas), GAS, OIL. Ignored for states without a well-type field." }, "county": { "title": "County contains", "type": "string", "description": "Return only wells whose county name contains this text (case-insensitive), e.g. McKenzie, Weld." }, "nameContains": { "title": "Well name contains", "type": "string", "description": "Return only wells/facilities whose name contains this text (case-insensitive)." }, "apiNumber": { "title": "API / facility number (exact)", "type": "string", "description": "Look up one exact identifier. North Dakota matches its API well number (raw column api_no, e.g. 33-053-10805-00-00). Colorado matches its facility number (raw column fac_num, e.g. 4-8) — which is NOT an API number, so it is published in the facility_number output field and Colorado rows carry api_number: null." }, "sinceModified": { "title": "Spudded since (YYYY-MM-DD) — SPUD date, NOT permit-issue date", "pattern": "^$|^\\d{4}-\\d{1,2}-\\d{1,2}$", "type": "string", "description": "Lower bound on the state's own date column. READ THIS BEFORE USING IT FOR PERMIT MONITORING: no state configured here publishes a permit-ISSUE date. North Dakota publishes SPUD_DATE only, so this window selects wells DRILLED since the date, not permits ISSUED since it — and because SQL treats a null date as not-greater-than, it structurally EXCLUDES all 630 permitted-but-not-yet-drilled (status LOC) wells, measured live 2026-08-25. For permitted inventory use status=\"LOC\", or set includeUndatedRecords to keep undated records (each labelled date_filter_match=\"undated_included\"). Colorado's layer has NO date column at all: a Colorado-only run with this field set now FAILS rather than returning an unfiltered result set labelled as filtered. Every row publishes date_filter_basis, date_filter_applied and date_filter_is_permit_issue_date. Format MUST be YYYY-MM-DD (e.g. 2026-01-15); any other format is rejected and the run fails without billing rather than being silently reinterpreted by ArcGIS's own date parser. Slash forms are rejected on purpose: live-measured against North Dakota, an ambiguous 05/06/2025 is silently read as May 6 (US order) and differs from the June 5 (EU) reading by 8.0% of matching wells, with nothing in the response indicating a format was guessed. Empty = no lower bound." }, "includeUndatedRecords": { "title": "Keep records with no date when a date window is applied", "type": "boolean", "description": "Only meaningful together with sinceModified, and only on a state that has a date column (North Dakota). When false (the default) a date window drops every record whose date is null — which on North Dakota means all 630 permitted-but-not-yet-drilled LOC wells, i.e. exactly the set a new-permit buyer wants. When true the window becomes (date > value OR date IS NULL) and each undated row is labelled date_filter_match=\"undated_included\", so a record that was never verified to fall inside the window is never presented as though it had been. Note this widens the result set: on North Dakota 6,988 of 43,835 wells carry a null spud date.", "default": false }, "maxResults": { "title": "Max results per state", "minimum": 1, "maximum": 200000, "type": "integer", "description": "Maximum number of well/permit records to return per state.", "default": 1000 }, "monitor": { "title": "Delta mode (only new since last run)", "type": "boolean", "description": "When scheduled, emit only wells/permits not seen in previous runs — a recurring new-permit alert backed by a key-value store of seen IDs.", "default": false }, "verifyUpstream": { "title": "Verify the state layers before billing (recommended)", "type": "boolean", "description": "Runs a live drift gate against each selected state layer BEFORE any billable row is fetched — a handful of cheap metadata, count-only and group-by requests, none of them billable. It checks that the layer still holds at least its measured floor of records (North Dakota 43,835 and Colorado 84,927 on 2026-08-25), still publishes every column this Actor reads, still returns one pinned canary record with its historical values intact, returns ZERO for an impossible status code, and still publishes its documented status vocabulary. A probe that completes and measures something wrong fails the run and bills nothing; a probe that never completes is treated as an availability problem, and only a load-bearing one of those is fatal. Turn this off only if you accept that a silently emptied or re-scoped layer would go undetected — every row then carries drift_gate_status=\"skipped\".", "default": true }, "simulateOutage": { "title": "Diagnostic: force a drift-gate branch", "enum": [ "none", "drift_required_unavailable", "drift_positive_unavailable", "drift_corroborating_unavailable", "drift_measured_wrong" ], "type": "string", "description": "Diagnostic only. Forces one class of drift-probe outcome so the gate's own failure paths can be re-proved on demand instead of only during a real outage. 'drift_required_unavailable' and 'drift_positive_unavailable' must FAIL the run and bill nothing; 'drift_corroborating_unavailable' must SUCCEED with drift_gate_status=\"verified_degraded\"; 'drift_measured_wrong' forces a completed-but-wrong measurement and must fail the run. Leave as 'none' for normal use.", "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 } } } } } } } } } }