# CERN Open Data

> Search the datasets, software and documentation that CERN's experiments (CMS, ATLAS, LHCb, ALICE and others) release on the CERN Open Data portal: find records by experiment, type, year, collision energy or file format, read one with its files and download links, count them, look up physics terms, and run a workflow when new ones are published. No account or API key required.

App · 5 actions. Web page: https://docs.lodol.com/docs/integrations/cern-open-data

## Actions

### Count records

Count the records that match your filters, grouped by experiment, record type, year, collision energy, file type or another field, with each group's share. Use it for how much each experiment has released, or the years and formats a search covers.

**Inputs**

- Group by (`group_by`, text): What to count the records by. Defaults to experiment. One of: `experiment`, `type` (Record type), `subtype` (Record sub-type), `year`, `collision_energy` (Collision energy), `collision_type` (Collision type), `file_type` (File type), `availability`, `number_of_events` (Number of events). Default: `experiment`.
- Search text (`query`, text): Words to look for in the records' titles, abstracts and other details, e.g. dimuon. AND and OR work, a minus sign before a word leaves it out, quotes find an exact phrase, and a field can be named, e.g. doi:10.7483/OPENDATA.CMS.CB8H.MFFA. Leave blank for every record.
- Experiments (`experiments`, list): Only records from these experiments, e.g. CMS or ATLAS. Leave blank for every experiment.
- Record types (`record_types`, list): Only these kinds of record, or a kind's sub-type, e.g. Dataset or Dataset > Simulated. Leave blank for every kind, documentation and glossary terms included.
- From year (`year_from`, number): Only records whose data was taken (or that were made) in this year or later, e.g. 2010. From 1900 to 2100.
- To year (`year_to`, number): Only records whose data was taken (or that were made) in this year or earlier, e.g. 2012. From 1900 to 2100.
- Collision energies (`collision_energies`, list): Only data from collisions at these energies, e.g. 13TeV or 7TeV. Leave blank for every energy.
- Collision types (`collision_types`, list): Only data from these collisions: pp for protons, PbPb for lead ions, e+e- for electrons and positrons, and so on.
- File types (`file_types`, list): Only records with files in these formats, e.g. csv, root or nanoaod. Leave blank for every format.

**Outputs**

- `count` (number): How many groups are listed.
- `group_by` (text): What the records were counted by.
- `groups` (list): The groups, largest first (years and event counts in order).
- `others_count` (number): Records in values the portal leaves out: it lists at most 10 values of some fields, A to Z. Narrow the filters to see the rest.
- `summary` (text): One line with the total and the largest group.
- `total` (number): How many records match in all.

**Example output**

```json
{
  "count": 4,
  "group_by": "file_type",
  "groups": [
    {
      "count": 4,
      "label": "csv",
      "percent": 100.0,
      "value": "csv"
    },
    {
      "count": 3,
      "label": "ig",
      "percent": 75.0,
      "value": "ig"
    },
    {
      "count": 2,
      "label": "json",
      "percent": 50.0,
      "value": "json"
    },
    {
      "count": 1,
      "label": "xls",
      "percent": 25.0,
      "value": "xls"
    }
  ],
  "others_count": 0,
  "summary": "4 records across 4 file types; the most are csv (4, 100.0%).",
  "total": 4
}
```

### Get record

Get one record by its number, its DOI or the address of its page: its title, abstract, authors, collaboration, dates, licence and DOI, its files with their sizes, checksums and download links, its file indexes, and the records it was derived from. Works for documentation and news pages too.

**Inputs**

- Record (`record`, text, required): The record's number, e.g. 700, its DOI, e.g. 10.7483/OPENDATA.CMS.CB8H.MFFA, or the address of its page on opendata.cern.ch. A documentation page's name or address works too.

**Outputs**

