BOEM Offshore Data Skill

Fetches and analyzes federal OCS offshore oil and gas data from the BOEM/BSEE ArcGIS REST MapServer and BOEM Data Center bulk downloads.

API Key Handling

No API key is required. All BOEM and BSEE data services are public and freely accessible without authentication.

Data Sources

BOEM provides two primary access methods:

1. ArcGIS REST MapServer — real-time spatial and attribute queries against national and regional GIS layers (wells, platforms, leases, pipelines, boundaries)
2. Bulk ASCII Downloads — zipped delimited text files from the BOEM Data Center containing full database exports (production, borehole, lease owner, etc.)

See references/endpoints.md for the complete endpoint catalog.

API Structure

GIS MapServer (Primary Query Interface)

Base URL: https://gis.boem.gov/arcgis/rest/services/BOEM_BSEE/MMC_Layers/MapServer

Key Layers:

Query parameters for {MapServer}/{LayerID}/query:

Bulk Data Downloads

Base URL: https://www.data.boem.gov/

Key download files (all zip archives of delimited text):

Key Fields by Layer

Wells (Layer 1)

• API_NUMBER — 12-digit API well number
• OPERATOR — Operator company number (cross-ref with Company data)
• WELL_NAME — Well name/designation
• SPUD_DATE — Date drilling commenced
• TYPE_CODE_DESC — Well type (Development, Exploratory)
• STATUS / STATUS_DESCRIPTION — Current status (PA=Permanently Abandoned, COM=Completed, DRL=Drilling, etc.)
• DEPTH — Total depth (feet)
• X, Y — Longitude, Latitude (NAD83)

Platforms (Layer 0)

• COMPLEX_ID_NUM — Platform complex identifier
• INSTALL_DATE — Installation date
• REMOVAL_DATE — Removal date (null = still active)

Leases (Layer 15)

• LEASE_NUMBER — OCS lease serial number
• LEASE_STATUS_CD — Status (PROD, EXPR, RELD, TERM, SOP, SOO)
• LEASE_EFF_DATE / LEASE_EXPIR_DATE — Effective and expiration dates
• SALE_NUMBER — Lease sale number
• ROYALTY_RATE — Royalty rate (fraction)
• MINERAL_TYPE_CD — Mineral type code
• CURRENT_AREA / INITIAL_AREA — Lease area

Workflow

Step 1 — Resolve Intent

Map the user's question to the appropriate layer and query type:

If uncertain which layer to query, start by checking the MapServer root to list available layers:

curl -s "https://gis.boem.gov/arcgis/rest/services/BOEM_BSEE/MMC_Layers/MapServer?f=json" \
  | jq '.layers[] | {id, name}'

Step 2 — Build the Query

Attribute query (e.g., wells by status):

curl -s "https://gis.boem.gov/arcgis/rest/services/BOEM_BSEE/MMC_Layers/MapServer/1/query" \
  --data-urlencode "where=STATUS='PA'" \
  --data-urlencode "outFields=API_NUMBER,OPERATOR,WELL_NAME,STATUS_DESCRIPTION,DEPTH,TYPE_CODE_DESC,SPUD_DATE" \
  --data-urlencode "resultRecordCount=20" \
  --data-urlencode "f=json"

Spatial query (e.g., wells within a bounding box):

curl -s "https://gis.boem.gov/arcgis/rest/services/BOEM_BSEE/MMC_Layers/MapServer/1/query" \
  --data-urlencode "geometry=-91,28,-89,29" \
  --data-urlencode "geometryType=esriGeometryEnvelope" \
  --data-urlencode "spatialRel=esriSpatialRelIntersects" \
  --data-urlencode "outFields=API_NUMBER,OPERATOR,WELL_NAME,STATUS_DESCRIPTION,DEPTH" \
  --data-urlencode "resultRecordCount=20" \
  --data-urlencode "f=json"

Count query (e.g., how many wells total):

curl -s "https://gis.boem.gov/arcgis/rest/services/BOEM_BSEE/MMC_Layers/MapServer/1/query?where=1%3D1&returnCountOnly=true&f=json"

Platform query (active platforms only):

curl -s "https://gis.boem.gov/arcgis/rest/services/BOEM_BSEE/MMC_Layers/MapServer/0/query" \
  --data-urlencode "where=REMOVAL_DATE IS NULL" \
  --data-urlencode "outFields=COMPLEX_ID_NUM,INSTALL_DATE" \
  --data-urlencode "resultRecordCount=10" \
  --data-urlencode "f=json"

Lease query (producing leases):

curl -s "https://gis.boem.gov/arcgis/rest/services/BOEM_BSEE/MMC_Layers/MapServer/15/query" \
  --data-urlencode "where=LEASE_STATUS_CD='PROD'" \
  --data-urlencode "outFields=LEASE_NUMBER,LEASE_STATUS_CD,LEASE_EFF_DATE,SALE_NUMBER,ROYALTY_RATE" \
  --data-urlencode "resultRecordCount=10" \
  --data-urlencode "f=json"

Bulk production download:

# Download all OGOR-A production data (pipe-delimited, ~1.3 MB compressed)
curl -sO "https://www.data.boem.gov/Production/Files/ogoradelimit.zip"

# Or a single year
curl -sO "https://www.data.boem.gov/Production/Files/ogora2024delimit.zip"

Step 3 — Parse Response

GIS query responses follow this structure:

