Skip to content

API documentation

Tamás Nyíri edited this page Aug 21, 2019 · 15 revisions

Using the API

SCOAP3 API allows search and harvest of all articles metadata and its fulltext files. The limitation is that maximum number of articles metadata downloaded per request is 10; this can be changed when using the unlimited API as a registered partner. All data are exported in JSON format.

Basic request

Base URL for SCOAP3 API is: https://repo.scoap3.org/api/records. To perform an easy search one can use the q parameter to specify a single search pattern. Example URL: https://repo.scoap3.org/api/records/?q=higgs

Request parameters

Parameter Description
q pattern
size number of returned results (max 10 for not authorized queries)
page number of page in results

Search pattern parameters

The q parameter contains a query search pattern. Pattern can be a single search term, contain a logical operator AND, OR, use any of metadata JSON fields or use additional filters.

Examples of search patterns:

Example result

{
  "aggregations": {
    "collaboration": {
      "buckets": [],
      "doc_count_error_upper_bound": 0,
      "sum_other_doc_count": 0
    },
    "country": {
      "buckets": [
        {
          "doc_count": 1,
          "key": "Romania"
        }
      ],
      "doc_count_error_upper_bound": 0,
      "sum_other_doc_count": 0
    },
    "journal": {
      "buckets": [
        {
          "doc_count": 1,
          "key": "Advances in High Energy Physics"
        }
      ],
      "doc_count_error_upper_bound": 0,
      "sum_other_doc_count": 0
    },
    "record_creation_date": {
      "buckets": [
        {
          "doc_count": 1,
          "key": 1514764800000,
          "key_as_string": "2018"
        }
      ]
    }
  },
  "hits": {
    "hits": [
      {
        "created": "2018-10-10T07:30:29.061397+00:00",
        "id": 43025,
        "links": {
          "self": "https://repo.scoap3.org/api/records/43025"
        },
        "metadata": {
          "$schema": "http://repo.scoap3.org/schemas/hep.json",
          "_files": [
            {
              "bucket": "0369e325-67fc-4abe-bde3-d0d6c7387836",
              "checksum": "md5:8c329dea8584d00c850e6080d4ff2958",
              "filetype": "pdf",
              "key": "10.1155/2018/4130417.pdf",
              "size": 2440291,
              "version_id": "caa12ff5-f549-49bf-a513-59df58ddaf71"
            },
            {
              "bucket": "0369e325-67fc-4abe-bde3-d0d6c7387836",
              "checksum": "md5:e88bf45da1b35b3f6d19033fd5cf0174",
              "filetype": "xml",
              "key": "10.1155/2018/4130417.xml",
              "size": 199651,
              "version_id": "78ccf678-4af4-4262-8b19-f25cac66d23b"
            }
          ],
          "_oai": {
            "id": "oai:repo.scoap3.org:43025",
            "sets": [
              "AHEP"
            ],
            "updated": "2019-05-10T13:40:14Z"
          },
          "abstracts": [
            {
              "source": "Hindawi",
              "value": "The black hole information paradox and the black hole entropy are currently extensively researched. The consensus about the solution of the information paradox is not yet reached, and it is not yet clear what can we learn about quantum gravity from these and the related research. It seems that the apparently irreducible paradoxes force us to give up on at least one well-established principle or another. Since we are talking about a choice between the principle of equivalence from general relativity and some essential principles from quantum theory, both being the most reliable theories we have, it is recommended to proceed with caution and search more conservative solutions. These paradoxes are revisited here, as well as the black hole complementarity and the firewall proposals, with an emphasis on the less obvious assumptions. Some arguments from the literature are reviewed, and new counterarguments are presented. Some less considered less radical possibilities are discussed, and a conservative solution, which is more consistent with both the principle of equivalence from general relativity and the unitarity from quantum theory, is discussed."
            }
          ],
          "acquisition_source": {
            "date": "2019-05-10T15:34:49.573960",
            "method": "Hindawi",
            "source": "Hindawi",
            "submission_number": "5e780fa2732811e99fff02163e01809a"
          },
          "arxiv_eprints": [
            {
              "categories": [
                "gr-qc",
                "hep-th",
                "83C57, 83C05, 83C15, 83C75, 81T20"
              ],
              "value": "1807.05864v1"
            }
          ],
          "authors": [
            {
              "affiliations": [
                {
                  "country": "Romania",
                  "value": "Department of Theoretical Physics, National Institute of Physics and Nuclear Engineering – Horia Hulubei, Bucharest, Romania"
                }
              ],
              "full_name": "Stoica, Ovidiu Cristinel",
              "given_names": "Ovidiu Cristinel",
              "orcid": "0000-0002-2765-1562",
              "raw_name": "Stoica, Ovidiu Cristinel",
              "surname": "Stoica"
            }
          ],
          "collections": [
            {
              "primary": "Advances in High Energy Physics"
            }
          ],
          "control_number": "43025",
          "copyright": [
            {
              "holder": "",
              "material": "",
              "statement": "Copyright © 2018 Ovidiu Cristinel Stoica.",
              "year": "2018"
            }
          ],
          "dois": [
            {
              "value": "10.1155/2018/4130417"
            }
          ],
          "imprints": [
            {
              "date": "2018-10-10",
              "publisher": "Hindawi"
            }
          ],
          "license": [
            {
              "license": "CC-BY-3.0",
              "url": "http://creativecommons.org/licenses/by/3.0/"
            }
          ],
          "page_nr": [
            16
          ],
          "publication_info": [
            {
              "artid": "",
              "journal_issue": "",
              "journal_title": "Advances in High Energy Physics",
              "journal_volume": "",
              "material": "",
              "page_end": "",
              "page_start": "4130417",
              "pubinfo_freetext": "",
              "year": 2018
            }
          ],
          "record_creation_date": "2018-10-10T09:30:28.748623",
          "record_creation_year": 2018,
          "titles": [
            {
              "source": "Hindawi",
              "subtitle": "",
              "title": "Revisiting the Black Hole Entropy and the Information Paradox"
            }
          ]
        },
        "updated": "2019-05-10T13:40:14.540094+00:00"
      }
    ],
    "total": 1
  },
  "links": {
    "self": "https://repo.scoap3.org/api/records/?sort=-record_creation_date&q=doi%3A%2210.1155%2F2018%2F4130417%22&page=1&size=10"
  }
}

