Package: orcid
python-orcid============.. image:: https://badges.gitter.im/ORCID/python-orcid.svg:alt: Join the chat at https://gitter.im/ORCID/python-orcid:target: https://gitter.im/ORCID/python-orcid?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge.. image:: https://img.shields.io/travis/ORCID/python-orcid.svg?style=flat-square:target: https://travis-ci.org/ORCID/python-orcid.. image:: https://img.shields.io/coveralls/ORCID/python-orcid.svg?style=flat-square:target: https://coveralls.io/r/ORCID/python-orcid?branch=master.. image:: https://img.shields.io/pypi/l/orcid.svg?style=flat-square:target: https://pypi.python.org/pypi/orcid/.. image:: https://img.shields.io/badge/status-beta-red.svg?style=flat-square:target: https://pypi.python.org/pypi/orcid/Authors-------Mateusz Susik <mateuszsusik@gmail.com>Installation------------.. code-block:: bashpip install orcidNotes-----This README might be slightly outdated. You can help by submitting a pull request.Exception handling--------------The methods of this library might throw client or server errors. An error isan exception coming from the proven`requests <http://docs.python-requests.org/en/latest/>`_ library. The usualway to work with them should be:.. code-block:: pythonfrom requests import RequestExceptionimport orcidapi = orcid.MemberAPI(key, secret, sandbox=True)try:api.add_record(author-orcid, token, 'work',{'title': 'Title', 'type': 'artistic-performance'})except RequestException as e:# Here the error should be handled. As the exception message might be# too generic, additional info can be obtained by:print(e.response.text)# The response is a requests Response instance.Introduction------------`ORCID <http://orcid.org/>`_ is an open, non-profit, community-based effort toprovide a registry of unique researcher identifiers and a transparent methodof linking research activities and outputs to these identifiers. ORCID isunique in its ability to reach across disciplines, research sectors, andnational boundaries and its cooperation with other identifier systems.ORCID offers an API (Application Programming Interface) that allows yoursystems and applications to connect to the ORCID registry, including readingfrom and writing to ORCID records.There are two types of API available for developers.PublicAPI=========The public API allows the developers to use the search engine and read authorrecords. In order to use it, you need to pass institution's key and secret.The functionality of this API is also available in the member API.Token-----In order to read or update records, the ``token`` is needed. The tokens comefrom OAuth 3-legged authorization. You can perform the authorization usingthis library (examples below).However, if the user is already connected to ORCiD and authenticated (so youhave an authorization code), this process can be simplified:.. code-block:: pythonimport orcidapi = orcid.PublicAPI(institution_key, institution_secret, sandbox=True)token = api.get_token_from_authorization_code(authorization_code,redirect_uri)A special case are the tokens for performing search queries. Such queriesdo not need user authentication, only institution credentials are needed... code-block:: pythonimport orcidapi = orcid.PublicAPI(institution_key, institution_secret, sandbox=True)search_token = api.get_search_token_from_orcid()By reusing the same token, the search functions will run faster skippingthe authentication process.Searching---------.. code-block:: pythonimport orcidapi = orcid.PublicAPI(institution_key, institution_secret, sandbox=True)search_results = api.search('text:English', access_token=Token)While creating a search query, it is possible to use a generator inorder to reduce time needed to fetch a record... code-block:: pythonsearch_results = api.search_generator('text:English',pagination=20)first_result = next(search_results)Reading records---------------.. code-block:: pythonimport orcidapi = orcid.PublicAPI(institution_key, institution_secret, sandbox=True)search_results = api.search_public('text:English')# Get the summarytoken = api.get_token(user_id, user_password, redirect_uri)summary = api.read_record_public('0000-0001-1111-1111', 'activities',token)summary = api.read_record_public('0000-0001-1111-1111', 'record',token)Every record in the `summary` dictionary should contain *put-codes*. Usingthem, it is possible to query the specific record for details. Type of therecord and the put-code need to be provided... code-block:: python# Get the specific recordwork = api.read_record_public('0000-0001-1111-1111', 'work', token,'1111')An exception is made for ``works`` `request_type`. It is possible tofetch multiple selected works at once by selecting multiple``put_codes`` in a list... code-block:: pythonwork = api.read_record_public('0000-0001-1111-1111', 'works', token,['1111', '2222', '3333'])Additional utilities--------------------Python-orcid offers a function for creating a login/register URL... code-block:: pythonurl = api.get_login_url('/authenticate', redirect_uri, email=email)MemberAPI=========The member API allows the developers to add/change/remove records.To modify the records one needs a token which can be obtained followingthe OAuth 3-legged authorization process.The member API lets the developer obtain more information when using thesearch API or fetching the records.To create an instance of the member API handler, the institution key and theinstitution secret have to be provided... code-block:: pythonimport orcidapi = orcid.MemberAPI(institution_key, institution_secret,sandbox=True)search_results = api.search('text:English')# Get the summarytoken = api.get_token(user_id, user_password, redirect_uri,'/read-limited')summary = api.read_record_member('0000-0001-1111-1111', 'activities',token)All the methods from the public API are available in the member API.Getting ORCID-------------If the ORCID of an author is not known, one can obtain it by authorizing theuser:.. code-block:: pythonorcid = api.get_user_orcid(user_id, password, redirect_uri)Adding/updating/removing records--------------------------------Using the member API, one can add/update/remove records from the ORCID profile.All the types of records are supported... code-block:: pythonput_code = api.add_record(author-orcid, token, 'work', json)# Change the type to 'other'api.update_record(author-orcid, token, 'work', put-code,{'type': 'OTHER'})api.remove_record(author-orcid, token, 'work', put-code)The ``token`` is the string received from OAuth 3-legged authorization.The last argument is the record itself. The record shouldfollow ORCID's JSON records definitions. Here is anexample of a dictionary that can be passed as an argument:.. code-block:: python{"title": {"title": {"value": "Work # 1"},"subtitle": null,"translated-title": null},"journal-title": {"value": "journal # 1"},"short-description": null,"type": "JOURNAL_ARTICLE","external-ids": {"external-id": [{"external-id-type": "doi","external-id-value": "ext-id-1","external-id-url": {"value": "http://dx.doi.org/ext-id-1"},"external-id-relationship": "SELF"}]}}If you do not know how to structure your JSON, visit`ORCID swagger <https://api.orcid.org/v2.0>`_It is possible to update many works in the same time!Us ``works`` request type and pass a JSON like this one:.. code-block:: python"bulk": [{"work": {"title": {"title": {"value": "Work # 1"},},"journal-title": {"value": "journal # 1"},"type": "JOURNAL_ARTICLE","external-ids": {"external-id": [{"external-id-type": "doi","external-id-value": "ext-id-1","external-id-url": {"value": "http://dx.doi.org/ext-id-1"},"external-id-relationship": "SELF"}]}}},{"work": {"title": {"title": {"value": "Work # 2"},},"journal-title": {"value": "journal # 2"},"type": "JOURNAL_ARTICLE","external-ids": {"external-id": [{"external-id-type": "doi","external-id-value": "ext-id-2","external-id-url": {"value": "http://dx.doi.org/ext-id-2"},"external-id-relationship": "SELF"}]}}}]