Data API
Open, read-only access to revenue data. No account, API key, or authentication is required.
Each row includes relevant reference data — the period, location, fund, and commodity labels are all available. The datasets are rebuilt after each monthly data load.
- MethodGET
- AuthNone
- FormatsJSON · CSV
Base URL
https://data.onrr.gov All paths below are relative to this base. The same datasets are also reachable at onrr.gov/data/<name>. GraphQL is not offered for these datasets — use REST; it's cached and simpler to support.
Endpoints
| Dataset | Endpoint | Measure |
|---|---|---|
| Monthly disbursements | /disbursements | amount (USD) |
| Revenue | /revenue | amount (USD) |
| Production | /production | volume |
| Federal sales | /federal-sales | sales value (USD) |
| Federal revenue by company | /federal-revenue-by-company | revenue (USD) |
Columns
Shared by disbursements, revenue, and production
| Column | Type | Description |
|---|---|---|
id | uuid | Unique row identifier. |
period_date | date | First day of the reporting month (YYYY-MM-DD). |
calendar_year | integer | Calendar year of the period. |
fiscal_year | integer | Federal fiscal year of the period. |
month_long | string | Full month name, e.g. "January". |
period_type | string | Reporting period: Monthly, Calendar Year, or Fiscal Year. |
state | string | Two-letter state code (blank for offshore). |
state_name | string | Full state name (blank for offshore). |
county | string | County, parish, or borough (blank for offshore). |
land_category | string | Onshore or Offshore. |
land_type | string | Land ownership / jurisdiction detail. |
commodity | string | Commodity that generated the record. |
product | string | Product detail within the commodity. |
unit | string | Unit for the measure (e.g. dollars, bbl, mcf). |
/disbursements also adds
| Column | Type | Description |
|---|---|---|
fund_type | string | Type of recipient fund. |
fund_recipient | string | Specific recipient of the disbursement. |
fund_source | string | Source fund of the disbursement. |
disbursement_type | string | Category of disbursement (e.g. GOMESA, 8(g)). |
revenue_type | string | Revenue category behind the disbursement. |
amount | numeric | Amount disbursed, USD (can be negative). |
/revenue also adds
| Column | Type | Description |
|---|---|---|
fund_type | string | Type of fund the revenue was recorded against. |
revenue_type | string | Revenue category (e.g. Royalties, Rents, Bonuses). |
fund_source | string | Source fund of the revenue. |
amount | numeric | Revenue amount, USD (can be negative). |
/production also adds
| Column | Type | Description |
|---|---|---|
mineral_lease_type | string | Mineral lease type. |
volume | bigint | Production volume, in the row's unit. |
/federal-sales (its own schema)
Federal sales is aggregated by calendar year and has a distinct set of columns — it does not share the columns above (no period_date, fiscal_year, or month).
| Column | Type | Description |
|---|---|---|
id | uuid | Unique row identifier. |
calendar_year | integer | Calendar year of the sales. |
commodity | string | Oil, Gas, NGL, or "Not Tied to a Commodity". |
land_class | string | Land ownership class (e.g. Federal). |
land_category | string | Onshore or Offshore. |
state_offshore_region | string | State name or offshore region. |
revenue_type | string | Revenue category. |
sales_volume | numeric | Sales volume. |
gas_volume | numeric | Gas volume. |
sales_value | numeric | Sales value, USD. |
royalty_value_prior_to_allowance | numeric | Royalty value prior to allowances (RVPA), USD. |
transportation_allowance | numeric | Transportation allowances (TA), USD. |
processing_allowance | numeric | Processing allowances (PA), USD. |
royalty_value_less_allowance | numeric | Royalty value less allowances (RVLA), USD. |
effective_royalty_rate | numeric | Effective royalty rate. |
Offshore rows have no state / county — check land_category / land_type instead.
/federal-revenue-by-company (its own schema)
Federal revenue by company is aggregated by calendar year and company, with its own flat set of columns (no period_date, fiscal_year, or month).
| Column | Type | Description |
|---|---|---|
id | uuid | Unique row identifier. |
calendar_year | integer | Calendar year of the revenue. |
corporate_name | string | Reporting company (corporate name). |
revenue_agency | string | Agency the revenue was reported to (e.g. Federal). |
revenue_type | string | Revenue category (e.g. Royalties, Rents, Bonus). |
commodity | string | Commodity that generated the revenue (Oil, Gas, NGL, Coal, …). |
revenue | numeric | Revenue amount, USD (can be negative). |
Querying
These endpoints accept the standard Directus REST query parameters:
| Parameter | Purpose | Example |
|---|---|---|
fields | Choose which columns to return (default: all). | fields=period_date,state_name,amount |
filter | Filter rows by column values. | filter[state_name][_eq]=Colorado |
sort | Order results; prefix - for descending. | sort=-period_date |
limit / offset | Page through results. | limit=100&offset=200 |
meta | Include the total match count. | meta=filter_count |
aggregate / groupBy | Server-side rollups (sum, count, avg, min, max). | aggregate[sum]=amount&groupBy[]=calendar_year |
export | Download the result as a file. | export=csv |
Common filter operators: _eq_neq_in_gte_lte_between_null_contains — combine them with _and / _or.
Examples
Each example is a live request against this environment — click Run to see the JSON.
Colorado disbursements in CY2024
Newest first, first 100 rows.
GET /disbursements?filter[state_name][_eq]=Colorado&filter[calendar_year][_eq]=2024&sort=-period_date&limit=100Total disbursed by recipient, FY2024
Server-side sum grouped by recipient.
GET /disbursements?aggregate[sum]=amount&groupBy[]=fund_recipient&filter[fiscal_year][_eq]=2024Oil production volume by state, CY2023
Sum of volume grouped by state.
GET /production?aggregate[sum]=volume&groupBy[]=state_name&filter[commodity][_eq]=Oil&filter[calendar_year][_eq]=2023Row count for a filter
No rows returned — just the total count.
GET /revenue?filter[commodity][_eq]=Gas&limit=0&meta=filter_countFederal oil sales value by year
Sum of sales value grouped by calendar year.
GET /federal-sales?aggregate[sum]=sales_value&groupBy[]=calendar_year&filter[commodity][_eq]=OilRevenue by company, CY2024
Sum of revenue grouped by company for one year.
GET /federal-revenue-by-company?aggregate[sum]=revenue&groupBy[]=corporate_name&filter[calendar_year][_eq]=2024Bulk downloads
For a full dataset or a large slice, use export=csv (or json / xml) rather than deep JSON pagination.
The entire disbursements dataset as CSV.
Download ↗GET /disbursements?export=csvA filtered, column-limited CSV slice.
Download ↗GET /disbursements?export=csv&filter[calendar_year][_eq]=2024&fields=period_date,state_name,fund_recipient,amountCaching & rate limits
- Responses are cached for about 30 minutes and refreshed automatically after each monthly data load. The
X-Cache-Statusresponse header showsHITorMISS. Keeping query shapes consistent improves cache hit rates. - The API is rate-limited to protect the service. Prefer a single filtered/aggregated query or a CSV export over many small paginated requests. Sustained abusive traffic may be throttled at the edge.
Notes
- Stability. This is a stable, versionless contract. Changes are additive — new columns or datasets may be added, and your existing requests keep working. Any breaking change (renaming or removing a column, changing a type) will be announced in advance with a deprecation window.
- Data reflects the most recent monthly publication;
period_dateis the first of the reporting month. Recent months may be preliminary. - Amounts are in USD; production
volumeunits are in theunitcolumn (e.g.bbl,mcf). Values can be negative (adjustments). - Field definitions for each dataset are also on its page under Data dictionary, e.g. Monthly disbursements.
Questions or feedback?
Whether you're building an integration, hit an unexpected result, or spotted a discrepancy in the data, the ONRR data team is glad to help. Email us at data@onrr.gov.
To help us respond quickly, include the dataset and the full request URL.