Export to a spreadsheet
Numbers checked against the live data on
To export, set your search and filters in factor search, click Export, choose CSV or XLSX, tick the credit box and click Export again. The file is the list on screen: every result in the list's order, each with the parent lines that place it, and every column of the open data files. Browsing and factor pages are free; the export needs a free account.
Before you start#
- An account. Without one, the dialog still opens and tells you what the file would hold, under Free with an account, with Create free account and Already have one?. Signing up brings you back to the same view, with your search and filters. It is the same free account that lifts the search allowance.
- Your search and filters. The export follows the text search and the filters in the Filters rail, including the Year filter. Find a factor shows how to set them.
- Your currency. When the list shows money in a currency you picked, the file restates spend factors in that currency too, and adds the two columns that turn every restated number back. See the currency pair.
The Columns menu only changes the screen. The file always carries every column, so hiding a column does not drop it from the file.
Export the view#
- In factor search, type your search and set the filters you need.
- Click Export above the list, or press E. The dialog Export this view opens.
- Check the summary under the title: the number of factors and of the values behind them.
- Under Format, choose CSV or XLSX.
- Tick "I accept the open data terms, and I will credit the publisher and open-climate.ai." The Export button stays off until you do. Read the full data terms opens them.
- Click Export. The dialog reads "Preparing your file…", then names the file it downloaded.
On a library page, the Browse factors section has the same Export button, already limited to that library.
What the file contains#
- The results, in the list's order. A search keeps its ranking, and a sort keeps its order. Each result is written with the parent lines that place it, as the list shows them, so a part never reaches the file without its total.
- Two kinds of line. A line the search and filters matched reads
matchin therolecolumn. A parent written only to place one readscontext, like the list's "shown for context" chip. Filterroleonmatchto drop them all at once. - Every column of the open data files, under the same names, then the list's own columns: the grouping, the currency pair when a currency is set, and the licence and citation of each line. What the columns mean lists them.
- The licence of each line. Every line carries its licence and how to cite it. The dialog says so: "Licence: source terms apply per row, and each line carries its licence and how to cite it." Keep those columns when you pass the file on: see Cite a factor.
An empty cell is a value the publisher does not give. It is not zero. Do not fill it with 0 when you add up the file. See value.
The sheets#
The XLSX has three sheets. The CSV is the first one alone.
- factors, the list itself, one line per result or context parent.
- columns, one row per column of factors: what it holds, which values a cell can take, and the docs page that defines it. The file explains itself, so a reader without these docs can still read it.
- notes, one fact per row: the selection you exported, how many factors and values the file holds out of how many the list has, how many lines and how many excluded, and whether the file was cut. Then how to credit it, the credit rule, the credit owed to every input behind an estimated line, and links to these docs.
What the columns mean#
The header row carries each column's machine name, not the label you saw on screen: Activity is activity_full, GWP is gwp_method_normalized, Derived is is_derived. They are the names the open data files and the reference tables use, so a file, a library download and a query read against each other. A yes-or-no column reads true or false.
The header runs in three blocks:
- The grouping:
group,roleanddepth. - The columns every open data file carries, from
library,slugandvalue_keytoapplies_to_year. Each one is described on Open data file columns, under its own name. Search these docs for a column's name to land on it. - The list's own columns:
original_unit_codeandfx_ratiowhen a currency is set, thenlicense_tier,license_code,license_urlandcitation.
The file's own columns sheet says the same, row by row.
Columns only a list export has#
The nine columns below are not in a library's open data file, because they describe a list rather than a library.
group#
The result's rank in the list on screen, 1 for the first. Every line of one result shares it: the matching part and the parents written to place it. Values: 1, 2, 3 and so on.
role#
match when the line passed the list's search and filters. context when it was written only to place a part that did, as the list's "shown for context" chip. Filter on match to keep the matches alone.
depth#
0 on the top-level factor, one more per level down. The path from the top-level factor to every matching part is written in full, so depth rebuilds the tree. Values: 0, 1, 2 and so on.
original_unit_code#
Only when a currency is set. The unit the publisher priced the factor in, before the value was restated into the file's currency, such as kg/EUR. Empty on a physical factor.
fx_ratio#
Only when a currency is set. What the publisher's value was multiplied by to restate it in the file's currency, at the value's own year. Divide by it to get the publisher's number back. Empty on a physical factor.
license_tier#
The licence family of the line's library edition: open or copyleft. A restricted library's lines are left out. See licence tier.
license_code#
The licence the publisher releases the edition under, as a code, such as cc-by-4.0. Licences and redistribution says what each one lets you do.
license_url#
Where that licence, or the publisher's terms, are published.
citation#
The credit and the citation in one line, to copy as it is: the library's credit line, then the address of the value itself. The source comes first, in the publisher's own words (or the publisher's name where it asks for none), then open-climate.ai with the library's page and the licence on what open-climate.ai added. For an ADEME line it reads "Source ADEME, Base Carbone v23.11. Normalised by open-climate.ai, https://open-climate.ai/factors/libraries/ademe/ (CC BY 4.0). https://open-climate.ai/factors/
Rows left out of the file#
A library whose licence does not let us republish its values has those values withheld: a dagger (†) in factor search, and no line in the file. Before you export, the dialog counts them for you, in the form "3 licence-restricted rows are not included in the file." The notes sheet repeats the count as excluded_lines.
What is left out follows the licence tier, not a list of names: open and copyleft libraries are served in full, restricted ones are searchable with their values withheld. The Licence filter in the rail tells you which tiers your view holds, and the Open data page marks a restricted library "Searchable on the portal · values withheld".
Large exports#
A file built from factor search stops at 1,000 lines. The dialog says so before you click: "This file stops at 1,000 lines, so only the first of these factors will be in it." The cut falls between two results, so no result loses its parents. After the download, the dialog says what the file holds, for example "This file holds 412 of 2,380 factors (1,105 of 6,020 values) in 1,000 lines", and the notes sheet carries truncated with a link to the open data files.
For more than that:
- A whole library is one download from its page: see Download the open data.
- A long list can be built over the API as a queued job, with no line limit. A queued file is built in the background: the dialog shows "Building: 120 of 2,380 factors.", then "Your file is ready." and a Download file link. The link lasts seven days; after that, run the export again.
The same export over the API#
Once you are signed in, the dialog also shows The same export over the API: the web address that produces the same file, with Copy URL. Give it to a developer who wants to fetch the file on a schedule; you do not need it to export.
Over the API, columns narrows the file to the columns it names, repeated one per parameter. It never adds a column or changes their order, and it always keeps group, role and slug, plus the currency pair when a currency is set. A name that is not a column of the file is refused, with "Unknown export columns", and a name given twice with "Duplicate export columns".
Keeping an export checkable#
A file you took keeps the numbers it was cut with, whatever factor search serves afterwards: that is what a refresh changes, and it is the point of exporting. Six months later, "has any of this changed?" is a question you answer by looking each line up again.
Every file carries what you look it up by: slug, the factor's permanent address, value_key, the value, and source_key, which changes when the served value does, whether from a new edition, a newly elected default or a correction. factor_value_url opens the value on the site. Pin a factor value to a release writes the comparison out, including the served numbers a source_key does not pin, such as price_index_ratio, and A source_key never changes is the promise it rests on.
Record what the file cannot hold: the edition of each library the view covers, which the Open data page prints on every card. The notes sheet keeps the selection you exported, and each line's citation links the exact value it holds. A factor page's citation carries no date, and the Dataset date in a citation copied from an earlier version of the page is not a stand-in for the edition: it was a fixed site date, not the data's. See dates, and the old Dataset date.
Other ways to take data away#
- One factor. A factor page has no export. Copy the value and its citation from the page instead, with Copy value and Cite: see Cite a factor.
- A whole library. The library page offers the publisher's edition as one file: see Download the open data.
Next#
- Open data file columns: every column the file shares with the open data files.
- Cite a factor: the credit lines your exported lines need.
- Download the open data: a whole library in one file.
- Choosing between similar factors: before you sum an exported list.
- Pin a factor value to a release: how to re-check an exported number after a new edition.