Metadata

Example record

Bellow the metadata of record 43025 can be seen.

{
  "$schema": "http://repo.scoap3.org/schemas/hep.json",
  "_files": [
    {
      "bucket": "0369e325-67fc-4abe-bde3-d0d6c7387836",
      "checksum": "md5:8c329dea8584d00c850e6080d4ff2958",
      "filetype": "pdf",
      "key": "10.1155/2018/4130417.pdf",
      "size": 2440291,
      "version_id": "caa12ff5-f549-49bf-a513-59df58ddaf71"
    },
    {
      "bucket": "0369e325-67fc-4abe-bde3-d0d6c7387836",
      "checksum": "md5:e88bf45da1b35b3f6d19033fd5cf0174",
      "filetype": "xml",
      "key": "10.1155/2018/4130417.xml",
      "size": 199651,
      "version_id": "78ccf678-4af4-4262-8b19-f25cac66d23b"
    }
  ],
  "_oai": {
    "id": "oai:repo.scoap3.org:43025",
    "sets": [
      "AHEP"
    ],
    "updated": "2019-05-10T13:40:14Z"
  },
  "abstracts": [
    {
      "source": "Hindawi",
      "value": "The black hole information paradox and the black hole entropy are currently extensively researched. The consensus about the solution of the information paradox is not yet reached, and it is not yet clear what can we learn about quantum gravity from these and the related research. It seems that the apparently irreducible paradoxes force us to give up on at least one well-established principle or another. Since we are talking about a choice between the principle of equivalence from general relativity and some essential principles from quantum theory, both being the most reliable theories we have, it is recommended to proceed with caution and search more conservative solutions. These paradoxes are revisited here, as well as the black hole complementarity and the firewall proposals, with an emphasis on the less obvious assumptions. Some arguments from the literature are reviewed, and new counterarguments are presented. Some less considered less radical possibilities are discussed, and a conservative solution, which is more consistent with both the principle of equivalence from general relativity and the unitarity from quantum theory, is discussed."
    }
  ],
  "acquisition_source": {
    "date": "2019-05-10T15:34:49.573960",
    "method": "Hindawi",
    "source": "Hindawi",
    "submission_number": "5e780fa2732811e99fff02163e01809a"
  },
  "arxiv_eprints": [
    {
      "categories": [
        "gr-qc",
        "hep-th",
        "83C57, 83C05, 83C15, 83C75, 81T20"
      ],
      "value": "1807.05864v1"
    }
  ],
  "authors": [
    {
      "affiliations": [
        {
          "country": "Romania",
          "value": "Department of Theoretical Physics, National Institute of Physics and Nuclear Engineering \u2013 Horia Hulubei, Bucharest, Romania"
        }
      ],
      "full_name": "Stoica, Ovidiu Cristinel",
      "given_names": "Ovidiu Cristinel",
      "orcid": "0000-0002-2765-1562",
      "raw_name": "Stoica, Ovidiu Cristinel",
      "surname": "Stoica"
    }
  ],
  "collections": [
    {
      "primary": "Advances in High Energy Physics"
    }
  ],
  "control_number": "43025",
  "copyright": [
    {
      "holder": "",
      "material": "",
      "statement": "Copyright \xa9 2018 Ovidiu Cristinel Stoica.",
      "year": "2018"
    }
  ],
  "dois": [
    {
      "value": "10.1155/2018/4130417"
    }
  ],
  "imprints": [
    {
      "date": "2018-10-10",
      "publisher": "Hindawi"
    }
  ],
  "license": [
    {
      "license": "CC-BY-3.0",
      "url": "http://creativecommons.org/licenses/by/3.0/"
    }
  ],
  "page_nr": [
    16
  ],
  "publication_info": [
    {
      "artid": "",
      "journal_issue": "",
      "journal_title": "Advances in High Energy Physics",
      "journal_volume": "",
      "material": "",
      "page_end": "",
      "page_start": "4130417",
      "pubinfo_freetext": "",
      "year": 2018
    }
  ],
  "record_creation_date": "2018-10-10T09:30:28.748623",
  "record_creation_year": 2018,
  "titles": [
    {
      "source": "Hindawi",
      "subtitle": "",
      "title": "Revisiting the Black Hole Entropy and the Information Paradox"
    }
  ]
}