{
  "displayFieldName": "API_Number",
  "fieldAliases": { "API_NUMBER": "API_NUMBER", ... },
  "geometryType": "esriGeometryPoint",
  "spatialReference": { "wkid": 4269 },
  "fields": [ { "name": "API_NUMBER", "type": "esriFieldTypeString", ... } ],
  "features": [
    {
      "attributes": {
        "API_NUMBER": "608104006000",
        "OPERATOR": "00250",
        "WELL_NAME": "  001",
        "STATUS_DESCRIPTION": "Permanently Abandoned",
        "DEPTH": "12500",
        "TYPE_CODE_DESC": "Development"
      },
      "geometry": { "x": -90.123, "y": 28.456 }
    }
  ]
}

Key parsing notes:

• Feature data is in features[].attributes
• Coordinates are in features[].geometry (NAD83, lon/lat)
• Date fields are millisecond epoch timestamps (divide by 1000 for Unix time)
• The OPERATOR field is a company number, not a name — cross-reference with Company bulk data for operator names

Step 4 — Produce Output

Format: Raw Data Table + Narrative

Present a markdown table of the most relevant rows (cap at ~20 rows for readability), then a narrative summary covering:

1. Current state — count of features, geographic scope
2. Key statistics — depth ranges, status breakdowns, temporal coverage
3. Geographic context — planning area, water depth zone if applicable
4. Data quality notes — operator codes vs names, date format caveats

Example output structure:

## OCS Wells — Central Gulf of Mexico (28-29N, 89-91W)

| API Number      | Operator | Well Name | Status              | Depth (ft) | Type        |
|-----------------|----------|-----------|---------------------|------------|-------------|
| 608104006000    | 00250    | 001       | Permanently Abandoned| 12,500     | Development |
| 608174002101    | 02481    | A001      | Completed           | 18,200     | Exploratory |
| ...             | ...      | ...       | ...                 | ...        | ...         |

**Summary:** Query returned 247 wells within the bounding box -91,28 to -89,29
in the central Gulf of Mexico. Of these, 68% are permanently abandoned, 22% are
completed, and 10% are in other statuses. Well depths range from 2,100 to
31,400 ft, with a median of 14,800 ft. The area spans portions of the Central
Planning Area (CPA) and includes both shelf and deepwater wells. Operator codes
shown — use the Company bulk download for operator name lookup.

Pagination

The ArcGIS REST API limits results per request (typically 1,000-2,000 features depending on server configuration). Use resultRecordCount and resultOffset to paginate:

import json
import urllib.request
import urllib.parse

offset = 0
page_size = 1000
all_features = []

while True:
    params = urllib.parse.urlencode({
        "where": "1=1",
        "outFields": "API_NUMBER,OPERATOR,STATUS",
        "resultRecordCount": str(page_size),
        "resultOffset": str(offset),
        "f": "json",
    })
    url = f"https://gis.boem.gov/arcgis/rest/services/BOEM_BSEE/MMC_Layers/MapServer/1/query?{params}"
    with urllib.request.urlopen(url) as resp:
        data = json.loads(resp.read())
    features = data.get("features", [])
    if not features:
        break
    all_features.extend(features)
    offset += len(features)
    if len(features) < page_size:
        break

print(f"Total features: {len(all_features)}")

Warn the user if a dataset exceeds ~10,000 features and suggest spatial or attribute filters to narrow results.

Error Handling

Regional GIS Services

In addition to the national MMC_Layers, BOEM provides regional MapServers with additional detail:

The GOA (Gulf of America) service includes additional layers such as Seismic Anomalies (layer 9) and Lease Points (layer 11).

OCS Planning Areas Reference

Geo Reference

Coordinate System: All national GIS layers use NAD83 (WKID 4269). Coordinates are geographic (longitude, latitude in decimal degrees).

Key geographic bounding boxes for common queries:

Caveats and Data Quality

• Operator codes, not names: The GIS well layer returns numeric operator codes (e.g., "00250"). Cross-reference with the Company bulk download for actual operator names.
• Date formats vary: GIS date fields are millisecond epoch timestamps. The SPUD_DATE field on wells is a string (MM/DD/YYYY). Bulk downloads use various date formats per file.
• GIS vs. official records: Per BOEM notice, GIS layers should not be used for legal or official purposes due to re-projection artifacts. The official records are in BOEM's internal database.
• Production data lag: OGOR-A production data typically lags 2-3 months behind current date. The most recent months may show incomplete volumes.
• Water depth not in GIS: The well GIS layer does not include water depth. For water depth analysis, use the Offshore Statistics bulk download or the borehole raw data files.
• Bulk download availability: Some bulk download URLs change periodically. If a URL returns an HTML page instead of a zip file, check the Raw Data page at https://www.data.boem.gov/Main/RawData.aspx for current links.

Implementation Notes

• Prefer bash_tool with curl for GIS queries — the REST API returns clean JSON that jq handles well
• Use python3 for bulk data processing — see references/python_example.py for a stdlib-only client with pagination, spatial queries, and downloads
• Spatial reference: Always NAD83 (WKID 4269) for national layers
• Record limits: Default server limit is ~2,000 features per request; paginate with resultOffset for larger result sets
• GeoJSON output: Add f=geojson instead of f=json for GeoJSON-format responses compatible with mapping tools
• BOEM Data Center updates: Well and lease data are updated frequently (weekly to monthly). Production data is updated quarterly.