- `abstract` (text): What it is, in full, as plain text.
- `accelerator` (text): The accelerator, e.g. 'CERN-LHC'.
- `authors` (list): The people who prepared it.
- `availability` (text): Whether its files can be downloaded now: 'online', 'partial' (some are on tape) or 'ondemand'.
- `categories` (list): The physics topics it is filed under.
- `collaboration` (text): The collaboration that released it, e.g. 'CMS Collaboration'.
- `collision_energy` (text): The collision energy of its data, e.g. '13TeV'.
- `collision_type` (text): What collided: 'pp' (protons), 'PbPb' (lead ions), 'e+e-' and so on.
- `date_published` (text): When the portal published it: a year, or a date (YYYY-MM-DD).
- `date_reprocessed` (text): The year its data was last reprocessed, when given.
- `doi` (text): Its DOI (permanent identifier), e.g. '10.7483/OPENDATA.CMS.CB8H.MFFA'.
- `doi_url` (text): Its DOI as a link, e.g. 'https://doi.org/10.7483/...'.
- `experiments` (list): The experiments it comes from, e.g. CMS or ATLAS.
- `file_count` (number): How many files the record lists itself.
- `file_formats` (list): The formats of its files, e.g. root, csv or nanoaod.
- `file_index_count` (number): How many file indexes it has.
- `file_indexes` (list): The file indexes listing the rest of its files: big datasets list their files this way. List record files lists what is in them.
- `files` (list): The files the record lists itself.
- `id` (text): The portal's id for it: a number such as '700' or a name such as 'cms-93965' for a record, the page's name for documentation, the term for a glossary entry.
- `keywords` (list): Its keywords.
- `kind` (text): What it is: 'record' (data, software and the like), 'documentation' (a guide or news page) or 'glossary' (a term).
- `licence` (text): Its licence, e.g. 'CC0-1.0' (no restrictions).
- `methodology` (text): How the data was selected or made, as plain text.
- `number_of_events` (number): How many collision events its data holds.
- `number_of_files` (number): How many files it has, when the portal says.
- `related` (list): Records it is related to, such as the dataset it was derived from.
- `run_periods` (list): The run periods its data covers.
- `size_bytes` (number): The size of all its files, in bytes, when the portal says.
- `subtypes` (list): The kinds of that type it is, e.g. Collision, Simulated or Derived for a dataset.
- `summary` (text): One line naming it, its experiments and how many files it has.
- `text` (text): The page's text (Markdown), for a documentation or news page.
- `title` (text): Its title; for a glossary entry, the term.
- `type` (text): The record type: Dataset, Software, Documentation, Environment, Supplementaries, News or Glossary.
- `url` (text): Its page on opendata.cern.ch.
- `years` (list): The years its data was taken or it was made.

**Example output**

