Basic tutorial: Searching data using the ORCID API

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. 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:

  • 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 to the monthly public data file; contact the ORCID Community team for more information
  • 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 a API credentials can search the ORCID Registry, and a /read-public access token is required for all searches. 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.

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

  https://sandbox.orcid.org/oauth/token 
  HEADER: accept:application/json
  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:

v2.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+xml
  Authorization type: Bearer
  Access token: [Your access token]
  URL: https://pub.sandbox.orcid.org/v2.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="https://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: Bearer
  Access token: [Stored access token]
  URL:  https://pub.sandbox.orcid.org/v2.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/v2.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/v2.0/search/?q=johnson+AND+(caltech+OR+"California+Institute+of+Technology")

Search result pagination

The API returns 100 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 100 results, add parameters for starting point and number of results. The maximum numbers of results that can be returned at one time is 200.

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

   URL:  https://pub.sandbox.orcid.org/v2.0/search/?q=orcid&start=201&rows=200

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/v2.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.

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

* For a full list of external identifier see the identifiers list. Some identifiers may require "-self" or "-part-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/v2.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/v2.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/v2.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/v2.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/v2.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/v2.0/search/?defType=edismax&q=Raymond&qf=given-names^1.0%20family-name^2.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 0000-0002-0879-455X and 0000-0001-6238-4490 will be excluded from the results.

Syntax: Extended DisMax
Paging: First 10 rows only
URL: https://pub.sandbox.orcid.org/v2.0/search/?defType=edismax&q=Raymond+-orcid:(0000-0002-0879-455X+0000-0001-6238-4490)&qf=given-names^1.0+family-name^2.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/v2.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/v2.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/v2.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/v2.0/search/?q=isbn:1234

Example 12

Description: Search for all record 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/v2.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/v2.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/v2.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/v2.0/search/?q=ringgold-org-id:1438