JSON Schema

The schema describing the metadata used to export data from the repository is available here: http://repo.scoap3.org/schemas/hep.json.

JSON tag description

Most of the JSON fields are self explanatory but the summary can be found below.

Field Description
abstract list of abstracts of an article
source - source of the abstract
value - content of the abstract
acquisition_source information about article origin and delivery
date - date of acquisition delivered by publisher
method - name of harvester
source - source of the article
submission_number - unique ID of harvest
arxiv_eprints (optional) list of arXiv IDs
value - arXiv ID
categories - arXiv categories. First element is always the primary category, followed by the secondary categories (if any).
authors information about articles authors
full-name - full name of the author
given-names - given names of the author
orcid (optional) - ORCID number
raw-name (optional) - authors name as in the metadata
surname - authors surname
authors.affiliations list of authors affiliations
country - extracted country of affiliation
value - affiliation name as in the metadata
collaborations (optional) value - Collaboration name as it appears on the paper
control_number unique ID of the article in SCOAP3 repository (former recid)
copyright article copyright information
holder - holder of copyright
material
statement - statement as in the metadata
year - year of the copyright
dois list of DOIs assigned to this article
imprints publication information
date - publication date
publisher - name of publisher
license articles license information
license - type of license
url - link to full license information
page_nr (optional) number of pages
publication_info bibliographic information about article
material (optional) - type of the paper: article, corrigendum, addendum, erratum
artid (optional) - publishers article ID
journal_issue (optional) - issue of journal
journal_title - title of journal
journal_volume (optional) - volume of journal
note (optional) - publication notes
page_end (optional) - ending page of article
page_start (optional) - starting page of article
pubinfo_freetext (optional) - publication infomrmation
year - publication year
record_creation_date creation date of the record in the repository
titles list of titles available for the article
source - source of the title
subtitle
title
_files fulltext files attached to the record
bucket - virtual location of file
checksum
filetype
key - file name
size - file size in bytes
version_id - internal identifier for file version

Control returned fields

It is possible to get only a subset of available fields using the _source parameter. All above mentioned fields and subfields can be used. Multiple fields have to be separated by a comma (,).

Examples:

Downloading files

Files can be downloaded one-by-one only. Links to files can be constructed in the following way: https://repo.scoap3.org/api/files/ + bucket + / + key

Links (for the same record as in the example) will look like this:

You can’t perform that action at this time.