```json
{
  "abstract": "This document contains 100k dimuon events selected from the Mu dataset from Run2010B. Each line corresponds to an event. The main file contains all 100k events. Files with an underscore contain 10k events each.\nThese data were selected from the Mu primary dataset. The selection criteria may be different from that used in CMS physics results. They are not suitable for a full physics analysis.",
  "accelerator": "CERN-LHC",
  "authors": [
    {
      "affiliation": null,
      "name": "McCauley, Thomas",
      "orcid": "0000-0001-6589-8286"
    }
  ],
  "availability": "online",
  "categories": [],
  "collaboration": null,
  "collision_energy": null,
  "collision_type": null,
  "date_published": "2014",
  "date_reprocessed": null,
  "doi": "10.7483/OPENDATA.CMS.CB8H.MFFA",
  "doi_url": "https://doi.org/10.7483/OPENDATA.CMS.CB8H.MFFA",
  "experiments": [
    "CMS"
  ],
  "file_count": 2,
  "file_formats": [
    "csv"
  ],
  "file_index_count": 0,
  "file_indexes": [],
  "files": [
    {
      "availability": "online",
      "checksum": "adler32:fcc5312a",
      "download_url": "https://opendata.cern.ch/eos/opendata/cms/Run2010B/Mu/CSV/Apr21ReReco-v1/MuRun2010B_0.csv",
      "index": null,
      "name": "MuRun2010B_0.csv",
      "size_bytes": 1515458,
      "uri": "root://eospublic.cern.ch//eos/opendata/cms/Run2010B/Mu/CSV/Apr21ReReco-v1/MuRun2010B_0.csv"
    },
    {
      "availability": "online",
      "checksum": "adler32:fb01b157",
      "download_url": "https://opendata.cern.ch/eos/opendata/cms/Run2010B/Mu/CSV/Apr21ReReco-v1/MuRun2010B_1.csv",
      "index": null,
      "name": "MuRun2010B_1.csv",
      "size_bytes": 1519070,
      "uri": "root://eospublic.cern.ch//eos/opendata/cms/Run2010B/Mu/CSV/Apr21ReReco-v1/MuRun2010B_1.csv"
    }
  ],
  "id": "700",
  "keywords": [
    "education"
  ],
  "kind": "record",
  "licence": null,
  "methodology": "The events in this derived dataset were selected because of the presence of precisely two muons with invariant mass between 2-110 GeV, one of which is a high-quality \"global\" muon. More information on the selections applied for the Mu primary dataset can be found there.",
  "number_of_events": 100000,
  "number_of_files": null,
  "related": [
    {
      "doi": "10.7483/OPENDATA.CMS.B8MR.C4A2",
      "id": "14",
      "relation": "isChildOf",
      "title": "/Mu/Run2010B-Apr21ReReco-v1/AOD"
    }
  ],
  "run_periods": [
    "Run2010B"
  ],
  "size_bytes": null,
  "subtypes": [
    "Derived"
  ],
  "summary": "Dataset 700: Dimuon event information derived from the Run2010B public Mu dataset (CMS). 2 files.",
  "text": null,
  "title": "Dimuon event information derived from the Run2010B public Mu dataset",
  "type": "Dataset",
  "url": "https://opendata.cern.ch/record/700",
  "years": [
    "2010"
  ]
}
```

### List record files

List a record's files a page at a time, with each one's size, checksum and download link, including the files its file indexes list (big datasets hold thousands this way). Narrow it to one file index or one file type.

**Inputs**

- Record (`record`, text, required): The record's number, e.g. 700, its DOI, e.g. 10.7483/OPENDATA.CMS.CB8H.MFFA, or the address of its page on opendata.cern.ch. A documentation page's name or address works too.
- File index (`file_index`, text): Only the files one file index lists, by the index's name from Get record. Leave blank for all the record's files.
- File type (`file_type`, text): Only files whose name ends in this, e.g. csv or root. Leave blank for every file.
- Files per page (`page_size`, number): How many files to return, from 1 to 1000. Defaults to 100. From 1 to 1000. Default: `100`.
- Page (`page`, number): Which page to return, from 1. From 1 to 100000. Default: `1`.

**Outputs**

- `count` (number): How many files this page holds.
- `files` (list): The files on this page.
- `has_more` (true/false): True when there is a further page.
- `next_page` (number): The next page's number, or null on the last page.
- `page` (number): The page returned, from 1.
- `page_size` (number): Files per page.
- `record_id` (text): The record's id.
- `summary` (text): One line saying how many files match and which are shown.
- `title` (text): The record's title.
- `total` (number): How many files match in all.
- `total_size_bytes` (number): The size of all the files that match, in bytes.

**Example output**

