Well Production API Reference

All endpoints are under https://api.oilpriceapi.com/v1/well-production. Authentication required on all endpoints — see Overview.

GET /v1/well-production

List and filter well production records across all covered states.

GET/v1/well-production

Parameters

Parameter	Type	Required	Description
`state_code`	string	No	Filter by state (e.g., `TX`, `NM`, `ND`)
`api_number`	string	No	Filter by 14-digit API well number
`from_date`	string	No	Start of date range (ISO date, e.g., `2023-01-01`)
`to_date`	string	No	End of date range (ISO date, e.g., `2023-12-31`)
`page`	integer	No	Page number (default: `1`)
`per_page`	integer	No	Records per page, max 100 (default: `25`)

Response

{
  "status": "success",
  "data": [
    {
      "api_number": "42461410190000",
      "state_code": "TX",
      "production_date": "2024-01-01",
      "production_year": 2024,
      "production_month": 1,
      "oil_bbl": 4821.5,
      "gas_mcf": 12450.0,
      "water_bbl": 9103.2,
      "boe": 6896.5,
      "operator_name": "Pioneer Natural Resources",
      "well_name": "SPRABERRY A 1H",
      "county": "Midland",
      "source": "texas_rrc",
      "granularity": "well"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 14382,
    "total_pages": 576
  }
}

Example

# Filter by state and date range
curl "https://api.oilpriceapi.com/v1/well-production?state_code=TX&from_date=2024-01-01&to_date=2024-03-31&per_page=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Filter by specific well
curl "https://api.oilpriceapi.com/v1/well-production?api_number=42461410190000" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /v1/well-production/states

List all states with available production data and coverage metadata.

GET/v1/well-production/states

Parameters

No parameters.

Response

{
  "status": "success",
  "data": [
    {
      "state_code": "TX",
      "state_name": "Texas",
      "well_count": 184320,
      "earliest_date": "2010-01-01",
      "latest_date": "2023-11-01",
      "last_updated_at": "2024-01-15T08:00:00Z",
      "share_of_us_wells": 0.43
    },
    {
      "state_code": "NM",
      "state_name": "New Mexico",
      "well_count": 51200,
      "earliest_date": "2010-01-01",
      "latest_date": "2023-11-01",
      "last_updated_at": "2024-01-15T08:00:00Z",
      "share_of_us_wells": 0.12
    }
  ]
}

Response Fields

Field	Type	Description
`state_code`	string	2-letter state code
`state_name`	string	Full state name
`well_count`	integer	Number of wells with production records
`earliest_date`	string	Earliest `production_date` in the dataset
`latest_date`	string	Most recent `production_date` available
`last_updated_at`	string	When this state's data was last ingested
`share_of_us_wells`	float	Approximate fraction of US onshore well count

Example

curl "https://api.oilpriceapi.com/v1/well-production/states" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /v1/well-production/by-state/{state_code}

Return all production records for wells in a given state, paginated.

GET/v1/well-production/by-state/{state_code}

Path Parameters

Parameter	Type	Required	Description
`state_code`	string	Yes	2-letter state code (e.g., `TX`)

Query Parameters

Parameter	Type	Required	Description
`from_date`	string	No	Start of date range (ISO date)
`to_date`	string	No	End of date range (ISO date)
`page`	integer	No	Page number (default: `1`)
`per_page`	integer	No	Records per page, max 100 (default: `25`)

Response

Same structure as GET /v1/well-production. Records are scoped to the specified state.

Example

# All New Mexico wells for 2023
curl "https://api.oilpriceapi.com/v1/well-production/by-state/NM?from_date=2023-01-01&to_date=2023-12-31" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /v1/well-production/by-api/{api_number}

Return the full production time series for a single well identified by its 14-digit API number.

GET/v1/well-production/by-api/{api_number}

Path Parameters

Parameter	Type	Required	Description
`api_number`	string	Yes	14-digit API well number (e.g., `42461410190000`)

Query Parameters

Parameter	Type	Required	Description
`from_date`	string	No	Start of date range (ISO date)
`to_date`	string	No	End of date range (ISO date)

Response

{
  "status": "success",
  "data": {
    "api_number": "42461410190000",
    "state_code": "TX",
    "well_name": "SPRABERRY A 1H",
    "operator_name": "Pioneer Natural Resources",
    "county": "Midland",
    "production": [
      {
        "production_date": "2024-01-01",
        "production_year": 2024,
        "production_month": 1,
        "oil_bbl": 4821.5,
        "gas_mcf": 12450.0,
        "water_bbl": 9103.2,
        "boe": 6896.5,
        "source": "texas_rrc",
        "granularity": "well"
      },
      {
        "production_date": "2023-12-01",
        "production_year": 2023,
        "production_month": 12,
        "oil_bbl": 5102.0,
        "gas_mcf": 13100.0,
        "water_bbl": 9450.0,
        "boe": 7285.3,
        "source": "texas_rrc",
        "granularity": "well"
      }
    ]
  }
}

Example

curl "https://api.oilpriceapi.com/v1/well-production/by-api/42461410190000" \
  -H "Authorization: Bearer YOUR_API_KEY"

# With date range
curl "https://api.oilpriceapi.com/v1/well-production/by-api/42461410190000?from_date=2022-01-01&to_date=2023-12-31" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /v1/well-production/top-producers

Return wells ranked by total production volume for a given period and volume type.

GET/v1/well-production/top-producers

Parameters

Parameter	Type	Required	Description
`state_code`	string	No	Scope to a specific state
`from_date`	string	No	Start of aggregation period (ISO date)
`to_date`	string	No	End of aggregation period (ISO date)
`volume_type`	string	No	Sort by: `oil_bbl`, `gas_mcf`, `water_bbl`, `boe` (default: `boe`)
`limit`	integer	No	Number of wells to return, max 100 (default: `25`)

Response

{
  "status": "success",
  "data": [
    {
      "rank": 1,
      "api_number": "42461410190000",
      "state_code": "TX",
      "well_name": "SPRABERRY A 1H",
      "operator_name": "Pioneer Natural Resources",
      "county": "Midland",
      "total_oil_bbl": 142380.0,
      "total_gas_mcf": 389100.0,
      "total_water_bbl": 274200.0,
      "total_boe": 207230.0,
      "period_months": 12
    }
  ],
  "meta": {
    "from_date": "2023-01-01",
    "to_date": "2023-12-31",
    "volume_type": "boe"
  }
}

Example

# Top 10 oil producers in Texas for 2023
curl "https://api.oilpriceapi.com/v1/well-production/top-producers?state_code=TX&from_date=2023-01-01&to_date=2023-12-31&volume_type=oil_bbl&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /v1/well-production/fields

Return production aggregated by oil/gas field.

GET/v1/well-production/fields

Parameters

Parameter	Type	Required	Description
`state_code`	string	No	Filter by state
`from_date`	string	No	Start of aggregation period (ISO date)
`to_date`	string	No	End of aggregation period (ISO date)
`page`	integer	No	Page number (default: `1`)
`per_page`	integer	No	Records per page, max 100 (default: `25`)

Response

{
  "status": "success",
  "data": [
    {
      "field_name": "Spraberry",
      "state_code": "TX",
      "well_count": 4820,
      "total_oil_bbl": 8420300.0,
      "total_gas_mcf": 22150000.0,
      "total_water_bbl": 15900000.0,
      "total_boe": 12113633.0,
      "period_months": 12
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 412,
    "total_pages": 17
  }
}

Response Fields

Field	Type	Description
`field_name`	string	Field name from state filing
`state_code`	string	State containing the field
`well_count`	integer	Number of wells with production in this period
`total_oil_bbl`	float	Aggregate oil production (barrels)
`total_gas_mcf`	float	Aggregate gas production (MCF)
`total_water_bbl`	float	Aggregate water production (barrels)
`total_boe`	float	Aggregate BOE
`period_months`	integer	Number of months in the aggregation window

Example

curl "https://api.oilpriceapi.com/v1/well-production/fields?state_code=TX&from_date=2023-01-01&to_date=2023-12-31" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /v1/well-production/operators

Return production aggregated by operator.

GET/v1/well-production/operators

Parameters

Parameter	Type	Required	Description
`state_code`	string	No	Filter by state
`from_date`	string	No	Start of aggregation period (ISO date)
`to_date`	string	No	End of aggregation period (ISO date)
`page`	integer	No	Page number (default: `1`)
`per_page`	integer	No	Records per page, max 100 (default: `25`)

Response

{
  "status": "success",
  "data": [
    {
      "operator_name": "Pioneer Natural Resources",
      "state_codes": ["TX"],
      "well_count": 2140,
      "total_oil_bbl": 3821500.0,
      "total_gas_mcf": 9840000.0,
      "total_water_bbl": 7230000.0,
      "total_boe": 5461000.0,
      "period_months": 12
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1840,
    "total_pages": 74
  }
}

Example

# All operators in New Mexico, most recent year
curl "https://api.oilpriceapi.com/v1/well-production/operators?state_code=NM&from_date=2023-01-01&to_date=2023-12-31" \
  -H "Authorization: Bearer YOUR_API_KEY"

Errors

Code	HTTP Status	Description
`INVALID_API_KEY`	401	Missing or invalid API key
`INVALID_STATE_CODE`	400	`state_code` is not a covered state
`INVALID_API_NUMBER`	400	`api_number` format is invalid or well not found
`INVALID_DATE_FORMAT`	400	Date parameter is not a valid ISO date
`INVALID_DATE_RANGE`	400	`from_date` is after `to_date`
`RATE_LIMIT_EXCEEDED`	429	Rate limit exceeded

Code Examples

import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://api.oilpriceapi.com/v1/well-production"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# Fetch time series for a single well
def get_well_history(api_number, from_date=None, to_date=None):
    params = {}
    if from_date:
        params["from_date"] = from_date
    if to_date:
        params["to_date"] = to_date
    r = requests.get(f"{BASE}/by-api/{api_number}", headers=HEADERS, params=params)
    r.raise_for_status()
    return r.json()["data"]

# Get top 10 BOE producers in Texas
def top_producers(state_code="TX", limit=10):
    params = {"state_code": state_code, "volume_type": "boe", "limit": limit}
    r = requests.get(f"{BASE}/top-producers", headers=HEADERS, params=params)
    r.raise_for_status()
    return r.json()["data"]

# Paginate all records for a state
def all_records_for_state(state_code):
    page = 1
    while True:
        r = requests.get(
            f"{BASE}/by-state/{state_code}",
            headers=HEADERS,
            params={"page": page, "per_page": 100}
        )
        r.raise_for_status()
        body = r.json()
        yield from body["data"]
        if page >= body["meta"]["total_pages"]:
            break
        page += 1

const API_KEY = "YOUR_API_KEY";
const BASE = "https://api.oilpriceapi.com/v1/well-production";
const HEADERS = { Authorization: `Bearer ${API_KEY}` };

// Fetch time series for a single well
async function getWellHistory(apiNumber, fromDate, toDate) {
  const params = new URLSearchParams();
  if (fromDate) params.set("from_date", fromDate);
  if (toDate) params.set("to_date", toDate);
  const res = await fetch(`${BASE}/by-api/${apiNumber}?${params}`, {
    headers: HEADERS,
  });
  if (!res.ok) throw new Error(`API error: ${res.status}`);
  return (await res.json()).data;
}

// Get top producers
async function topProducers(stateCode = "TX", volumeType = "boe", limit = 10) {
  const params = new URLSearchParams({
    state_code: stateCode,
    volume_type: volumeType,
    limit,
  });
  const res = await fetch(`${BASE}/top-producers?${params}`, {
    headers: HEADERS,
  });
  if (!res.ok) throw new Error(`API error: ${res.status}`);
  return (await res.json()).data;
}

Overview — coverage map, data quality notes, record schema
Well Permits — permit data upstream of production
Rig Counts — weekly rig activity