Changelog
Numbers checked against the live data on
What changed in the data model, in the served view open_ef.factors_flat, in the libraries and in these docs, newest first. Each month lists one entry per change. Where a column gains a successor, the entry names it and says what to read instead. How we change things is the standing policy behind that list: what gets an entry, and what notice you get before something you query moves.
How we change things#
This page is the record of a change, and for the served view it is the only one. There is no factor search version number to pin to: a release is a publisher's own edition label, so DESNZ at 2026 and ADEME at 23.11 advance on their own schedules, and neither moves when the shared model or the served view changes shape.
What gets an entry#
| surface | what is recorded | what moves it |
|---|---|---|
The served view open_ef.factors_flat |
Every column added or superseded, and every change to a closed code list | A rebuild of the view |
| The data model | New tables, fields and vocabularies, and rules that were tightened | A migration |
| The libraries | A library added, and mapping or classification work inside one | An ingest |
| These docs | A new page, or a reorganisation of the ones that exist | A docs release |
The numbers are deliberately not listed change by change. A new edition moves values under the same addresses, with no notice before the switch: What a refresh changes for you is the policy, a library's own Changelog section is where an edition is written up, and source_key is how you detect the move (Pin a factor value to a release).
The four kinds of change#
| kind | what it does to a query that works today | what to do |
|---|---|---|
| Addition | Nothing. A new column, a new code, a new table or library | Nothing, except handle codes you have not seen: a closed list can gain a member |
| New edition | The number moves, the address does not | Compare source_key against the one you stored |
| Supersession | Nothing. A column gains a clearer successor beside it, and the one you query keeps its name and its meaning | Move to the successor when it suits you: the entry names it |
| Retired code | The code stops being written. A filter on it matches nothing | Take the surviving codes from the view itself, not from a literal you wrote last year |
A column you query does not disappear under you, so the loud failure, column ... does not exist, is not the one to plan for. A retired code is the one that can cost you a number. WHERE system_boundary = 'well_to_wheel' does not error once that code is retired; it matches nothing, and an aggregate over nothing returns no total rather than a wrong one, which reads like a zero. September's boundary merges retired codes that way. So check that a code filter matched anything before you trust what it adds up to, and take the surviving codes from the view itself (SELECT DISTINCT system_boundary) or from System boundaries, not from a literal you wrote last year.
Slugs do not cover you here, and it is worth being exact about why. A slug is frozen when it is minted, so a renamed code leaves the old word standing inside it: the DESNZ diesel total still reads well_to_wheel in its slug while its system_boundary says well_to_use (Identifiers and stability). Nothing in the slug moved, so nothing needed an alias. emission_factor_alias answers the other question, a factor that was merged or re-keyed (A published slug always resolves).
The notice you get#
- Identifiers are promised, not merely recorded. A published slug always resolves, and a
source_keynever changes. Store those rather than a column list or a row's position. - Every entry from now on carries the date it landed and says where you meet the change: in the view, in factor search, in an export, or only in these docs. The launch list carries no dates because it is not a running log: it is the state of the model written in one batch on 17 September 2026, and every change in it landed on or before that day.
- This page is the record. A library's Versions and Changelog sections carry the same news for one edition, in more detail than an entry here has room for.
Where this sits against the guarantees#
Schema evolution is additive covers the names as well as the meanings. A column you query keeps its name, and it keeps meaning what it meant: a genuine change of meaning arrives as a new column beside the old one, and so does a better name. The old column stays served, unchanged, and an entry here says what supersedes it and from when. That is the whole of the word "deprecated" on this page.
The renames in the launch list are from before the site opened, and they are the shape this promise rules out from now on: September renamed the year-window pair on the served view, renamed the quality columns on the value record, of which two are served, and dropped the publisher's validity pair from it.
If you wrote queries against the view before then, check their names against the view as served. information_schema.columns, for table_schema = 'open_ef' and table_name = 'factors_flat', is that list. Today it holds applies_from_year; it holds neither start_year, the name that pair carried before September, nor publisher_valid_from, which is read from the value record instead (The publisher's validity window).
October 2026#
31 October#
- Matching API and MCP. Two route codes are renamed: the goods route is now
goods(it wasecoinvent) and the food route is nowfood(it wasagribalyse), because both routes draw on several libraries. This is a retired code.library_routeon every/v2row, in JSON and in the CSV, andef_libraryin the result the MCP tools read, serve the new codes for every job, including one matched before the rename, so a filter onlibrary_route = 'ecoinvent'there now matches nothing./v1does not change: its rows, in JSON and in the CSV, keep servingecoinventandagribalyse, for jobs matched before the rename and after it, and so doesef_libraryin the MCP result read with a partner key. Library codes do not change:ecoinventandagribalysestill name those libraries, in a job'slibrariesand in/v2/libraries.
27 October#
- Matching API. Every row, on
/v1and/v2, in JSON and in the CSV, now ends with ten fields that say where the line belongs in a GHG inventory.ghg_reporter_roleis the role the line is reported under (energy_buyer,fuel_user,purchaser,operator,traveller,freight_buyer_upstream,capital_purchaser,waste_generator), andghg_role_sourcesays which field answered it: the line's own item nature, the library route it was searched on, or the matched factor's category default.ghg_scope_slotsis the slot set the line claims under that role, an array ofscope_1,scope_2andscope_3_<category>codes, andghg_scope_stateisresolved,unsplitorunassigned.ghg_scope_legscuts an energy line into one leg per stage, each leg carrying its slot, its share of the line and its part of the line's total, so the Scope 2 leg and the upstream Scope 3.3 leg are reported apart; a leg never carries the child factor's own value.ghg_scope_unsplit_reasonandghg_scope_unplaced_reasonsay why a line was not split, or claims no slot at all, so nothing is quietly missing from a total.ghg_scope_2_instrumentislocation_based,market_based,residual_mixorunstated, per line, so a run that mixes instruments is visible before a Scope 2 figure is drawn from it.ghg_scope_category_default_roleis the role the matched factor's category would have assumed on its own, andghg_scope_store_gate_substituted_fromnames the factor served in its place when a food line was matched at the store gate rather than the consumer gate. A scope belongs to the reader, not to the factor: the same district-heat factor is Scope 1 to the operator and Scope 2 plus an upstream leg to the buyer, so the answer is resolved for each line and no factor carries one of its own. This is an addition: every column you read today is unchanged and stays where it was, and a job matched before these fields existed does not carry them.
21 October#
- API. Every published route now sits under
/v2, on one base URL:https://api.open-climate.ai, withhttps://dev.open-climate.aias the sandbox. The factor API moved from/factors/api/to/v2/factors,/v2/librariesand/v2/currencies, and the mapping API's uploads, jobs and results moved from/v1to/v2/uploadsand/v2/mapping-jobs. The queries and the bodies are the ones you know, under the new prefix, and inside/v2the rule is the one/v1had: we add, we do not remove. The API reference documents/v2only, so a link you kept to one of its operations changed with the path. - Still served.
/v1answers exactly as before for the integrations built on it; it is only gone from the reference. Its two rows routes,/v1/mapping-jobs/{job_id}/rowsand/rows.csv, now also send aDeprecationheader and aLinkheader naming their/v2successor, and nothing else about them changed./factors/api/is still served too, as the website explorer's own routes, and is not part of the contract: point your code at/v2. - Libraries.
/v1/librariesis replaced byGET /v2/libraries, the one list both APIs read. A library'sjob_searchsays whether a mapping job may be restricted to it, and itscodeis what a job'slibrariesnames./v1/librariesitself still answers as it did.
17 October#
- Matching API and MCP. Every row, on
/v1and/v2, in JSON and in the CSV, and in the result the MCP tools read, now ends with two fields that report how the factor's library was chosen.final_top_1_library_choice_reasonsays why the chosen factor beat another factor for the same activity, from another library, region or year, for exampleDESNZ over ADEME: lower expected error (k 1.15 vs k 1.31), and isnullwhen there was no other to weigh.final_top_1_value_outlieristruewhen the chosen factor's value sits far from the centre of its activity group in the result, by more than such factors usually differ (the measured spread where there is one, a default otherwise),falsewhen it does not, andnullwhen there was nothing to compare it with. This is an addition: every column you read today is unchanged and stays where it was, and a job matched before these fields existed does not carry them.
16 October#
- Matching API. The
/v2rows name each factor field the way the factor API names it, with no old name kept beside the new one.factor.idis nowfactor.slug, beside a newfactor.factor_api_url, and on the rowfinal_top_1_factor_idisfinal_top_1_slug, besidefinal_top_1_factor_api_url.value_kgco2e_per_unitisvalue_co2e_normalized, and the factor now says its GWP basis ingwp_method_normalized(ar4,ar5orar6) andgwp_horizon_years(100).attributionisattribution_text.edition,library_nameandfinal_top_1_library_nameare gone:libraryis the library code, and its name is onGET /factors/api/libraries.unit_codeis a lowercase unit code (eur,kg,kwh); a factor from your own database whose unit has no code at the same scale readsnull, and its own spelling stays on the partner entry.value_withheldis alwaystrueorfalse.license_tiertakes the factor API's values. Theopen_efblock holds only what the factor itself does not:final_top_1_open_ef_slugis gone,final_top_1_open_ef_releaseisfinal_top_1_open_ef_release_versionandfinal_top_1_open_ef_region_codeisfinal_top_1_region_code. In the CSV, eachcandidate_{rank}_*group carriesslugandvalue_co2e_normalizedin place offactor_idandvalue_kgco2e_per_unit. The/v1rows did not change.
15 October#
- Docs. The API reference documents the factor API under
/factors/api/beside the mapping endpoints, and Call the API is published: filter and page factor search, read one factor and its decomposition, ask about a library, and cache with anETag. Every route it documents takes a key. The/v2rows the 14 October entry announces are in the reference from today too: until now it left them out, so it showed no rows route at all. Nothing served changed. - Factor API. A keyed read of a factor now carries an
ETag. The list and one factor's detail answer a user key, an OAuth token or a partner key with one, as the decomposition, the library routes and the currency list already did, and a matchingIf-None-Matchis a304with no body. The validator covers the licence view you were served, not the credential you sent; a read your entitlement widens, and asaved=truepage, carry none (Cache and detect a change). The API reference now declares theETag, theIf-None-Matchheader and the304on every factor route. EveryETagyou hold changes once with this release, so expect one full re-read.
14 October#
- Matching API. A mapping job's rows have a second version,
/v2/mapping-jobs/{job_id}/rowsand/v2/mapping-jobs/{job_id}/rows.csv, and the reference now documents it in place of the first. It takes the same query and returns the same rows, with three differences. Each factor'sid, andfinal_top_1_factor_idon the row, is the factor's slug, the id the factor API answers to; a factor matched against your own factor database has no slug, and its id isnull. A partner key gets its own reference to each candidate incandidates[].external_references: the reference, its unit, the quantity in that unit, and whether it isresolved,needs_revieworunmapped. The first-ranked one is repeated in sevenfinal_top_1_external_*columns after all the others, and any other key gets an empty list and none of those columns. Inquantity_conversion_detail,ef_native_unitandquantity_in_ef_native_unitare namedfactor_unit_codeandquantity_in_factor_unit. - Behaviour change on
/v1. The/v1rows are still served, and on a job matched on the existing factor store they are byte for byte what they were; they are only gone from the reference. On a run on open_ef factors,/v1now names each factor by the partner's own reference, with the quantity and the value in that reference's unit.
9 October#
- Matching API. Each factor in
candidateson/v1/mapping-jobs/{job_id}/rowsgainsopen_ef: what the open_ef model knows about it, namely its slug andsource_key, its release, region, category and boundary preset, the unit and GWP basis of its value, its licence, and the crosswalk edge to the factor it stands in for. It isnullwhile matching runs on the existing factor store, so today a response gains that onenullkey and nothing else, and/rows.csvand the MCP read tool are unchanged. Once matching runs on open_ef factors, five columns follow all the others incolumns, in/rows.csvand in the MCP read tool:final_top_1_open_ef_slug,final_top_1_open_ef_source_key,final_top_1_open_ef_release,final_top_1_open_ef_region_codeandfinal_top_1_open_ef_boundary_preset. No published column moves position. On such a runlibrary_name, the spelling ofunit_codeand the keys ofreport_stats.by_libraryare the ones open_ef stores (EXIOBASE 3rather thanExiobase). The contract version is now 0.1.0. - Factor search and API. Every model that carries
value_withheld(the list and decomposition rows, a factor's detail, each matrix cell, part, input-output twin and value passport) gainsvalue_withheld_reason, which says why the number is held back.licence: the library's tier serves you metadata only, and an account entitled to that tier sees the number.pending: the value is withheld from every caller, entitled or not. The field is null exactly whenvalue_withheldis false, anddata_quality_normalizedis null on a pending value, which has no number to rate. - Behaviour change for entitled accounts. An account entitled to a restricted library never saw
value_withheldtrue before. It now does, with reasonpending, on ecoinvent factors, whose values are withheld from every caller: the factor is listed, searchable and described, with no number, and no account changes that. Branch on the reason, not on the account. - Libraries. Each library in the API's library list gains
values_pending, the values withheld from every caller, counted apart fromvalues_totalandvalues_served. It is 0 for every library that has none. A library's open data measures carryvalue_pendingthe same way. - Exports. No pending factor reaches an exported file: an export of a factor list serves open and copyleft libraries only, and it leaves out any factor without a number, whatever its library, counting it among the excluded rows.
- Mapping jobs and MCP. A mapped line whose factor is withheld (
licenceorpending) never carries the factor's number, on the chosen match or on any alternative. Apendingline keeps its quantity, its total is null with skip reasonvalue_pending, and it is left out of every sum, never counted as 0. The flatfinal_top_1_*projection of a job's rows gainsfinal_top_1_value_withheld_reasonright afterfinal_top_1_value_kgco2e_per_unit, so every column after it shifts one place in a CSV: read columns by name, not by position. It also gainsfinal_top_1_total_emissions_skip_reasonafterfinal_top_1_total_emissions_kgco2e. The downloadable result file keeps the columns it had: it shows such a line with an empty total and no skip-reason column, so read the reason from the rows or the CSV. A job'smessagescan carry a new code,rows_value_pending. In the MCP report,skip_reason_countsis now filled on every served result file, where it used to be empty, so therows_missing_quantitymessage now fires on jobs it missed before.
September 2026#
26 September#
- Served view.
boundary_scopekeeps its name and its meaning, the effective includes and excludes term by term, and now answers them for the factor rather than for its boundary. Each term takes the most specific answer there is: the factor's own record, then the library's method document for the factor's sub-category, its category or the whole library, then the boundary's default. A new column,boundary_scope_source, says which of those five answered each term (factor,library_sub_category,library_category,library,boundary). A term that cannot apply to what the factor measures, such as end of life on a kilowatt-hour of grid electricity, is left out. See What a boundary actually includes. - Retired codes.
variesis no longer served inboundary_scope: a term that no source settles for the factor readsnot_stated. The scope termemployee_travelis split intobusiness_travelandemployee_commuting, the GHG Protocol's Scope 3 categories 6 and 7, because an input-output factor counts business travel and never commuting. A filter on either old code now matches nothing. - Data model. Two new tables:
publisher_boundary_scope, one row per answer a library's method document gives, with the document's link, andcategory_subject_kind, which says what each category measures (a product, grid energy, a fuel, transport, a service, waste, direct emissions or land).boundary_scope_termgainssubject_kinds, the kinds each term applies to. - Factor search. The boundary hover in the results list and on a factor's page prints the factor's own map: each stage that applies reads included, excluded or not stated by the library, and says who answered it. The API's list rows and detail carry
boundary_scopeandboundary_scope_source. - Data quality. A new reason,
implausible_estimated_loss_share, marks an estimated electricity leg whose loss share, read from the publisher's own figures, is above 20 %. The value is ratedproblematic, so the view, factor search and the files leave it out; today that holds back 15 of ECCC's values (the ceiling). - Descriptions. Every estimated electricity and fuel leg, and every total summed over one, is now described in German as well as English and French, each language written from its own template with the same numbers rather than machine translated. The electricity totals, which carried no description, now say who added them, which legs they sum and what tier they take.
25 September#
- Fuels. Seven libraries that print only what burning a fuel emits now carry an estimated well-to-tank leg beside it,
upstream_fuel(extracting, refining and transporting the fuel), and awell_to_usetotal of the two: the U.S. EPA, ISPRA, Japan's Ministry of the Environment, New Zealand's MfE, MITERD, RVO and Statistics Finland. The leg is the published combustion value times a ratio of the two legs taken from another source, the nearest one that fits: the same country's own statistics, a regional supply-chain model, the EU average or the UK Government's factors. Each leg is markedis_estimated, capped at a tier set by where its ratio comes from, and described as added by open-climate.ai. Biofuels, waste-derived fuels, by-product gases, hydrogen and fuels no source describes get no leg, and no published value changes. See Estimated fuel legs. - Data quality. A new reason,
estimated_from_proxy_region, marks a leg whose ratio comes from another country's supply chain, capped atvery_low. The three other reasons for an estimate now describe a fuel as well as electricity. - Open data. The files carry
is_estimatedafteris_derived, andco2e_originafterco2e_basis.
24 September#
- Served view.
factors_flatgains three columns.is_estimatedmarks a number open-climate.ai estimated rather than read or summed from the publisher's own rows; every estimated factor is alsois_derived.co2e_originsays where the headline came from:source,computed_from_gases,summed_from_childrenorestimated_from_reference.grid_mix_originsays whether the publisher printed the electricity mix (source) or it was set by rule (assigned), and is empty wheregrid_mixis. In the API they areestimated,co2e_originandgrid_mix_origin. - Electricity. Where a library prints only the emissions of generating electricity, open-climate.ai adds the missing legs: the grid losses, the fuel chain, and the fuel chain of the losses, each marked
is_estimated, plus awell_to_usetotal per mix where the library prints none. A printed leg or total always stays. See Estimated electricity legs.
22 September#
- Docs. The site is cut by the reader's job rather than by whether they write SQL: five sections, and a badge that marks the pages asking you to write SQL, HTTP or code, so a page with no badge needs none. URLs move with it:
/docs/developers/becomes/docs/guides/quickstart/. New pages cover the standardisation story, editions, reporting, geography and waste routes. Nothing in the data or onfactors_flatchanged.
21 September#
- Docs.
/factors/open-data/gets a page, covering the credit dialog every download goes through and when there is no download at all. Facts that move, such as the search allowance and factor search's default columns, each get one owning page and are linked from the rest rather than restated.
At launch, 17 September#
The state of the shared model, the served view and the libraries on the day the site opened, written in one batch rather than logged as it happened.
- Docs. The docs site opens on 17 September, with a track for using factors, a track for building on the data, and shared methodology pages and a glossary.
- Licences. Every licence code now answers five questions: using the data for your own footprint, publishing results, sharing it with customers, embedding it in a product, and modifying or combining it. Each answer is yes, yes if, ask, unclear or no. See Licences.
- Libraries. Each library is described as a generalist or a specialist, from how its factors spread across categories, and the checks run on its data are recorded so a library page can show them.
- Units. Every unit code has a display name that can be translated.
- Years. You can filter on several accounting years at once. A factor is kept if any chosen year is inside its window, and shows the value for the latest one. See Applicable years.
- EPDs.
is_epdmarks factors that come from an Environmental Product Declaration, andhas_suppliermarks factors that name a supplier. A generic dataset no longer names a supplier. - Decomposition. Every row names the top of its tree in
root_slug. - Boundaries. EN 15804 declarations get a whole-declaration boundary,
epd_total, and module D (benefits beyond the system boundary) is reported beside the declaration withparent_relationreported_beside_parent, never summed into it. The EN 15804 boundaries also state what the standard excludes. - Boundaries.
well_to_usenow covers both a fuel's full cycle and delivered energy such as grid electricity, where they were two boundaries before. The two full life-cycle energy boundaries merge intoenergy_lifecycle. - Boundaries. Each boundary states which life-cycle phases it covers.
- Publishers. Every publisher declares a short name, a home region, a kind and tags.
- Licences.
license_urlandlicense_noticeare served besideattribution_text, which now holds only the credit line to reproduce. - Vocabularies.
license_tieranddata_typeaccept only their listed values.data_typehas three:specific,averageandgeneric. - Data quality. The tier for a rated value is read from the cut-offs stored with each rating scheme. A zero from a green electricity contract is no longer marked down for being zero. See Data quality.
- Boundaries. Electricity transmission and distribution losses get their own upstream boundary,
transmission_distribution_upstream. - Waste. Where a publisher gives several treatment routes for one waste stream, one is elected the default for "route unknown", served as
is_route_default. - Years. The window columns are now
applies_from_yearandapplies_to_year. The publisher's own validity dates are no longer on the served view; read them from the value record. See The publisher's validity window. - Units. Gas volumes are stored in litres, with the publisher's reference conditions.
- Regions.
region_is_publisher_defaultsays when a region was filled in from the library's default rather than stated on the row. - Data quality. The quality columns are named for whose quality they are:
data_quality_rating_nativeanddata_quality_scheme_nativefor the publisher's,data_quality_normalizedanddata_quality_reason_normalizedfor ours. The API's quality filter and field use the same name. - Spend factors. A spend factor is re-priced to each accounting year in its own currency, rather than in its economy's. See Currency year.
- Years. A physical value carries its whole window of accounting years on one row, with open ends, instead of one row per year; a spend value keeps one row per year. The newest row is flagged
is_latest_activity_year. - GWP. Every value and every gas leg carries a normalised version on AR6 GWP100. A value with no exact conversion keeps the publisher's number there and is labelled
unconvertedingwp_normalization_basis. See GWP values. - Categories. The served view carries our category axis,
categoryandsub_category, one column per gas leg, andis_top_parentfor counting without double counting. - Spend factors. Monetary factors are deflated to each accounting year from price indices of their economy.
- Boundaries. The EN 15804 modules are grouped as life-cycle stages of an asset, and
cradle_to_grave_embodiedcovers the embodied whole life: modules A1 to A5 and C1 to C4, without the use phase. - ADEME. A fuel printed on two energy bases is one factor, not two. Avoided-emission credits get their own boundary,
avoided_credit. Factors are no longer given a data quality rating ADEME did not score. - AGRIBALYSE. Stage-by-stage slices are filed under the total they widen.
- DESNZ. Transmission and distribution losses are added into a delivered-electricity total. Sea freight is recorded as global, not as a UK factor.
- ÖKOBAUDAT. Each declaration gets a full tree with cradle-to-grave and whole-declaration totals and module D beside them. A process dataset carries the boundary it prices.
- Data type. Values a supplier discloses, or that represent a group, are typed
averagerather thanspecific.
August 2026#
- Years and methods. The served view carries every year and every method of a factor. The default row is flagged with
is_default_indicatorand the latest year with a flag, rather than everything else being filtered out. - Identifiers.
source_keyis served, so a value can be traced to its source line. See Trace a served value. - MITECO. The default method of a factor is no longer used to pick its year.
- Decomposition.
is_derivedmarks a total assembled from parts the publisher printed separately. See Glossary: derived total. - Validity. The publisher's own validity window is exposed.
- DESNZ. Each factor records the edition it came from.
- Decomposition.
parent_relationis closed tosums_to_parentandcontained_by_parent. - AGRIBALYSE. Every stage boundary above the farm gate states that land-use change is inside it, as the farm gate does.
- Boundaries. EN 15804 modules A1, A2 and A3 add up exactly to cradle-to-gate.
- Categories. One category axis, the same for every library, classifies every factor. See Glossary: category.
- Classifications. The BEA 2017 commodity code becomes a standard classification on both USEEIO and Open CEDA, so the two libraries can be joined on it.
- Licences.
license_tierandlicense_codeare served on every row. See Licences.
July 2026#
- GWP. Each value gets an AR6 version beside the one the publisher printed.
- Suppliers. A supplier registry names the counterparty behind supplier-specific electricity (MITECO) and EPDs (ÖKOBAUDAT). A supplier is a description of the factor, never part of its identifier.
- Fit. Four additions help you judge whether a factor fits: its classification in the publisher's and standard trees with native codes, the publisher's descriptive text, what its boundary includes, and what a publisher's quality rating means.
- Serving. One default value per factor, a typed price basis and currency year for spend factors, and change tracking on every value.
- Identity. A factor's identity is anchored in its source. Improving a region, unit or boundary mapping never changes a factor's identifier. See Identifiers and stability.
- Ingest. Every library loads through the same framework, one adapter per library.