```json
{
  "count": 2,
  "files": [
    {
      "availability": "online",
      "checksum": "adler32:fcc5312a",
      "download_url": "https://opendata.cern.ch/eos/opendata/cms/Run2010B/Mu/CSV/Apr21ReReco-v1/MuRun2010B_0.csv",
      "index": null,
      "name": "MuRun2010B_0.csv",
      "size_bytes": 1515458,
      "uri": "root://eospublic.cern.ch//eos/opendata/cms/Run2010B/Mu/CSV/Apr21ReReco-v1/MuRun2010B_0.csv"
    },
    {
      "availability": "online",
      "checksum": "adler32:fb01b157",
      "download_url": "https://opendata.cern.ch/eos/opendata/cms/Run2010B/Mu/CSV/Apr21ReReco-v1/MuRun2010B_1.csv",
      "index": null,
      "name": "MuRun2010B_1.csv",
      "size_bytes": 1519070,
      "uri": "root://eospublic.cern.ch//eos/opendata/cms/Run2010B/Mu/CSV/Apr21ReReco-v1/MuRun2010B_1.csv"
    }
  ],
  "has_more": false,
  "next_page": null,
  "page": 1,
  "page_size": 2,
  "record_id": "700",
  "summary": "Dataset 700 has 2 csv files (3.0 MB); showing 1 to 2.",
  "title": "Dimuon event information derived from the Run2010B public Mu dataset",
  "total": 2,
  "total_size_bytes": 3034528
}
```

### Look up glossary term

Find what a physics or experiment term means in the portal's glossary, e.g. luminosity or AOD: its definition, other spellings, related terms and where to read more. An exact match comes first.

**Inputs**

- Term (`term`, text, required): The word or words to look up, e.g. luminosity.
- Most terms (`page_size`, number): The most terms to return, from 1 to 50. Defaults to 5. From 1 to 50. Default: `5`.

**Outputs**

- `count` (number): How many terms are listed.
- `query` (text): The words looked up.
- `summary` (text): One line with how many matched and the best match.
- `terms` (list): The matching terms, an exact match first.
- `total` (number): How many glossary terms match in all.

**Example output**

```json
{
  "count": 2,
  "query": "luminosity",
  "summary": "Found 2 glossary terms for 'luminosity'; the best match is Luminosity.",
  "terms": [
    {
      "category": "generic",
      "definition": "The Luminosity (L) indicates the number of events per time per cross section. The \u201dIntegrated Luminosity\u201d is the sum of the luminosity over time, and is typically measured in units of inverse femtobarn.",
      "experiments": [],
      "id": "Luminosity",
      "links": [
        {
          "text": "Read more on Wikipedia,",
          "url": "https://en.wikipedia.org/wiki/Luminosity_(scattering_theory)"
        }
      ],
      "see_also": [
        "Cross section",
        "Events",
        "Barn",
        "Lumisection"
      ],
      "synonyms": [
        "luminosity"
      ],
      "term": "Luminosity",
      "url": "https://opendata.cern.ch/glossary/Luminosity"
    },
    {
      "category": "generic",
      "definition": "Barn is a unit of area, used to express cross sections, and is equivalent to $10^{-24}$ cm\u00b2. The inverse femtobarn ($fb^{-1}$) is the typical unit used for time-integrated Luminosity.",
      "experiments": [],
      "id": "Barn",
      "links": [
        {
          "text": "Read more in Wikipedia",
          "url": "https://en.wikipedia.org/wiki/Barn_(unit)"
        }
      ],
      "see_also": [
        "Cross section",
        "Luminosity"
      ],
      "synonyms": [
        "barn",
        "Femtobarn",
        "femtobarn"
      ],
      "term": "Barn",
      "url": "https://opendata.cern.ch/glossary/Barn"
    }
  ],
  "total": 2
}
```

### Search records

Find datasets, software, documentation and glossary terms on the CERN Open Data portal, by text, experiment, record type, the years the data was taken, collision energy and file type. Each record comes with its title, type, experiments, DOI, the start of its abstract and its page. Returns a page at a time, newest first unless you choose otherwise.

**Inputs**

