Library · Record

API & data dictionary

Every column of every export, with its unit and meaning, and how to reach the same data through the API. The dictionary is read from the API, and a test holds it to the headers the exports actually write.

The API

A REST API under one prefix. The method, the guide and this dictionary are public; facility-resolved data need an account or an API key, and row-level security decides the rows.

Base: https://emisource.ai/api/v1
Description: OpenAPI at https://emisource.ai/api/v1/openapi.json, browsable at /docs under the same prefix.
Authentication: A bearer token from signing in, or an organisation's API key in the Authorization header. Keys are issued and revoked by the organisation's administrator.
Errors: Problem details (RFC 9457) with a stable code: NO_DATA_TIER and AUTH_REQUIRED are answers about entitlement, not faults, and are not worth retrying.
Exports: GET /exports/{dataset}.csv with from, to, facility_id and include_history. Each export is recorded with its row count and the SHA-256 of the file.

Every export begins with one comment line naming the dataset, the generation time (UTC), the engine version and the role of the person exporting; a demo deployment adds DEMO DATA. The second line is the header. Each export is recorded with its row count and the SHA-256 of the file, returned in the X-Content-SHA256 header.

Source-resolved emissions · inventory.csv

One row per facility, month and emission source.

Column	Unit	Meaning
facility_code	—	The facility's code. Demo deployments use anonymised codes.
period	date	First day of the month the row covers.
source	—	Emission source key, one of the twelve in Methods → Estimation model.
ch4_t	t CH₄	Methane emitted, tonnes.
co2_t	t CO₂	Carbon dioxide emitted, tonnes.
co2e_t	t CO₂e	CO₂-equivalent, tonnes, with methane at GWP₁₀₀ 29.8 (IPCC AR6).
tier	—	IPCC tier of the estimate (1, 2 or 3); blank where a tier does not apply to the row.
basis	—	How the value was arrived at: measured, calculated, modelled or estimated (national rows: ensemble mean or derived). Measured and calculated are different claims.
is_current	—	True for the version in force. A resubmission or recompute supersedes a row; the old row stays, with is_current false, so a past figure can be reconstructed.
engine_version	—	Version of the calculation engine that produced the row.
lineage_id	—	Identifier of the lineage record: the inputs, factor set, seed and engine behind the figure. Open it at /app/regulator/lineage/id/<lineage_id>.

Carbon and methane intensity · intensity.csv

One row per facility and month.

Column	Unit	Meaning
facility_code	—	The facility's code. Demo deployments use anonymised codes.
period	date	First day of the month.
ci_gco2e_per_mj	g CO₂e/MJ	Upstream carbon intensity per megajoule of saleable energy.
mi_produced_pct	%	Methane intensity: methane emitted as a share of gas produced.
mi_marketed_pct	%	Methane intensity against gas marketed; blank where no gas was marketed.
saleable_energy_mj	MJ	Energy in the oil and gas sold, the intensity denominator.
tier	—	IPCC tier of the estimate (1, 2 or 3); blank where a tier does not apply to the row.
basis	—	How the value was arrived at: measured, calculated, modelled or estimated (national rows: ensemble mean or derived). Measured and calculated are different claims.
is_current	—	True for the version in force. A resubmission or recompute supersedes a row; the old row stays, with is_current false, so a past figure can be reconstructed.
engine_version	—	Version of the calculation engine that produced the row.
lineage_id	—	Identifier of the lineage record: the inputs, factor set, seed and engine behind the figure. Open it at /app/regulator/lineage/id/<lineage_id>.

National aggregates · national.csv

One row per metric and period.

Column	Unit	Meaning
metric	—	The aggregate, for example total CO₂e or methane.
covers_from	date	First month included in the aggregate.
period	date	Last month included.
value	unit column	The figure: the Monte-Carlo ensemble mean where p2_5 and p97_5 are given.
p2_5	unit column	Lower bound of the 95% interval from the ensemble.
p97_5	unit column	Upper bound of the 95% interval from the ensemble.
unit	—	Unit of value, p2_5 and p97_5.
tier	—	IPCC tier of the estimate (1, 2 or 3); blank where a tier does not apply to the row.
basis	—	How the value was arrived at: measured, calculated, modelled or estimated (national rows: ensemble mean or derived). Measured and calculated are different claims.
is_current	—	True for the version in force. A resubmission or recompute supersedes a row; the old row stays, with is_current false, so a past figure can be reconstructed.
engine_version	—	Version of the calculation engine that produced the row.
lineage_id	—	Identifier of the lineage record: the inputs, factor set, seed and engine behind the figure. Open it at /app/regulator/lineage/id/<lineage_id>.

