SHERPA/FACT Logo   . . . opening access to research   . . . opening access to research  
Home  •  Definitions  •  FAQ •  API •  Feedback •  About 

Application Programmers' Interface

   

The Application Programmers' Interface (API) will be of interest to anyone who wishes to customise SHERPA/FACT for their institutions. For instance, the API would enable you to:

The FACT API can also be used for statistical studies, such as checking the potential compliance of lists of journals or articles. E.g. see this Presentation to OR2013, slides 20 to 23.

Current Prototype

This API is a beta test version, and should not be used for business-critical applications.

The FACT API works in a similar manner to the SHERPA/RoMEO API and SHERPA/JULIET API, where queries and output options are specified by adding parameters to a base URL. These are listed and described below.

The base URL is:

http://www.sherpa.ac.uk/fact/api-beta

We would very much appreciate feedback on any aspect fo this prototype, for instance; how far it goes towards meeting your requirements, the suitability of the output, etc.

Parameters

Parameter names are case sensitive, but their values are case insensitive. Where they contain spaces or other special characters, they should be URL-encoded.

Parameters may be used in combination, although logically incompatible combinations may yield zero results.

Query Parameters

• &ak= Access Key - a unique string of letters and numbers for each user appication, obtainable from: http://www.sherpa.ac.uk/romeo/apiregistry - Required.
e.g. http://www.sherpa.ac.uk/fact/api-beta?ak=83jLFoo23n3&issn=2230-326X&juliet_id=705

The Access Key used in the examples on this page is a dummy key. You must substitute your own Access Key in the URLs to see the results.

If you already have a RoMEO API Access Key, enter it here: and
• &juliet_id= Funder's JULIET persistent identifier - comma separated list of numbers - Required.
e.g. http://www.sherpa.ac.uk/fact/api-beta?ak=83jLFoo23n3&issn=0025-7273&juliet_id=695
See the list of supported funders below.
• &journaltitle= Journal title string - full title or standard abbreviations - Required, if &issn= not specified.
e.g. http://www.sherpa.ac.uk/fact/api-beta?ak=83jLFoo23n3&juliet_id=722&journaltitle=journal%20of%20medicinal%20chemistry
• &querytype= Type of journal title search. One of exact [default], starts, or contains. Only used with the &journaltitle= parameter.
e.g. http://www.sherpa.ac.uk/fact/api-beta?ak=83jLFoo23n3&juliet_id=717&journaltitle=electrochemistry&querytype=contains
• &issn= ISSN (International Standard Serial Number) - e.g. 1535-9778 - Required, if &journaltitle= not specified.
e.g. http://www.sherpa.ac.uk/fact/api-beta?ak=83jLFoo23n3&juliet_id=709&issn=1535-9778</a>

Output Parameters

• &markup= Markup format for output. One of:
  • xml XML [default]
e.g. http://www.sherpa.ac.uk/fact/api-beta?ak=83jLFoo23n3&juliet_id=717&issn=0378-4266&markup=xml
  • json JSON
e.g. http://www.sherpa.ac.uk/fact/api-beta?ak=83jLFoo23n3&juliet_id=705&issn=2151-4585&markup=json
  • php PHP array definition code for use in eval() commands.
e.g. http://www.sherpa.ac.uk/fact/api-beta?ak=83jLFoo23n3&juliet_id=726&issn=1758-2083&markup=php
  Future additional alternative mark-up formats will be considered
• &trail= show or hide the decision trail for this journal from the FACT algorithm - default hide.
e.g. http://www.sherpa.ac.uk/fact/api-beta?ak=83jLFoo23n3&juliet_id=698&trail=show&issn=1350-7524

Output

Arguments and Data

In general, all computable information is returned as arguments and displayable information is returned as data. This is implemented for each of the &markup= options as in the following examples:

XML

<goldcompliance goldcompliancecode="yes" goldcompliancereport="paidoa">You can publish your article compliantly with open access</goldcompliance>

JSON

"arg_goldcompliancecode": "yes",
"arg_goldcompliancereport": "paidoa",
"val_goldcompliance": "You can publish your article compliantly with open access",

PHP

'goldcompliance' => array (
  '_args' => array (
    'goldcompliancecode' => "yes",
    'goldcompliancereport' => "paidoa"
  ),
  '_data' => "You can publish your article compliantly with open access"
),

Compliance Codes

Separate compliance information is given for the funder's Gold (publishing with open access), Green (self-archiving in open access repositories), and Overall policies. Compliance codes have one of four values:

yes = Compliant.
maybe = Possibly compliant, subject to further checks by the author.
no = Non-compliant.
unknown = Compliance unknown due to missing or unclear policy information

Links within Data

In SHERPA/FACT's human interface, some information includes hyperlinks. These are parsed out into arguments for API output. e.g.:

Confirm that it is published under a Creative Commons Attribution (CC-BY) or more open licence.

becomes:

<goldconfirm goldconfirmcode="confirmgoldlicence" goldconfirmlinkurl="http://creativecommons.org/licenses/" goldconfirmlinktext="Creative Commons">Confirm that it is published under a Creative Commons Attribution (CC-BY) or more open licence.</goldconfirm>

The ...linktext is the text marked as the link in the original data, while the ...linkurl is the corresponding URL. ...linktext and ...linkurl can therefore be used in a string substitution function to recreated the original hyperlink.

Multiple Links. Only one ...linktext and one ...linkurl are allowed. If there is more than one hyperlink, space-separated URLs are given in ...linkurl and their corresponding link texts are given separated by '|' characters in ...linktext. e.g.

You cannot readily archive your article compliantly in Europe PMC/Pubmed Central

becomes:

<greencompliance greencompliancecode="no" greencompliancereport="noncompliant" greencompliancelinkurl="http://europepmc.org/ http://www.ncbi.nlm.nih.gov/pmc/" greencompliancelinktext="Europe PMC|Pubmed Central">:You cannot readily archive your article compliantly in Europe PMC/Pubmed Central</greencompliance>:

Supported Funders

Funder JULIET ID
Arthritis Research UK 14
Arts and Humanities Research Council (AHRC) 698
Biotechnology and Biological Sciences Research Council (BBSRC) 709
Bloodwise 925
British Heart Foundation (BHF) 18
Cancer Research UK 19
Economic and Social Research Council (ESRC) 717
Engineering and Physical Sciences Research Council (EPSRC) 722
Medical Research Council (MRC) 705
Natural Environment Research Council (NERC) 726
Parkinson's UK 411
Science and Technology Facilities Council (STFC) 716
Wellcome Trust 695

FACT Compliance Codes

goldcompliance...
...code...reportdescription
yesoajOpen access journal
yespaidoaPaid open access option
yesromeooajRoMEO-listed open access journal
yesdoajCompliant DOAJ-Listed open access journal
maybecheckissuesCompliant subject to one or more issues being checked
maybedoajDOAJ-listed journal, compliant subject to one or more issues being checked
nononcompliantNon-compliant
nonopmcNot automatically deposited in Pubmed Central
nounavailableGold options unavailable
unknownnopublisherPublisher not known
unknownunlistedNot listed in RoMEO or other journal databases
-notrequiredGold option not required by the funder
 
greencompliance...
...code...reportdescription
yescompliantacceptedAuthor's accepted version may be self-archived compliantly
yescompliantdoajDOAJ-listed open access journal may be self-archived compliantly
yescompliantpdfPublisher's version may be self-archived compliantly
yescompliantpmcCompliantly archived automatically in Pubmed Central
yesspecialCompliant special arrangement for the funder
yespmclistonlyCompliantly archived automatically in Pubmed Central but not self-archivable
maybecheckacceptedAuthor's accepted version may be self-archived compliantly subject to one or more issues being checked
maybecheckdoajDOAJ-listed journal, compliant subject to one or more issues being checked
maybecheckembargoConfirm that the embargo complies
maybecheckpdfPublisher's version may be self-archived compliantly subject to one or more issues being checked
maybecheckrcukextensionConfirm that the RCUK conditions for an extended embargo apply
maybepmclistonlyCompliantly archived automatically in Pubmed Central subject to one or more issues being checked
nononcompliantNon-compliant
nononcompliantdoajNon-compliant DOAJ-listed open access journal
noprohibitedSelf-archiving prohibited
unknowndoajDOAJ-listed open access journal may be compliant
unknownnopublisherPublisher not known
unknownunclearPublisher's policy not clear
unknownunlistedNot listed in RoMEO or other journal databases
-notrequiredGreen option not required by the funder
 
