API Tutorial: Searching the ORCID registry

This tutorial describes how to search the ORCID Registry using the ORCID public and member API. Both of these methods require an access token retrieved using your client credentials.

The ORCID API supports searching a subset of ORCID metadata using the popular Solr query syntax. Please note that only the ORCID iDis returned in the search results. Information on retrieving data from a specific ORCID iD can be found in Read data from an ORCID record.

API search may not be right for your use. You may wish to consider these alternatives:

• Finding a researcher’s ORCID iD? We do not recommend manual entry of any ORCID iDs into your systems or processes. We would advise that you collect authenticated ORCID iDs from your researchers.
• ORCID releases an annual public data file — a snapshot of all public data in the ORCID Registry at that point in time — which can also be used to perform searches on large public data in the Registry. Premium ORCID members can also get access the data file on demand using the public data sync.
• For specific instructions on finding a large number of your institution’s researchers, see our tips on finding ORCID record-holders at your institution

a

Why should I update ORCID records?

You can help make life easier for your users by connecting validated information to their ORCID records. You will also be helping to build trust in scholarly communications and, by keeping that data up to date, you can reduce the reporting burden for your users and improve data quality.

ORCID for Research Organisations

In addition to its use as a persistent identifier for your researchers, ORCID can help you take control of how your institution‚s name is used across research systems. In combination with other persistent identifiers ORCID enables you to authoritatively assert your staff, faculty, and student affiliations with your institution. You can also use ORCID APIs to receive real-time notifications about research activities, to auto-update forms, and to follow your alumni’s careers.

ORCID for Funding Organisations

By embedding ORCID iDs in your funding workflows, you can reliably connect your grantees and funding programs — and save everyone time and reduce errors caused by manual keying of information. Using ORCID in your system(s), you can play your part in building a trusted research information infrastructure by asserting connections between individuals and the grants you award them.

ORCID for Publishers

Researchers are at the heart of everything that scholarly and research publishers do. Accurate author and reviewer information is vital to indexing, search and discovery, publication tracking, funding and resource use attribution, and supporting peer review.

ORCID serves as an information hub, enabling your authors and reviewers to reliably connect to their contributions, and to share information from their ORCID record as they interact with your publishing systems. Collecting iDs for all your authors and reviewers during the publication process — whether for books, journals, datasets, compositions, presentations, code, or a variety of other works — allows for information to be easily shared, ensures researchers can provide consent to share, saves researchers time and hassle, reduces the risk of errors and, critically, enables researchers to get the credit they deserve for the important work they’re doing.

Did you find this FAQ helpful?

1

0

Permalink

a

How do I collect an authenticated ID?

Integrating ORCID into your system allows your organization to collect authenticated ORCID iDs and add them to your own data. At the same time, the researcher provides the organization permission to read and write to and from their ORCID record. 

To make this work, organizations MUST obtain authenticated ORCID iDs using the ORCID OAuth API.  This means they include an ORCID branded button or link within their system, that when clicked, asks the user to sign in to their ORCID record.

Once signed in, the user will be asked to authorize access to the system asking for their ORCID iD

The user’s ORCID iD and name on the ORCID record (depending on visibility settings) is returned to the organization as part of this process.   The system can then request additional data from the ORCID API.

The above described workflow for collecting authenticated APIs is available in both ORCID’s public and member APIs. The former is available for use free of charge by non-commercial services.

Did you find this FAQ helpful?

5

0

Permalink

Obtain a search token

Anyone with a API credentials can search the ORCID Registry. The member API requires a /read-public access token in order to make API calls. To obtain a token, make a call to the ORCID API using two-legged OAuth authorization (i.e. a call directly to the API). The call is the same for public and member API credentials.

a

How do I get “/read-public” access token?

Anyone with public or member API credentials can receive a /read-public access token. To obtain a token, you make a call to the ORCID API token endpoint.

This process is often referred to as the client-credentials OAuth flow, or 2-step OAuth.