- Search text (`query`, text): Words to look for in the records' titles, abstracts and other details, e.g. dimuon. AND and OR work, a minus sign before a word leaves it out, quotes find an exact phrase, and a field can be named, e.g. doi:10.7483/OPENDATA.CMS.CB8H.MFFA. Leave blank for every record.
- Experiments (`experiments`, list): Only records from these experiments, e.g. CMS or ATLAS. Leave blank for every experiment.
- Record types (`record_types`, list): Only these kinds of record, or a kind's sub-type, e.g. Dataset or Dataset > Simulated. Leave blank for every kind, documentation and glossary terms included.
- From year (`year_from`, number): Only records whose data was taken (or that were made) in this year or later, e.g. 2010. From 1900 to 2100.
- To year (`year_to`, number): Only records whose data was taken (or that were made) in this year or earlier, e.g. 2012. From 1900 to 2100.
- Collision energies (`collision_energies`, list): Only data from collisions at these energies, e.g. 13TeV or 7TeV. Leave blank for every energy.
- Collision types (`collision_types`, list): Only data from these collisions: pp for protons, PbPb for lead ions, e+e- for electrons and positrons, and so on.
- File types (`file_types`, list): Only records with files in these formats, e.g. csv, root or nanoaod. Leave blank for every format.
- Order (`sort`, text): Which records come first. Best match only means something with search text. One of: `newest` (Newest first), `oldest` (Oldest first), `best_match` (Best match first), `title` (Title, A to Z), `title_desc` (Title, Z to A). Default: `newest`.
- Records per page (`page_size`, number): How many records to return, from 1 to 100. Defaults to 10. From 1 to 100. Default: `10`.
- Page (`page`, number): Which page to return, from 1. Only the first 10,000 records of a search can be paged through. From 1 to 10000. Default: `1`.

**Outputs**

- `count` (number): How many records this page holds.
- `has_more` (true/false): True when there is a further page.
- `next_page` (number): The next page's number, or null on the last page.
- `page` (number): The page returned, from 1.
- `page_size` (number): Records per page.
- `query` (text): The search text, as sent.
- `records` (list): The records on this page.
- `summary` (text): One line saying how many matched and which are shown.
- `total` (number): How many records match in all.

**Example output**

```json
{
  "count": 2,
  "has_more": true,
  "next_page": 2,
  "page": 1,
  "page_size": 2,
  "query": "dimuon",
  "records": [
    {
      "abstract": "This document contains 100k dimuon events selected from the Mu dataset from Run2010B. Each line corresponds to an event. The main file contains all 100k events. Files with an underscore contain 10k events each.\nThese data were selected from the Mu primary dataset. The selection criteria may be different from that used in CMS physics results. They are not suitable for a full physics analysis.",
      "availability": "online",
      "collision_energy": null,
      "collision_type": null,
      "date_published": "2014",
      "doi": "10.7483/OPENDATA.CMS.CB8H.MFFA",
      "experiments": [
        "CMS"
      ],
      "file_formats": [
        "csv"
      ],
      "id": "700",
      "kind": "record",
      "licence": null,
      "number_of_events": 100000,
      "number_of_files": null,
      "size_bytes": null,
      "subtypes": [
        "Derived"
      ],
      "title": "Dimuon event information derived from the Run2010B public Mu dataset",
      "type": "Dataset",
      "url": "https://opendata.cern.ch/record/700",
      "years": [
        "2010"
      ]
    },
    {
      "abstract": "The collaboration approved 2000 dimuon events around the J/psi for use in education and outreach. This record contains the necessary files for these use-cases.\nThese data were selected for use in education and outreach and contain a subset of the total event information. The selection criteria may be different from that used in CMS physics results. They are not suitable for a full physics...",
      "availability": "online",
      "collision_energy": null,
      "collision_type": null,
      "date_published": "2014",
      "doi": "10.7483/OPENDATA.CMS.SW96.PFX3",
      "experiments": [
        "CMS"
      ],
      "file_formats": [
        "csv",
        "ig",
        "json"
      ],
      "id": "301",
      "kind": "record",
      "licence": "CC0-1.0",
      "number_of_events": 2000,
      "number_of_files": null,
      "size_bytes": null,
      "subtypes": [
        "Derived"
      ],
      "title": "J/psi to two muons from 2010",
      "type": "Dataset",
      "url": "https://opendata.cern.ch/record/301",
      "years": [
        "2010"
      ]
    }
  ],
  "summary": "Found 4 records; showing 1 to 2, best match first.",
  "total": 4
}
```
