XML API

SCOAP3 has a search API that allows users to search the repository and export data in XML format.

As a quick start, you can use a regular search interface (e.g. browser access to the repository) to refine your query, and then amend a few URL parameters to turn the query into an XML API one.

In April 2015 SCOAP3 hosted a webinar to explain in detail the usage of the API. You can find the slides used during the webinar here.

In the sections below, you can find more details on how to use the API:

Syntax:

GET /search?p=…&of=…&ot=…

Simple parameters:

p = pattern (i.e. your query)
of = output format (e.g. `xm` for MARCXML, this is the best way to obtain data for later processing)
ot = output tags (e.g. “ to get all fields, `100` to get the first author, and so on for other MARC fields )

A full list of parameters follows later in this page.

Notes:

Example: (returning full XML output)

GET /search?p=higgs&of=xm

<!– Search-Engine-Total-Number-Of-Results: 312 –>
<collection>
<record>
<controlfield tag=”001″>5146</controlfield>
<controlfield tag=”005″>20141211195144.0</controlfield>
<datafield tag=”245″ ind1=” ” ind2=” “>
<subfield code=”a”>On the flavor structure of natural composite Higgs models & top flavor violation</subfield>
</datafield><datafield tag=”260″ ind1=” ” ind2=” “>
<subfield code=”c”>2014-12-10</subfield>
<subfield code=”b”>Springer/SISSA</subfield>
</datafield><datafield tag=”024″ ind1=”7″ ind2=” “>
<subfield code=”a”>10.1007/JHEP12(2014)082</subfield>
<subfield code=”2″>DOI</subfield>
</datafield>
<datafield tag=”037″ ind1=” ” ind2=” “>
<subfield code=”a”>arXiv:1408.4525</subfield>
<subfield code=”9″>arXiv</subfield>
</datafield>
<datafield tag=”100″ ind1=” ” ind2=” “>
<subfield code=”a”>Azatov, Aleksandr</subfield>
<subfield code=”v”>CERN Physics Department, Theory Division, CH-1211, Geneva 23, Switzerland</subfield>
<subfield code=”w”>Switzerland</subfield>
</datafield>

Example: (returning XML output, first author (100) and title (245) fields only)

GET /search?p=higgs&of=xm&ot=100,245
<!– Search-Engine-Total-Number-Of-Results: 312 –>
<collection>
<record>
<controlfield tag=”001″>5146</controlfield>
<datafield tag=”245″ ind1=” ” ind2=” “>
<subfield code=”a”>On the flavor structure of natural composite Higgs models & top flavor violation</subfield>
</datafield><datafield tag=”100″ ind1=” ” ind2=” “>
<subfield code=”a”>Azatov, Aleksandr</subfield>
<subfield code=”v”>CERN Physics Department, Theory Division, CH-1211, Geneva 23, Switzerland</subfield>
<subfield code=”w”>Switzerland</subfield>
</datafield>
</record>

Example: returning 250th page of a query, with 50 records per page:

GET /search?p=cern&of=xm&ot=100,245&jrec=12501&rg=50

Parameters – full list:

cc – current collection (e.g. “Advances in High Energy Physics”). The collection the user started to search/browse from.

c – collection list (e.g. [“Physics Letters B”, “European Physical Journal C”]). The collections user may have selected/deselected when starting to search from ‘cc’.

p – pattern to search for (e.g. “ellis and muon or kaon”).

f – field to search within (e.g. “author”) (list of available fields in the next paragraph)

sf – sort field (e.g. “title”).

so – sort order (“a”=ascending, “d”=descending).

sp – sort pattern (e.g. “CERN-“) — in case there are more values in a sort field, this argument tells which one to prefer

of – output format (e.g. “hb”). Usually starting “h” means HTML output (and “hb” for HTML brief, “hd” for HTML detailed), “x” means XML output, “t” means plain text output, “id” means no output at all but to return list of recIDs found, “intbitset” means to return an intbitset representation of the recIDs found (no sorting or ranking will be performed). (Suitable for high-level API.)

ot – output only these MARC tags (e.g. “100,700,909C0b”). Useful if only some fields are to be shown in the output, e.g. for library to control some fields.

recid – display record ID (e.g. “20000”).

Fields that can be used as a pattern:

If you specify a “p” parameter you can give there search terms like:

  • any text – it will look for the given text in title, abstract etc.
  • ***__*: value – field and subfield with value that yopu want to look for:
    • 100__w:Germany
    • 024__:10.1155/2014/231452
    • 773__p:’Advances in High Energy Physics’

There is also a list of possible logical fields (human readable mapping of MARC fields) that you can use as a pattern (examples bellow):

  • title
  • author
  • abstract
  • keyword
  • subject
  • fulltext
  • collection
  • year
  • record ID
  • isbn
  • issn
  • journal
  • affiliation
  • exactauthor
  • datecreated
  • datemodified
  • firstauthor
  • author count
  • doi
  • orcid

This will give all articles with 2014 as publication year:

GET /search?p=year:2014&of=xm

This finds record with a given DOI:

GET /search?p=doi:10.1007/JHEP02(2014)072&of=xm

This finds all records created from 1st August 2014:

GET /search?p=datecreated:2014-08-01->9999-01-01&of=xm

This finds all records by an author with a given ORCID:

GET /search?p=orcid:0000-0003-0429-6868&of=xm

This finds all records with authors with an affiliation in the USA:

GET /search?p=country:USA&of=xm

API key (or token)

The API is a pilot service for SCOAP3 partners. To access the SCOAP3 API you will need a key (or token) for which you have to register.

To use the API each request must be digitally signed by sender: it allows SCOAP3 to identify sender and validate the request. We use a digital signature with public-key encryption. After  registration you will obtain a pair of key: private and public, here how to use them:

  1. Prepare your query (be sure to URL-encode it).
  2. Add “apikey” with your public key to the list of parameters.
  3. Sort (alphabetically) parameters of your query.
  4. Create a HMAC-SHA1 signature of the full query (starting with http://api.scoap3.org/…) using your private key as the key.
  5. Append the hexadecimal-encoded signature to your query string as “signature” parameter.

GET http://api.scoap3.org/search?apikey=xxxxx&of=xm&p=country:USA&signature=yyyyyy

Note: The private key is secret, you should not share it with anyone. SCOAP3 will never ask you your private key.