REST API
The PDG REST API supports the downloading of PDG data in JSON format.
pdgLive uses this API to implement the JSON (beta) buttons. The REST API may also be used by user programs for
incidental downloading of PDG data.
Terms of use
The PDG REST API is intended for incidental access. Please do not use it if you wish to download a fair fraction or all of the PDG data - Python API and database files are provided for use cases where this is desired.
To avoid overwhelming the PDG server, access is strictly rate-limited. Please limit your access to the REST API to less than 2 requests per second. IP addresses that substantially exceed this limit will be blocked for 5 minutes at a time from accessing all PDG services. Repeat offenders may be permanently blocked.
Data versions
The data provided by the REST API comes from the latest version of the Review of Particle Physics as presented on
the PDG website and in pdgLive. The Review of Particle Physics
is updated yearly. Whenever a new version becomes available, the data provided by the API is also updated. Between
these updates, minor updates may be made to address mistakes
(see list of errata on
the PDG website).
These updates are propagated to the REST API as soon as possible after they become available on pdgLive.
The data_release_timestamp gives the date and time when the last update was made (see description of /info below).
For summary values only, the PDG Identifier can be used to request data from a previous edition.
Access
The PDG REST API uses URLs of the form
https://pdgapi.lbl.gov/PATH
where PATH is one of the paths given in the table below, and PDGID is the PDG Identifier of the desired quantity.
Path |
Example |
Description |
|---|---|---|
/info |
Get metadata (edition, citation, version, license) |
|
/summaries/PDGID |
Get summary data for PDG Identifiers |
|
/summaries/PDGID/EDITION |
Get summary data from an earlier edition |
|
/doc |
This documentation (regular web page, not JSON) |
Except for the documentation pages under /doc, all paths return JSON documents.
Contents of JSON documents
Preamble
All JSON documents start with the following general information about the request:
Key |
Data type |
Description |
|---|---|---|
status_code |
Number |
HTTP response code |
status_message |
String |
Explanation of status (e.g. “OK” for successful request) |
request_timestamp |
String |
Time stamp of when the request was received |
request_url |
String |
URL for the request |
edition |
String |
Edition of the Review of Particle Physics being used |
about |
String |
A help message providing the link to this documentation |
Data returned by /info
The /info path provides general information about the data being returned by the other paths:
Key |
Data type |
Description |
|---|---|---|
data_release_timestamp |
String |
Time stamp of when the data provided by the API was released |
citation |
String |
Citation for the Review of Particle Physics from which the data comes |
license |
String |
License for using the data returned by the API |
Data returned by /summaries
The /summaries path returns the data published for a given quantity
in the Summary Tables of the Review of Particle Physics. The following
information is returned when the PDG Identifier denotes a single particle property or branching fraction:
Key |
Data type |
Description |
|---|---|---|
pdgid |
String |
PDG Identifier/particle property for which data is returned |
description |
String |
Plain-ASCII description of the quantity the PDG Identifier refers to |
mode_number |
String |
Only for branching fractions: number of this decay in current edition (*) |
section |
String |
Only for branching fractions: section, if any, where mode appears (e.g. “Inclusive decays”) |
pdg_values |
Array |
Array of JSON objects, each describing a summary value (see below) |
(*) Please note that the mode_number of a decay may change from one edition of the Review of Particle Physics to the next one.
Each JSON object describing a summary value may contain the following data (keys whose value is not meaningful for the present summary value are omitted):
Key |
Data type |
Description |
|---|---|---|
value |
Number |
Central value or limit |
error_positive |
Number |
Positive error or null |
error_negative |
Number |
Negative error or null |
value_text |
String |
Plain-text representation of the value with errors or limit |
unit |
String |
Units |
scale_factor |
Number |
Error scale factor when applied to errors |
confidence_level |
Number |
Confidence level for limits or null |
type |
String |
Type of data (“OUR FIT” etc) |
In case the PDG Identifier denotes a particle, the following is returned:
Key |
Data type |
Description |
|---|---|---|
pdgid |
String |
PDG Identifier of particle for which data is returned |
description |
String |
Plain-ASCII description of the particle the PDG Identifier refers to |
summaries |
Array |
A JSON objects with keys “properties” and/or “branching_fractions”, each containing a list of JSON objects for the PDG Identfier(s) describing particle properties or branching fractions for this particle. These JSON objects are the same as what would be returned when querying for a single property or branching fraction, as documented above. |
Error handling
If the request fails, an appropriate HTTP status code is returned, together with a JSON document providing details on the error and the failed request . The following status codes may be generated:
HTTP status code |
Error description |
|---|---|
400 |
Invalid path |
404 |
No such PDG Identifier |
500 |
Internal error (this is a bug - please report) |
License
The data downloaded via the PDG REST API is subject to the license used by the corresponding edition of the Review of Particle Physics. Starting with the 2022 edition, and until further notice, PDG uses the CC BY-NC 4.0 license.