Monthly activity returns · returns.csv

One row per facility and month, as accepted.

Column	Unit	Meaning
facility_code	—	The facility's code. Demo deployments use anonymised codes.
period	date	First day of the month.
days_on_production	days	Days the facility produced in the month.
oil_bbl	bbl	Oil produced.
gas_produced_mscf	Mscf	Associated gas produced.
gas_flared_mscf	Mscf	Gas sent to flare.
fuel_gas_mscf	Mscf	Gas burned as fuel on the facility.
gas_export_mscf	Mscf	Gas exported.
gas_reinjection_mscf	Mscf	Gas reinjected.
produced_water_bbl	bbl	Produced water; blank where not reported.
tier	—	IPCC tier of the estimate (1, 2 or 3); blank where a tier does not apply to the row.
basis	—	How the value was arrived at: measured, calculated, modelled or estimated (national rows: ensemble mean or derived). Measured and calculated are different claims.
is_current	—	True for the version in force. A resubmission or recompute supersedes a row; the old row stays, with is_current false, so a past figure can be reconstructed.
submission_id	—	The operator submission the row came from; blank for the historical record.
lineage_id	—	Identifier of the lineage record: the inputs, factor set, seed and engine behind the figure. Open it at /app/regulator/lineage/id/<lineage_id>.

Data-quality flags · flags.csv

One row per flag raised by a rule or an AI screening module.

Column	Unit	Meaning
facility_code	—	The facility's code. Demo deployments use anonymised codes.
period	date	Month the flag concerns; blank for a whole-submission flag.
rule_key	—	The rule or AI check that raised it.
severity	—	info, warn or error.
status	—	open, investigating, explained, confirmed or dismissed — the reviewer's decision.
raised_by	—	rule or ai. An AI flag is a question for a reviewer, not a finding.
model_version	—	Version of the AI module, for AI flags.
priority	—	Triage priority, 0 to 1, for AI flags.
priority_basis	—	What the priority rests on.
message	—	The flag as shown to the reviewer.
resolution_note	—	The reviewer's note on the decision.
submission_id	—	The submission flagged, where there is one.
tier	—	IPCC tier of the estimate (1, 2 or 3); blank where a tier does not apply to the row.
basis	—	How the value was arrived at: measured, calculated, modelled or estimated (national rows: ensemble mean or derived). Measured and calculated are different claims.
is_current	—	True for the version in force. A resubmission or recompute supersedes a row; the old row stays, with is_current false, so a past figure can be reconstructed.
lineage_id	—	Identifier of the lineage record: the inputs, factor set, seed and engine behind the figure. Open it at /app/regulator/lineage/id/<lineage_id>.

Submissions · submissions.csv

One row per operator submission, including superseded ones.

Column	Unit	Meaning
facility_code	—	The facility's code. Demo deployments use anonymised codes.
period_start	date	First month the submission covers.
period_end	date	Last month the submission covers.
status	—	draft, submitted, validating, needs_fix, validated, accepted, rejected or superseded.
channel	—	How it arrived: portal_form (the web form) or bulk_upload (a file, through the portal or the API).
submitted_at	timestamp	When it was filed (UTC).
reviewed_at	timestamp	When a reviewer accepted or rejected it.
review_note	—	The reviewer's note; required for a rejection.
file_sha256	—	SHA-256 of the file as filed.
superseded_by	—	The submission that replaced it, if any.
tier	—	IPCC tier of the estimate (1, 2 or 3); blank where a tier does not apply to the row.
basis	—	How the value was arrived at: measured, calculated, modelled or estimated (national rows: ensemble mean or derived). Measured and calculated are different claims.
is_current	—	True for the version in force. A resubmission or recompute supersedes a row; the old row stays, with is_current false, so a past figure can be reconstructed.
lineage_id	—	Identifier of the lineage record: the inputs, factor set, seed and engine behind the figure. Open it at /app/regulator/lineage/id/<lineage_id>.