Basic Tutorial: Searching Data Using the ORCID API (3.0+)

This guide describes how to search the ORCID Registry using the ORCID public and member API. Both require an access token retrieved using your client credentials. (Need credentials? Learn how to get them.)

The ORCID API supports searching a subset of ORCID metadata using the popular Solr query syntax. Note that only the ORCID iD of each search hit will be returned unless using the expaned search endpoint. Information on retrieving data from a specific ORCID iD can be found in Read data from an ORCID record.

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

  • Want to find a researcher’s ORCID iD? Have them provide it for you using OAuth: the researcher signs into their ORCID account and is returned automatically to your system with a code you can exchange to obtain their validated ORCID iD
  • 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

Obtain a Search Token

Anyone with API credentials can search the ORCID Registry; a /read-public access token is required for all searches. To obtain a token, make a call to the ORCID API using 2-legged OAuth authorization (i.e. a call directly to the API). The call is the same for public and member API credentials.

An example call to obtain a search token on the sandbox:

 https://sandbox.orcid.org/oauth/token 

  HEADER: accept:application/json

  METHOD: POST

  DATA: 

    client_id=[Your client ID]

    client_secret=[Your client secret]

    grant_type=client_credentials

    scope=/read-public

You will then be returned an access token similar to the following:

 {"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}

The token returned is long-lived (not expiring for approximately 20 years) and can be used for multiple searches. 

Build Your Search

Searches can be performed on the sandbox testing Registry or the live production Registry. 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]

/expanded-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+xml

  Authorization 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 100 results by default:

 <?xml version="1.0"  encoding="UTF-8" standalone="yes"?>

  <search:search num-found="385" xmlns:search="http://www.orcid.org/ns/search"  xmlns:common="http://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>

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. See our tutorial on reading data from an ORCID record for more information.

Query Syntax

All query syntaxes available in SOLR 3.6 are supported, including Lucene with Solr extensions (default), DisMax, and Extended Dismax.

Basic Keyword-Based Searches

As indicated above, 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. 

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.

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 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")

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, familiy-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=jones

Search Result Pagination 

The API returns 1000 results (or rows) by default on both public and member API. To display a certain number of results  add parameters for starting point and number of results. The maximum number 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=1001&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

Search for Specific Elements by Field 

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. (n.b. As of February 2017, fewer than 2% of the 3+ million email addresses on ORCID records are public.)

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.

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.

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.

Funding data

funding-titles

The title of any funding item in the user’s record.

fundref-org-id

The FundRef 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.

 

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.

Example Queries Using the Public API 

Example 1


Description:

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

Syntax:

Lucene

Paging:

Rows 5-10 only

URL:

https://pub.sandbox.orcid.org/v3.0/search/?q=family-name:Sanchez&start=4&rows=6

 

Example 2


Description:

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

Syntax:

Lucene

Paging:

First 10 rows only

URL:

https://pub.sandbox.orcid.org/v3.0/search/?q=text:English&start=0&rows=10

 

Example 3


Description:

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

Syntax:

Lucene

Paging:

All records

URL:

https://pub.sandbox.orcid.org/v3.0/search/?q=pmid:24857732

 

Example 4


Description:

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.

Syntax:

Lucene

Paging:

First 10 rows only

URL:

https://pub.sandbox.orcid.org/v3.0/search/?q=family-name:Einstein+AND+keyword:Relativity&start=0&rows=10

 

Example 5


Description:

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

Syntax:

Lucene

Paging:

All results

URL:

https://pub.sandbox.orcid.org/v3.0/search/?q=family-name:Taylor+AND+given-names:Michael

 

Example 6


Description:

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.

Syntax:

Extended DisMax

Paging:

First 10 rows only

URL:

https://pub.sandbox.orcid.org/v3.0/search/?defType=edismax&q=Raymond&qf=given-names^1.0%20family-name^3.0&start=0&rows=10

 

Example 7


Description:

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.

Syntax:

Extended DisMax

Paging:

First 10 rows only

URL:

https://pub.sandbox.orcid.org/v3.0/search/?defType=edismax&q=Raymond+-orcid:(0000-0002-0879-455X+0000-0001-6238-4490)&qf=given-names^1.0+family-name^3.0&start=0&rows=10

 

Example 8


Description:

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

Paging:

Default

URL:

https://pub.sandbox.orcid.org/v3.0/search/?q=doi-self:%2210.1087/20120404%22

 

Example 9


Description:

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

Paging:

Default

URL:

https://pub.sandbox.orcid.org/v3.0/search/?q=digital-object-ids:10.1087

 

Example 10


Description:

Search for records with a PubMed Identifier 27281629 set to self

Paging:

Default

URL:

https://pub.sandbox.orcid.org/v3.0/search/?q=pmid-self:27281629

 

Example 11


Description:

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

Paging:

Default

URL:

https://pub.sandbox.orcid.org/v3.0/search/?q=isbn:1234

 

Example 12


Description:

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

Paging:

Default

Note: Most ORCID records have the email address marked as private, and private information will not be returned in the search results.

URL:

https://pub.sandbox.orcid.org/v3.0/search/?q=email:*@orcid.org

 

Example 13


Description:

Search for records modified between January 1, 2017 and today

Paging:

First 10 results

URL:

https://pub.sandbox.orcid.org/v3.0/search/?q=profile-last-modified-date:%5B2017-01-01T00:00:00Z%20TO%20NOW%5D&start=1&rows=10

 

Example 14


Description:

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

Paging:

Default (100)

URL:

https://pub.sandbox.orcid.org/v3.0/search/?q=affiliation-org-name:(%22Boston%20University%22+OR+BU)

 

Example 15


Description:

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

Paging:

Default (100)

URL:

https://pub.sandbox.orcid.org/v3.0/search/?q=ringgold-org-id:1438

 

Example 16


Description:

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

Paging:

Default (100)

URL:

https://pub.sandbox.orcid.org/v3.0/search/?q=grid-org-id:grid.5509.9