overallcompliance...
...code...reportdescription
yesprefergoldovergreenPrefer the gold option to the green option
yesprefergreenPrefer the green option to the gold option
yesusegoldUse the gold option
yesusegoldandgreenUse both the gold and green options
yesusegoldandorgreenUse either the gold or green options
yesusegreenUse the green option
maybecheckgoldUse the gold option subject to one or more issues being checked
maybecheckgoldandgreenUse both the gold and green options subject to one or more issues being checked
maybecheckgoldandorgreenUse either the gold or green options subject to one or more issues being checked
maybecheckgoldgreenunknownUse the gold option subject to one or more issues being checked, ignoring unknown green option
maybecheckgreenUse the green option subject to one or more issues being checked
maybegoldunknowncheckgreenUse the green option subject to one or more issues being checked, ignoring unknown gold option
nonogoldNon-compliant because no compliant gold option is available
nonogreenNon-compliant because no compliant green option is available
nononcompliantNon-compliant
unknowngoldunknownGold compliance unknown
unknowngoldunknowngreenunknownNeither gold nor green compliance known
unknowngreenunknownGreen compliance unknown

Sample XML Output

<?xml version="1.0" encoding="utf-8" ?>
<factapi version="1.5">
  <control>
    <parameterlist>
      <parameter source="specified">
        <parametername>juliet_id</parametername>
        <parametervalue>722</parametervalue>
      </parameter>
      <parameter source="specified">
        <parametername>issn</parametername>
        <parametervalue>1099-8292</parametervalue>
      </parameter>
      <parameter source="default">
        <parametername>lang</parametername>
        <parametervalue>en</parametervalue>
      </parameter>
      <parameter source="default">
        <parametername>markup</parametername>
        <parametervalue>xml</parametervalue>
      </parameter>
      <parameter source="default">
        <parametername>trail</parametername>
        <parametervalue>hide</parametervalue>
      </parameter>
    </parameterlist>
    <timestamp>2013-10-08 04:06:25</timestamp>
    <num_funders>1</num_funders>
    <num_journals>1</num_journals>
    <outcome>singleJournal</outcome>
    <messagelist />
    <licence>SHERPA/FACT data is available for re-use under a Creative Commons Attribution-Non-Commercial-Share Alike 2.5 licence. For more details, please see the 'conditions for re-use' at the &lt;licenceurl /&gt;, and linked-to from the SHERPA/RoMEO home page.</licence>
    <licenceurl>http://www.sherpa.ac.uk/romeoreuse.html</licenceurl>
    <disclaimer>All SHERPA/FACT information is correct to the best of our knowledge but should not be relied upon for legal advice. SHERPA cannot be held responsible for the re-use of FACT data, or for alternative interpretations which are derived from this information.</disclaimer>
  </control>
  <funderlist>
    <funder juliet_id="722">
      <name>Engineering and Physical Sciences Research Council</name>
      <acronym>EPSRC</acronym>
      <url>http://www.epsrc.ac.uk/</url>
    </funder>
  </funderlist>
  <journallist>
    <journal issn="1099-8292">
      <title>Internet Journal of Chemistry</title>
      <publisher romeo_id="43">Internet Journal of Chemistry</publisher>
    </journal>
  </journallist>
  <overall>
    <overallcompliance overallcompliancecode="yes" overallcompliancereport="usegreen">You can comply with your funder's policy:</overallcompliance>
    <overallrecommendation overallrecommendationcode="usegreen">You should self-archive your article within 6 months of publication.</overallrecommendation>
    <overalladvicelist />
  </overall>
  <gold>
    <goldcompliance goldcompliancecode="no" goldcompliancereport="unavailable">You cannot publish your article with open access</goldcompliance>
    <goldreason>This is not an open access journal, nor does it have a paid open access option.</goldreason>
    <goldfee />
    <goldadvicelist />
    <goldconfirmlist />
    <goldprocesslist />
    <golddecisionlist />
  </gold>
  <green>
    <greencompliance greencompliancecode="yes" greencompliancereport="compliantaccepted">You can archive your article compliantly in an open access repository</greencompliance>
    <greenreason>You may deposit the Accepted version of your article in open access repositories upon publication.</greenreason>
    <greenadvicelist>
      <greenadvice greenadvicecode="archive">Please ensure that your article is deposited in an open access repository within 6 months of publication.</greenadvice>
      <greenadvice greenadvicecode="opendoar" greenadvicelinkurl="http://www.opendoar.org/find.php" greenadvicelinktext="OpenDOAR">If necessary, use OpenDOAR to find your institution's repository.</greenadvice>
    </greenadvicelist>
    <greenconfirmlist />
    <greendecisionlist />
  </green>
</factapi>

Sample JSON Output

