1.2 Tutorial: Retrieve data using the public API (archive)

This guide is an archived document related to the 1.2 version of the ORCID Message Schema, which is no longer supported by ORCID. The current supported version is 2.0 documentation. Go to the document for the 2.0 Message Schema.

Overview

The purpose of the Query API is to enable external applications to query and search the ORCID system for obtaining record data through a simple RESTful web interface. This article address queries with the Public API and made available to the general public. This API will only return data marked by users as "public" and will come with no service level agreement (SLA). The API may be throttled at the IP / transaction level in order to discourage inadvertent overloading and/or deliberate abuse of the system. For queries using a Member API see Tutorial: Retrieve data from an ORCID record with cURL 1.2 and earlier, for searching public data see Tutorial: Searching data using the API

The following types of API requests are supported:

Bio /orcid-bio Return record holder's name and personal information.
Affiliations /affiliations Return the list of affiliations
Funding /funding Return the list of funding items
Works /orcid-works Return the list of works
Full /orcid-profile Return the entire ORCID record

Calls to the development site can be made using https://pub.sandbox.orcid.org/v1.2/
Public calls to the live site can be made using https://pub.orcid.org/v1.2/

Note: This guide is based on version 1.2 of the ORCID Schema. Refer to the latest version of the schema for the most current information.

 

Retrieving public data

The Query API supports returning ORCID record data in either HTML, XML or JSON format. The default is XML, but clients can specify a preferred representation the corresponding standard mime-type in the Accept HTTP request header.  Including the schema version number will return results in the version specified, otherwise the default schema will be used.

* You will need to get a token when using the cURL commands in the Public API for retrieving data

Bio - retrieving biographical record data

curl -i -L -H "Accept: application/json" -d "client_id=APP-01XX65MXBF79VJGF" -d "client_secret=3a87028d-c84c-4d5f-8ad5-38a93181c9e1" -d "scope=/read-public" -d "grant_type=client_credentials" "https://sandbox.orcid.org/oauth/token"
HTTP/1.1200 OK...
{"access_token":"aa2c8730-07af-4ac6-fb22c0987348","token_type":"bearer","expires_in":631138518,"scope":"/read-public","orcid":null}
curl -H "Content-Type: application/orcid+xml" -H "Authorization: Bearer aa2c8730-07af-4ac6-fb22c0987348" "https://pub.sandbox.orcid.org/v1.2/0000-0002-2389-8429/orcid-bio/"

Example: Request the XML representation of an ORCID bio

Response to XML request
Note: only data marked "public" by the ORCID user is returned with the Public API.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<orcid-message xmlns="http://www.orcid.org/ns/orcid">
     <message-version>1.2</message-version>
    <orcid-profile type="user">
        <orcid-identifier>
            <uri>http://sandbox.orcid.org/0000-0002-2389-8429</uri>
            <path>0000-0002-2389-8429</path>
            <host>sandbox.orcid.org</host>
        </orcid-identifier>
        <orcid-preferences>
            <locale>en</locale>
        </orcid-preferences>
        <orcid-history>
            <creation-method>Direct</creation-method>
            <submission-date>2014-10-24T06:40:40.517Z</submission-date>
            <last-modified-date>2015-09-23T17:42:00.933Z</last-modified-date>
            <claimed>true</claimed>
            <verified-email>true</verified-email>
            <verified-primary-email>true</verified-primary-email>
        </orcid-history>
        <orcid-bio>
            <personal-details>
                <given-names>Sofia</given-names>
                <family-name>Hernandez</family-name>
            </personal-details>
        </orcid-bio>
    </orcid-profile>
</orcid-message>

Example: Request the HTML representation of the bio

curl -i -L -H "Accept: application/json" -d "client_id=APP-01XX65MXBF79VJGF" -d "client_secret=3a87028d-c84c-4d5f-8ad5-38a93181c9e1" -d "scope=/read-public" -d "grant_type=client_credentials" "https://sandbox.orcid.org/oauth/token"
HTTP/1.1200 OK...
{"access_token":"aa2c8730-07af-4ac6-fb22c0987348","token_type":"bearer","expires_in":631138518,"scope":"/read-public","orcid":null}
curl -H "Content-Type: text/html" -H "Authorization: Bearer aa2c8730-07af-4ac6-fb22c0987348" "https://pub.sandbox.orcid.org/v1.2/0000-0002-2389-8429/orcid-bio/"

Example: Request the JSON representation of the bio

curl -i -L -H "Accept: application/json" -d "client_id=APP-01XX65MXBF79VJGF" -d "client_secret=3a87028d-c84c-4d5f-8ad5-38a93181c9e1" -d "scope=/read-public" -d "grant_type=client_credentials" "https://sandbox.orcid.org/oauth/token"
HTTP/1.1200 OK...
{"access_token":"aa2c8730-07af-4ac6-fb22c0987348","token_type":"bearer","expires_in":631138518,"scope":"/read-public","orcid":null}
curl -H "Content-Type: application/orcid+json" -H "Authorization: Bearer aa2c8730-07af-4ac6-fb22c0987348" "https://pub.sandbox.orcid.org/v1.2/0000-0002-2389-8429/orcid-bio/"

 

Example: Request the XML representation of the activities

curl -i -L -H "Accept: application/json" -d "client_id=APP-01XX65MXBF79VJGF" -d "client_secret=3a87028d-c84c-4d5f-8ad5-38a93181c9e1" -d "scope=/read-public" -d "grant_type=client_credentials" "https://sandbox.orcid.org/oauth/token"
HTTP/1.1200 OK...
{"access_token":"aa2c8730-07af-4ac6-fb22c0987348","token_type":"bearer","expires_in":631138518,"scope":"/read-public","orcid":null}
curl -H "Content-Type: application/orcid+xml" -H "Authorization: Bearer aa2c8730-07af-4ac6-fb22c0987348" "https://pub.sandbox.orcid.org/v1.2/0000-0002-2389-8429/orcid-works/"

Example: Request an XML representation of the full ORCID record

curl -i -L -H "Accept: application/json" -d "client_id=APP-01XX65MXBF79VJGF" -d "client_secret=3a87028d-c84c-4d5f-8ad5-38a93181c9e1" -d "scope=/read-public" -d "grant_type=client_credentials" "https://sandbox.orcid.org/oauth/token"
HTTP/1.1200 OK...
{"access_token":"aa2c8730-07af-4ac6-fb22c0987348","token_type":"bearer","expires_in":631138518,"scope":"/read-public","orcid":null}
curl -H "Content-Type: application/orcid+xml" -H "Authorization: Bearer aa2c8730-07af-4ac6-fb22c0987348" "https://pub.sandbox.orcid.org/v1.2/0000-0002-2389-8429/orcid-profile/"