Adding Constraints
The Springer Nature API allows you to limit the results returned by adding constraints to your request. Constraints should appear in your request as a "constraint:argument" pair.
There are three types of constraints: "equals" constraints, "contains" constraints, and "display" constraints. These three types of constraints behave differently.
Note
*M2 (meta/v2) is a new meta API XML version with an up-to-date PAM-compliant schema (the previous meta/v1 still works but meta/v2 is now recommended).
NEW: *meta APIs (v1 and v2) are now also available in JATS (i.e., jats in path, e.g., meta/v2/jats ["jats" refers to JATS and/or BITS]).
"Equals" Constraints
When an "equals" constraint is used, the relevant element value in an article or chapter must match the specified argument exactly in order for that content item to appear in the results.
For example, the request:
http://api.springernature.com/metadata/pam?q=subject:Math&api_key=APIKEYHERE
will return zero results because - although there are documents where the subject element contains the string "math" (e.g., Mathematics) - there are no documents where the value in a subject element is exactly the string "math".
"Equals" constraints are also case sensitive. So, use of the constraint pair, "subject:mathematics" will also return zero results while the constraint pair, "subject:Mathematics" will return many results.
The API currently supports the following "equals" constraints:
| Constraint | Description | Applies to collection | Example Query |
| doi*: | limit to a single Digital Object Identifier | M,O,M2 | http://api.springernature.com/meta/v2/json?q=doi:10.1007/978-3-319-07410-8_4&api_key=.. |
| doi*: | query multiple Digital Object Identifiers | M,O,M2 | http://api.springernature.com/meta/v2/pam?q=(doi:10.1007/s11214-017-0458-1 OR doi:10.1038/s41598-017-17625-2)&api_key=.. |
| subject: | limit to the specified subject collection | M,O,M2 | http://api.springernature.com/openaccess/jats?q=subject:Chemistry&api_key=.. |
| keyword: | limit to articles tagged with a keyword | M,O,M2 | http://api.springernature.com/metadata/pam?q=keyword:onlinear&api_key=.. |
| language: | limit to articles from a particular language | M,O,M2 | http://api.springernature.com/meta/v2/pam?q=language:de&api_key=... |
| pub: | limit to articles from a particular publication | M,O,M2 | http://api.springernature.com/meta/v2/pam?q=pub:Extremes&api_key=... |
| year: | limit to articles/chapters published in a particular year | M,O,M2 | http://api.springernature.com/meta/v2/jats?q=year:2007&api_key=.. |
| onlinedate: | limit to date that an article appeared online | M,O,M2 | http://api.springernature.com/meta/v2/jats?q=onlinedate:2019-03-29 type:Book&api_key=.. (also wildcard, e.g., onlinedate:2019-01-*) |
| onlinedate(from/to): | limit to date range that an article appeared online, using onlinedatefrom, onlinedateto | M,O,M2 | http://api.springernature.com/meta/v2/pam?q=neptune type:Journal openaccess:true year:2019 onlinedatefrom:2019-09-01%20 onlinedateto:2019-12-31&api_key=.. |
| country: | limit to articles authored in a particular country | M,O,M2 | http://api.springernature.com/openaccess/jats?q=country:%22New%20Zealand%22&api_key=.. |
| isbn: | limit to a single International Standard Book Number | M,O,M2 | http://api.springernature.com/metadata/json?q=isbn:978-0-387-79148-7&api_key=.. |
| issn: | limit to a single International Standard Serial Number | M,O,M2 | http://api.springernature.com/metadata/pam?q=issn:1861-0692&api_key=.. |
| journalid: | limit articles to a single Journal id | M,O,M2 | http://api.springernature.com/meta/v2/json?q=journalid:392&api_key=.. |
| topicalcollection: | limit content to a single toplical collection | M,M2 | http://api.springernature.com/meta/v2/json?q=topicalcollection:"Scleroderma"&api_key=.. |
| journalonlinefirst:true | limit articles to Online first | M,O,M2 | http://api.springernature.com/meta/v2/json?q=journalid:270 JournalOnlineFirst:true&api_key=.. |
| date: | limit to documents published on a particular date {yyyy-mm-dd} | M,O,M2 | http://api.springernature.com/openaccess/jats?q=date:2010-03-01&api_key=.. |
| issuetype | limit content to a issuetype | M,M2 | http://api.springernature.com/meta/v2/jats?q=issuetype:Supplement&api_key=.. |
| issue | limit articles to a issue for journal | M,O,M2 | http://api.springernature.com/meta/v2/json?q=issn:1556-276X issue:1 volume:9 &api_key=.. |
| volume | limit articles to a volume for journal | M,O,M2 | http://api.springernature.com/meta/v2/jats?q=issn:1556-276X volume:9 &api_key=.. |
| type: | limit to either Book or Journal content {Book, Journal} | M,O,M2 | http://api.springernature.com/meta/v2/json?q=type:Book&api_key=.. |
| openaccess:true | limit to only Open Access content | M2 | http://api.springernature.com/meta/v2/pam?q=journalid:259 openaccess:true&api_key=.. |
*When a doi contains parentheses, quotes should be placed around the expression: http://api.springernature.com/metadata/pam?q=doi:"10.1016/S1071-3581(97)90014-3"&api_key=...
"Contains" Constraints
When a "contains" constraint is used, the response will include documents where the specified argument is contained anywhere in the relevant element.
The API currenlty supports the following "contains" constraints:
| Constraint | Description | Applies to collection | Example Query |
| empty | A word or phrase that appears among the constraints but is not preceded by a constraint value will be treated as the argument of the "empty constraint" (i.e., a text/string search). Requests of this type will locate documents that contain the specified word or phrase in any element. | M,O,M2 |
|
| title: | locate documents containing a word or phrase in the "article/chapter title" element | M,O,M2 | http://api.springernature.com/meta/v2/pam?q=title:%22game%20theory%22&api_key=.. |
| orgname: | locate documents containing a word or phrase in the "organization name" element | M,O,M2 | http://api.springernature.com/metadata/json?q=orgname:Paris&api_key=.. |
| journal: | locate documents containing a word or phrase in the "journal title" element | M,O,M2 | http://api.springernature.com/openaccess/jats?q=journal:informatics&api_key=.. |
| book: | locate documents containing a word or phrase in the "book title" element | M,O,M2 | http://api.springernature.com/meta/v2/jats?q=book:%22social%20network%22&api_key=.. |
| name: | locate documents containing a word or phrase in the "author name" element | M,O,M2 | http://api.springernature.com/openaccess/jats?q=name:Salvador&api_key=.. |
"Display" Constraints
There is only one "display" constraint currently supported.
| Constraint | Description | Applies to collection | Example Query |
| sort:date | sorts results by publication date in reverse chronological order {date} | M,M2 | http://api.springernature.com/metadata/json?q=subject:Cardiology sort:date&api_key=.. |
| sort:sequence | sorts results by Article Sequence number in chronological order | M,M2 | http://api.springernature.com/meta/v2/pam?q=journalid:115 volume:84 issue:12 sort:sequence&api_key=.. |
Using Multiple Constraints:
Each constraint that appears in your request will automatically be ANDed with all the others. For instance, a request including constraints: "title:bone+name:Jones" is the equivalent to the request containing constraints concatenated by the AND operator: "title:bone%20AND%20name:Jones".
To alter this behaviour you can include the OR operator to broaden the results.
E.g., a request containing the constraints:"title:bone%20OR%20name:Jones", would return results where either the title contained the string "bone" or the author name contained the string "Jones".
Brackets "( )" can also be used to help structure these boolean constructs.
For example, here is a valid request that uses brackets to group constraints:
http://api.springernature.com/meta/v2/pam?q=(title:"game theory" OR title:"perfect information")&api_key=..
This request returns documents where the title either includes the phrase "game theory" or includes the phrase "perfect information".
Excluding Constraints:
Any constraint can be negated by surrounding the constraint:argument pair with "( )" and then preceding it with the minus or hyphen symbol. This operation will remove any results that meet the negated criteria from the response.
For example, the request containing the constraints:
"journal:Planta %20name:Smith%20-(name:Fry)"
will return all documents from the journal "Planta" where the author name field contains the string "Smith" except for the articles where the author field contains the string "Fry".
Helpful Hints
Because the {space} character (represented as "%20" or "+") is used to separate "constraint:argument" pairs, whenever the argument of a constraint is a multi-word phrase (e.g: "bone substitute"), the quote symbol (represented by %22 in a URL) must be used surround the phrase in order for the included {space} to be recognized as part of the argument.For example, consider the "constraint:argument" pair, "orgname:%22University%20of%20Calgary%22".
If the "%22" quotes were omitted from this request, i.e., "orgname:University of Calgary" the API will interpret this request as having three distinct constraints:
1) "orgname:University" 2) "of" and 3) "Calgary" (where "of" and "Calgary" are arguments of "empty" constraints)
The request without quotes would return all documents were "University" appears in the organization name and where the words "of" and "Calgary" appear anywhere in the document.
JournalID
JournalIDs can be found at https://metadata.springernature.com/metadata/kbart (see Complete Nature.com and Complete Springer Journals to get lists of JournalIDs).
To view Example API Responses please see next section.