{
    "control": {
        "parameter": [
            {
                "arg_source": "specified",
                "val_parametername": "juliet_id",
                "val_parametervalue": 705
            },
            {
                "arg_source": "specified",
                "val_parametername": "issn",
                "val_parametervalue": "2151-4585"
            },
            {
                "arg_source": "specified",
                "val_parametername": "markup",
                "val_parametervalue": "json"
            },
            {
                "arg_source": "default",
                "val_parametername": "lang",
                "val_parametervalue": "en"
            },
            {
                "arg_source": "default",
                "val_parametername": "trail",
                "val_parametervalue": "hide"
            }
        ],
        "val_timestamp": "2013-10-30 12:07:09",
        "val_num_funders": 1,
        "val_num_journals": 1,
        "val_outcome": "singleJournal",
        "message": [],
        "val_licence": "SHERPA/FACT data is available for re-use under a Creative Commons Attribution-Non-Commercial-Share Alike 2.5 licence. For more details, please see the 'conditions for re-use' at the , and linked-to from the SHERPA/RoMEO home page.",
        "val_licenceurl": "http://www.sherpa.ac.uk/romeoreuse.html",
        "val_disclaimer": "All SHERPA/FACT information is correct to the best of our knowledge but should not be relied upon for legal advice. SHERPA cannot be held responsible for the re-use of FACT data, or for alternative interpretations which are derived from this information."
    },
    "funder": [
        {
            "arg_juliet_id": 705,
            "val_name": "Medical Research Council",
            "val_acronym": "MRC",
            "val_url": "http://www.mrc.ac.uk/"
        }
    ],
    "journal": [
        {
            "arg_issn": "2151-4585",
            "val_title": "Geriatric Orthopaedic Surgery and Rehabilitation",
            "arg_romeo_id": 65,
            "val_publisher": "SAGE Publications (UK and US)"
        }
    ],
    "overall": {
        "arg_overallcompliancecode": "yes",
        "arg_overallcompliancereport": "usegoldandorgreen",
        "val_overallcompliance": "You can comply with your funder's policy:",
        "arg_overallrecommendationcode": "usegoldandorgreen",
        "val_overallrecommendation": "Use either of the required methods.",
        "overalladvice": []
    }
    "gold": {
        "arg_goldcompliancecode": "yes",
        "arg_goldcompliancereport": "paidoa",
        "val_goldcompliance": "You can publish your article compliantly with open access",
        "arg_goldreasonlinkurl": "http://www.uk.sagepub.com/sagechoice.sp",
        "arg_goldreasonlinktext": "SAGE Choice",
        "val_goldreason": "Paid open access option available - SAGE Choice - with a range of Creative Commons licences to be selected or confirmed by the author.",
        "val_goldfee": "Indicative fee: £800-£1600, $1500-$3000 per article - Author must request Creative Commons Attribution License",
        "goldadvice": [
            {
                "arg_goldadvicecode": "authorscopyright",
                "val_goldadvice": "You retain the copyright of your article."
            }
        ],
        "goldconfirm": [
            {
                "arg_goldconfirmcode": "confirmgoldlicence",
                "arg_goldconfirmlinkurl": "http://creativecommons.org/licenses/",
                "arg_goldconfirmlinktext": "Creative Commons",
                "val_goldconfirm": "Confirm that articles are published under a Creative Commons Attribution (CC-BY) or more open licence."
            }
        ],
        "goldprocess": [
            {
                "arg_goldprocesscode": "paidoarequest",
                "val_goldprocess": "Your notification of acceptance should invite you to use the open access option. If not, or if already published, contact the journal's editor."
            }
        ],
        "golddecision": []
    }
    "green": {
        "arg_greencompliancecode": "yes",
        "arg_greencompliancereport": "compliantpmc",
        "arg_greencompliancelinkurl": "http://europepmc.org/ http://www.ncbi.nlm.nih.gov/pmc/",
        "arg_greencompliancelinktext": "Europe PMC|Pubmed Central",
        "val_greencompliance": "You can archive your article compliantly in Europe PMC/Pubmed Central",
        "arg_greenreasonlinkurl": "http://europepmc.org/ http://www.ncbi.nlm.nih.gov/pmc/",
        "arg_greenreasonlinktext": "Europe PMC|Pubmed Central",
        "val_greenreason": "This journal will automatically deposit the Publisher's version/PDF of your article in Europe PMC/Pubmed Central at the time of publication.",
        "greenadvice": [
            {
                "arg_greenadvicecode": "nospecialaction",
                "val_greenadvice": "No special action required"
            }
        ],
        "greenconfirm": [],
        "greendecision": []
    }
}

© 2013-2017, University of Nottingham Contact us