Endpoints that support content negotiation use a content type specified using the
the Accept request header. See supported formats for a
complete list of formats and the documentation for individual endpoints to see
which formats are supported for each of them.
Example (request article in APS JSON format):
Accept: application/vnd.tesseract.article+json
Individual endpoints define the responses they provide. Clients should guard against general network and HTTP errors such as timeouts, unexpected server errors (50x responses), etc. Most supported error responses provide additional information about the error (see Error Responses).
All JSON responses wrap the object(s) returned in an object containing the
top-level key data. This is done to provide future-proofing of response
objects. The actual data contained in the data key is specified by the type
of response (see documentation for each endpoint below).
Example (list of objects returned):
{
"data": [
]
}
Example (single object returned):
{
"data": {
}
}
There are three main authentication types supported for access to the API:
CHOR-Agency-Auth-Token request header.API key based authentication uses a key provided by APS included in the Authorization header:
Authorization: Bearer <token>
Endpoints that return a list of objects will paginate the response if the
number of items exceeds a requested or internal limit. When additional results
are available the Link header will be returned following the convention
described in draft-nottingham-http-link-header-06
and popularized by the Github API.
The Link header values must be followed, do not construct your own URLs.
Several libraries are available for parsing these headers:
Example:
Link: <http://harvest.aps.org/v2/journals/articles?from=2015-01-01&page=2&per_page=100>; rel="next", <http://harvest.aps.org/v2/journals/articles?from=2015-01-01&page=56&per_page=100>; rel="last"
Retrieve a list of articles given some criteria.
| Name | Type | Values | Description |
|---|---|---|---|
| from | Date or timestamp | YYYY-MM-DD or YYYY-MM-DDThh:mm:ssZ |
Earliest date to return, inclusive. Optional: omit it to start from the earliest article available to you. |
| until | Date or timestamp | YYYY-MM-DD or YYYY-MM-DDThh:mm:ssZ |
Latest date to return, inclusive. Optional, but requires from. |
| date | String | modified, published | Which date from and until apply to, and the order results are returned in: "modified" (default) or "published". See Dates. |
| journals | String | see journals | Journal codes to restrict to (comma separated). Only the journals listed are returned. |
| set | String | see sets | Set to restrict to, for example: "openaccess" |
| page | Integer | 1 or more | Page of results to return (default 1). Follow the Link header rather than setting this yourself (see Pagination). |
| per_page | Integer | 1 to 100 | Number of results to return per response (default and maximum 100; a value outside the range is treated as 100) |
metadata_last_modified_at on each article.from and until is used.Dates and timestamps follow ISO 8601; a date without a time is a whole day in UTC.
Results are returned oldest first by the selected date. Articles sharing a date are returned in a fixed order, so pages do not overlap.
application/vnd.tesseract.article+json (default) is supported for this operation. The response is returned as application/json.until is earlier than from, or until without from)Retrieve a specific article by its ID (DOI). The article will be returned in the format requested.
Retrieve a specific article's accepted fulltext PDF by its ID (DOI).
| Content Type | Description |
|---|---|
| application/vnd.tesseract.article+json | APS article JSON (Default) |
| application/zip | BagIt |
| application/pdf | |
| text/xml | XML |
The JSON format provides the article metadata in an easy to consume format. Full documentation for the fields within the returned JSON object can be found in the Article Response section. A JSON Schema is also provided to validate responses and provide additional documentation.
The BagIt format provides
a mechanism for packaging deliverables consisting of multiple files. The harvest
API provides a bag per article in zip format. When unpacked the bag contains a directory named using the basename of the
filename parameter in the Content-Disposition header. For example, the
response returning the following header:
Content-Disposition: attachment; filename="articlebag-10-1103-PhysRevX-5-021001-complete.zip"
This corresponds to the following structure within the zip file:
articlebag-10-1103-PhysRevX-5-021001-complete/
|-- manifest-md5.txt
|-- manifest-sha1.txt
|-- bagit.txt
|-- bag-info.txt
+-- data/
+-- PhysRevX.5.021001/
|-- figure_f1.eps.gz
|-- figure_f2.eps.gz
|-- figure_f3.eps.gz
|-- figure_f4.eps.gz
|-- figure_f5.eps.gz
|-- figure_f6.eps.gz
|-- fulltext.ocr
|-- fulltext.xml
|-- metadata.xml
+-- online.pdf
Actual names of the bags and contents will vary depending on what components
the request is authorized to retrieve. Best practice is to verify that the
SHA1 checksum of the retrieved bag matches the checksum provided in the
Content-SHA1 response header. Individual files within the bag should be
validated using the manifest-*.txt files contained in the bag.
| Code | Name |
|---|---|
| APSOS | APS Open Science |
| PRA | Physical Review A |
| PRAB | Physical Review Accelerators and Beams |
| PRAPPLIED | Physical Review Applied |
| PRB | Physical Review B |
| PRC | Physical Review C |
| PRD | Physical Review D |
| PRE | Physical Review E |
| PRFLUIDS | Physical Review Fluids |
| PRL | Physical Review Letters |
| PRMATERIALS | Physical Review Materials |
| PRSTPER | Physical Review Special Topics - Physics Education Research |
| PRRESEARCH | Physical Review Research |
| PRX | Physical Review X |
| PRXENERGY | PRX Energy |
| PRXINTELLIGENCE | PRX Intelligence |
| PRXLIFE | PRX Life |
| PRXQUANTUM | PRX Quantum |
| RMP | Reviews of Modern Physics |
| PRSTAB | Physical Review Special Topics - Accelerators and Beams |
| PRPER | Physical Review Physics Education Research |
| PR | Physical Review |
| PRI | Physical Review (Series I) |
| Code | Description |
|---|---|
| openaccess | Open access |
Fields such as title and abstract which may contain formatting use HTML
with MathML embedded that is appropriate for display using MathJax. All strings are UTF-8.
{
"id": "10.1103/PhysRevX.5.021001",
"type": "article",
"abstract": {
"value": "<p>The first law of thermodynamics imposes not just a constraint on the energy content of systems in extreme quantum regimes but also symmetry constraints related to the thermodynamic processing of quantum coherence. We show that this thermodynamic symmetry decomposes any quantum state into mode operators that quantify the coherence present in the state. We then establish general upper and lower bounds for the evolution of quantum coherence under arbitrary thermal operations, valid for any temperature. We identify primitive coherence manipulations and show that the transfer of coherence between energy levels manifests irreversibility not captured by free energy. Moreover, the recently developed thermomajorization relations on block-diagonal quantum states are observed to be special cases of this symmetry analysis.</p>",
"format": "html"
},
"articleType": "article",
"authors": [
{
"type": "Person",
"name": "Matteo Lostaglio",
"firstname": "Matteo",
"surname": "Lostaglio",
"affiliationIds": [
"a1"
]
},
{
"type": "Person",
"name": "Kamil Korzekwa",
"firstname": "Kamil",
"surname": "Korzekwa",
"affiliationIds": [
"a1"
]
},
{
"type": "Person",
"name": "David Jennings",
"firstname": "David",
"surname": "Jennings",
"affiliationIds": [
"a1"
]
},
{
"type": "Person",
"name": "Terry Rudolph",
"firstname": "Terry",
"surname": "Rudolph",
"affiliationIds": [
"a1"
]
}
],
"affiliations": [
{
"name": "Department of Physics, Imperial College London, London SW7 2AZ, United Kingdom",
"id": "a1"
}
],
"date": "2015-04-01",
"fundings": [
{
"funderId": "http://dx.doi.org/10.13039/501100000266",
"funderName": "Engineering and Physical Sciences Research Council",
"awards": []
},
{
"funderId": "http://dx.doi.org/10.13039/501100000921",
"funderName": "European Cooperation in Science and Technology",
"awards": [
"MP1209"
]
},
{
"funderId": "http://dx.doi.org/10.13039/501100000288",
"funderName": "Royal Society",
"awards": []
},
{
"funderId": "http://dx.doi.org/10.13039/501100000275",
"funderName": "Leverhulme Trust",
"awards": []
}
],
"metadata_last_modified_at": "2015-04-01T12:39:49-0400",
"last_modified_at": "2015-04-01T12:39:49-0400",
"identifiers": {
"doi": "10.1103/PhysRevX.5.021001"
},
"issue": {
"number": "2"
},
"pageStart": "021001",
"hasArticleId": true,
"numPages": 11,
"publisher": {
"name": "APS"
},
"rights": {
"rightsStatement": "Published by the American Physical Society",
"copyrightYear": 2015,
"copyrightHolders": [
{
"name": "authors"
}
],
"creativeCommons": true,
"licenses": [
{
"url": "http://creativecommons.org/licenses/by/3.0/"
}
]
},
"journal": {
"id": "PRX",
"abbreviatedName": "Phys. Rev. X",
"name": "Physical Review X"
},
"classificationSchemes": {
"physh": {
"concepts": [
{
"id": "...",
"facet": { "id": "..." },
"primary": true
}
],
"disciplines": [
"..."
]
}
},
"title": {
"value": "Quantum Coherence, Time-Translation Symmetry, and Thermodynamics",
"format": "html"
},
"volume": {
"number": "5"
}
}
Fields:
identifiers field.date=modified filters and orders on thislicenses for the specific license)Most errors will return a JSON response with an error object containing a message with additional details.
Example:
{
"errors": [
{
"title": "zip format not authorized"
}
]
}
The examples below use cURL to demonstrate some common API use cases. The headers are shown along with abbreviated response payloads full payloads have been ommitted for brevity.
curl -D - -H 'Accept: application/vnd.tesseract.article+json' http://harvest.aps.org/v2/journals/articles?from=2015-01-01
Response:
HTTP/1.1 200 OK
Server: nginx/1.7.9
Date: Mon, 27 Apr 2015 12:57:17 GMT
Content-Type: application/json
Content-Length: 403667
Connection: close
Status: 200 OK
Link: <http://harvest.aps.org/v2/journals/articles?from=2015-01-01&page=2&per_page=100>; rel="next", <http://harvest.aps.org/v2/journals/articles?from=2015-01-01&page=56&per_page=100>; rel="last"
{"data":[...]}
curl -D - -H 'CHOR-Agency-Auth-Token: 8f75458ff33070cad3bdee28868bad434f2c' http://harvest.aps.org/v2/journals/articles
## Retrieve a single article - JSON format
curl -D - -H 'Accept: application/vnd.tesseract.article+json' http://harvest.aps.org/v2/journals/articles/10.1103/PhysRevX.5.021001
Response:
HTTP/1.1 200 OK
Server: nginx/1.7.9
Date: Mon, 27 Apr 2015 12:55:10 GMT
Content-Type: application/vnd.tesseract.article+json
Content-Length: 2842
Connection: close
Status: 200 OK
{"data":{...}}
curl -D - -H 'Accept: application/pdf' http://harvest.aps.org/v2/journals/articles/10.1103/PhysRevX.5.021001
Response:
HTTP/1.1 200 OK
Server: nginx/1.7.9
Date: Wed, 29 Apr 2015 20:15:57 GMT
Content-Type: application/pdf
Content-Length: 749834
Connection: close
Vary: Accept-Encoding
Status: 200 OK
ETag: "4d1c9cab10e2030a9ce751017081f73e34f35c0f"
Content-Disposition: inline; filename=PhysRevX.5.021001.pdf
...
curl -D - -H 'Accept: application/zip' http://harvest.aps.org/v2/journals/articles/10.1103/PhysRevX.5.021001
Response:
HTTP/1.1 200 OK
Server: nginx/1.7.9
Date: Wed, 29 Apr 2015 20:43:35 GMT
Content-Type: application/zip
Content-Length: 1833565
Connection: close
Status: 200 OK
ETag: "85797c188ca0fbcb1bf73b55e4d1bd98d9c4c4bc"
Cache-Control: max-age=86400
Expires: Thu, 30 Apr 2015 20:43:35 GMT
Content-SHA1: 85797c188ca0fbcb1bf73b55e4d1bd98d9c4c4bc
Accept-Ranges: bytes
Content-Disposition: attachment; filename="articlebag-10-1103-PhysRevX-5-021001-complete.zip"
...
Open access articles (typically Creative Commons CC-BY) may be retrieved without
the need for any authentication. The set parameter must be provided and set to
"openaccess".
curl http://harvest.aps.org/v2/journals/articles?set=openaccess
The fulltext XML and PDF of the article may be retrieved by calling the endpoint
for individual articles using the DOI retrieved in the list response and setting
the appropriate Accept header:
Fulltext XML:
curl -H 'Accept: text/xml' http://harvest.aps.org/v2/journals/articles/10.1103/PhysRevSTAB.4.072801
PDF:
curl -H 'Accept: application/pdf' http://harvest.aps.org/v2/journals/articles/10.1103/PhysRevSTAB.4.072801