An example call to obtain an access token to read public data on the sandbox — replace the placeholders with your credentials (be sure to remove the brackets.

URL=https://sandbox.orcid.org/oauth/token
  HEADER: Accept: application/json
  METHOD: POST
  DATA: 
    client_id=[Your public API client ID]
    client_secret=[Your public API secret]
    grant_type=client_credentials
    scope=/read-public

You will then be returned an access token similar to the following. The token returned is long-lived (not expiring for approximately 20 years) and can be used multiple times to retrieve public data from ORCID records. 

{"access_token":"4bed1e13-7792-4129-9f07-aaf7b88ba88f","token_type":"bearer",
"refresh_token":"2d76d8d0-6fd6-426b-a017-61e0ceda0ad2","expires_in":631138518,
"scope":"/read-public","orcid":null}

Note: All tokens with the /authenticate scope now also have /read-public scope included. If you use only the /authenticate scope, you can use the stored access tokens to read public data without needing to again obtain an access token. 

Integrators using the member API can use the /read-public scope to read ORCID record summaries.

Did you find this FAQ helpful?

4

39

Permalink

Basic keyword based searches

Searches can be performed on the sandbox testing registry or the live production registry.  The search API endpoint accepts GET for HTTP requests. The only required input is the query string which is passed on to the Solr search engine. 

a

How do I use the ORCID Search API?

The ORCID search API uses the SOLR syntax. All query syntaxes available in SOLR 3.6 are supported, including Lucene with Solr extensions (default), DisMax, and Extended Dismax.

You need a “/read-public” access token to use it. Once you have obtained your search token, build your base search URL:

Credentials type:	Public API	Member API
Resource URL:	Sandbox: https://pub.sandbox.orcid.org Production: https://pub.orcid.org	Sandbox: https://api.sandbox.orcid.org Production: https://api.orcid.org
API version:	v3.0
Search endpoint	/search/?=[query]

An example call to search for “orcid” with the token on the sandbox public API with the results returned in XML format is:

Method:  GET Content-type: application/vnd.orcid+xmlnAuthorization type and Access token: Bearer [stored access token]URL: https://pub.sandbox.orcid.org/v3.0/search/?q=orcid

The results will specify the number of results found (num-found) and display the first 1000 results by default:

 <?xml version="1.0"  encoding="UTF-8" standalone="yes"?>
  <search:search num-found="385" xmlns:search="https://www.orcid.org/ns/search"  xmlns:common="https://www.orcid.org/ns/common">
  <search:result>
  <common:orcid-identifier>
    <common:uri>https://sandbox.orcid.org/0000-0001-2345-6789</common:uri>
    <common:path>/0000-0001-2345-6789</common:path>
    <common:host>sandbox.orcid.org</common:host>
  </common:orcid-identifier>
  </search:result>
  [...]
  </search:search> 

An example basic search on the sandbox public API with results returned in json format:

Method: GET
Content-type: application/vnd.orcid+json
Authorization type and Access token: Bearer [stored access token]
URL:  https://pub.sandbox.orcid.org/v3.0/search/?q=newman

The search returns only the individual ORCID iDs of records holding public data matching the search. To obtain more information about the result, make a call to read the ORCID record directly.

For more information, see our Search API tutorial.

Did you find this FAQ helpful?

1

3

Permalink

Expanded Search

In addition to the basic search, the expanded search end point expanded-search is available. Using this endpoint returns the following information: orcid-id, given-names, family-names, credit-names, other-names, email and institution when using the standard search syntax. Results can be returned in either XML or JSON.

An example search on the sandbox public API for term “jones”

URL: https://pub.sandbox.orcid.org/v3.0/expanded-search/?q=spaceman

    <expanded-search:expanded-result>
        <expanded-search:orcid-id>0000-0002-2436-0000</expanded-search:orcid-id>
        <expanded-search:given-names>Dave Theodore</expanded-search:given-names>
        <expanded-search:family-names>Spaceman</expanded-search:family-names>
        <expanded-search:other-name>D Spaceman</expanded-search:other-name>
        <expanded-search:other-name>D T Spaceman</expanded-search:other-name>
        <expanded-search:institution-name>The University of The Moon</expanded-search:institution-name>
        <expanded-search:institution-name>Saturn Institute</expanded-search:institution-name>
    </expanded-search:expanded-result>

Search results returned in CSV format

Search results can also be returned in CSV format. As part of the call you can specify the output columns from a list of available fields below:

•  orcid
•  email
•  given-name
•  family-name
•  given-and-family-names
•  credit-name
•  other-name
•  current-institution-affiliation-name
•  past-institution-affiliation-name 

Using your credentials you need to specify the header to be ‘text/csv’. As part of the search call, you need to add the fields that you require on the output to the query too.  

An example call for a member searching on a ringgold ID* with the required output including ORCID, name and affiliation. 

Method: GET
  Content-type: text/csv
  Authorization type: Bearer
  Access token: [Stored access token]
  URL:  https://api.orcid.org/v3.0/csv-search/?q=ringgold-org-id:385488&fl=orcid,given-names,family-name,current-institution-affiliation-name,'

You can also complete the search using your browser. The URL is constructed the same way but you do not need to use any API credentials. Please note that this can only be completed using the public API. 

A note on quotes or speech marks.

When searching in the browser, please use straight quotes like these :  "" when performing searches and not curly quotes like these: “” .  Using curly quotes will give you incorrect results.

Below is an example call using the public API searching by organisation name with the ORCID, given names, family names, current institution affiliation name and past institution affiliation name as the desired output. 

https://pub.orcid.org/v3.0/csv-search/?q=affiliation-org-name:ORCID&fl=orcid,given-names,family-name,current-institution-affiliation-name,past-institution-affiliation-name

Below is another example call using the public API searching by different variations of the organizations name.

https://pub.orcid.org/v3.0/csv-search/?q=affiliation-org-name:(“University of Plymouth” OR “Plymouth University”)

Formatting search queries

The default behavior is a free-form, unrestricted search across all available indexed fields. A basic search for “newman” will therefore turn up researchers with the published name Newman, given name Newman, or associated with a work with “newman” in the title, etc. Searches can be returned in json or xml based on what is specified in content-type.

The API also supports Boolean searches using multiple keywords, exact phrases, and other Boolean search features. Keywords must be combined using brackets and “AND” or “OR” in upper case — lower case “and” and “or” are treated as a part of the search.

An example Boolean search on the sandbox public API for records matching three keywords (johnson, cardiology, and houston):

URL:  https://pub.sandbox.orcid.org/v3.0/search/?q=johnson+AND+cardiology+AND+houston

An example Boolean search on the sandbox public API for records matching the keyword “johnson” and the keyword “caltech” or the phrase “California Institute of Technology” and results returned in XML:

URL:  https://pub.sandbox.orcid.org/v3.0/search/?q=johnson+AND+(caltech+OR+"California+Institute+of+Technology")

Search for specific elements by field

You can use a fielded search when you need to search a specific section of the ORCID record.

The basic syntax for fielded search is field:value, so the query string family-name:james will find record with the family name “James”, such as “Roland James”, but not those with the first name “James”, such as “James Johnson”.

Multiple field:value pairs can be provided. Matching is based on sub-string tokens rather than raw strings, so query string other-names:carberry will match both J. Carberry and J. S. Carberry.

a

Which fields does the ORCID Search API support?

The ORCID search API uses the SOLR syntax. All query syntaxes available in SOLR 3.6 are supported, including Lucene with Solr extensions (default), DisMax, and Extended Dismax.

You can use a fielded search when you need to search a specific section of the ORCID record. The current list of fields recognized in the API search, along with their corresponding record structure elements, are as follows:

Search field	Description
Biographical data
given-names	The given (first) name(s) of the user.
family-name	The family (sur)name of the user.
credit-name	The “published name” on the ORCID user interface, the name that normally appears on publications by the user
other-names	Alternative names that may have appeared on publications by the user.
email	The email address of the user.
keyword	Any keywords associated with the user.
external-id-reference	Identifiers from other systems added to the user‚s ORCID record using the API.
Affiliations data
affiliation-org-name	The name of any organization in an education or employment item in the user’s record.
grid-org-id	The GRID ID of any organization in the activities section of the user’s record. Generally this will be associated with an education or employment item.
ror-org-id	The ROR ID of any organization in the activities section of the user’s record. Generally this will be associated with an education or employment item.
ringgold-org-id	The Ringgold ID* of any organization in the activities section of the user’s record. Generally this will be associated with an education or employment item.
Funding data
funding-titles	The title of any funding item in the user‚s record.
fundref-org-id	The Crossref Funder Registry ID of any organization in the activities section of a user‚s record. Generally this will be associated with a funding item, but it may also be associated with an affiliation.
grant-numbers	Grant number (identifier) of any funding item in the user’s record.
Research activities data
work-titles	The titles of any work in the user’s record.
digital-object-ids	A work external identifier with type doi
doi-self	A work external identifier with type doi and the external identifier relationship set to self
[external identifier type]*	A work external identifier with the given type
[external identifier type]*-self	A work external identifier with the given type and the external identifier relationship set to self
[external identifier type]*-part-of	A work external identifier with the given type and the external identifier relationship set to part-of
[external identifier type]*-version-of	A work external identifier with the given type and the external identifier relationship set to version-of * For a full list of external identifier see the identifiers list. Some identifiers may require “-self” “-part-of”  or “-version-of” to return results
ORCID record data
orcid	The 16-digit ORCID identifier of the user, in 0000-0001-2345-6789 format.
profile-submission-date	The date and time the record was created.
profile-last-modified-date	The date and time the record was last modified.
All data
text	All the above fields. This is also the default field for Lucene syntax queries.

See our Search API Tutorial for more information.

*Although Ringgold identifiers still exist within the ORCID registry, as of 1 August 2023, ORCID no longer receives updates to the RINGGOLD organization identifier database used by our Registry, nor will we be able to process or use RINGGOLD IDs created after that date. See our FAQ for more info

Did you find this FAQ helpful?

1

1

Permalink

Search result pagination

The API returns 1000 results (or rows) by default on both public and member API. To display a certain number of at once, or to retrieve past the first 1000 results, add parameters for starting point and number of results. The maximum numbers of results that can be returned at one time is also 1000.

An example search on the sandbox public API for the second 1000 results matching the keyword “orcid”:

URL:  https://pub.sandbox.orcid.org/v3.0/search/?q=orcid&start=1000&rows=1000

An example search on the sandbox public API for items 2 through 4 in a search with the terms “johnson”, “cardiology”, and “houston”:

URL:  https://pub.sandbox.orcid.org/v3.0/search/?q=johnson+cardiology+houston&start=2&rows=3

Example queries using the public API

Example 1

Search family names of all ORCID records for the name “Sanchez”

Example 2

Search all searchable fields of all ORCID records for the word “English”

Example 3

Search for contributors associated with the work at PubMed ID 2485-7732

Example 4

Search for records with the family name “Einstein” and the keyword “Relativity”. Only records containing both the family name and the keyword will be returned.

Example 5

Search for records with the Family name Taylor and the given-name Michael.

Example 6

Search given names and family names of all ORCID records for “Raymond” but boost the family name. Records with given names containing “Raymond” and family name containing “Raymond” will be returned, but those with family name will appear at the top of the list and will have a higher relevancy score.

Example 7

Search given names and family names of all ORCID records for “Raymond” but boost the family name. Records with given names containing “Raymond” and family name containing “Raymond” will be returned, but those with family name will appear at the top of the list and will have a higher relevancy score.The two records with ORCID ID https://sandbox.orcid.org/0000-0002-0879-455X and https://sandbox.orcid.org/0000-0001-6238-4490 will be excluded from the results.

Example 8

Search for records with the exact DOI 10.1087/20120404 set to self

Example 9

Search for records with a DOI that includes 10.1087 set either to self or part-of

Example 10

Search for records with a PubMed Identifier 27281629 set to self

Example 11

Search for records with an ISBN Identifier including 1234 set to either self or part-of

Example 12

Search for all records with an email address with an @orcid.org domain

Example 13

Search for records modified between January 1, 2017 and today

Example 14

Search for records affiliated with the organization with the exact name “Boston University” or “BU”

Example 15

Search for records affiliated with the Ringgold ID* 1438 (University of California Berkeley) with CSV format

Example 16

Search for records affiliated with the GRID ID grid.5509.9 (University of Tampere) using the expanded search

* Although Ringgold identifiers still exist within the ORCID registry, as of 1 August 2023, ORCID no longer receives updates to the RINGGOLD organization identifier database used by our Registry, nor will we be able to process or use RINGGOLD IDs created after that date. See our FAQ for more info