1.2 Tutorial: Searching data using the 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.

Introduction

This tutorial is a walk-through of searching the ORCID Registry using the ORCID API. The ORCID API supports searching a subset of ORCID metadata using the popular Solr query syntax. Note that search results only return the <orcid-bio> portion of a researcher’s record; to access the activities section of the ORCID record (affiliations, funding, and works data), you will need to use the API to retrieve data from that section of the record.

This tutorial covers searching using the public API and member APIs. Both require an access token retrieved using your client credentials.

Information on retrieving data from a specific ORCID iD can be found in Tutorial: Retrieve data using the public API and Tutorial: Retrieve data from an ORCID record

Want to find which of your researchers hold ORCID records? See our tips on finding ORCID record holders at your institution.

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.

 

The base URL

Anyone with an ORCID record and public API credentials can search the production registry using https://pub.orcid.org and the sandbox (with relevant sandbox credentials) using https://pub.sandbox.orcid.org

Members with API credentials can search the production registry using https://api.orcid.org and the sandbox (with relevant sandbox credentials) using https://api.sandbox.orcid.org

All base URLs should be followed by the version number of the schema you would like the results returned in, e.g. /v1.2

Note: A read-public access token is required for all searches.

 

Obtaining a search token: Public API

The cURL command required to get a token when using the public API sandbox is:

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"

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

{"access_token":"5266384f-0567-43f0-9cd4-bc6f6a5dc3ea","token_type":"bearer","refresh_token":"c10e89af-c827-4092-80f9-98bd2ec6e6e8","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.  An example cURL call to search with the token is:

curl -H "Content-Type: application/orcid+xml" -H "Authorization: Bearer 5266384f-0567-43f0-9cd4-bc6f6a5dc3ea" "https://pub.sandbox.orcid.org/v1.2/search/orcid-bio/?q=..."

 

Obtaining a search token: Member API

An example cURL call to get a token for searching on sandbox with member clients is:

curl -i -L -H "Accept: application/json" -d "client_id=APP-NPXKK6HFN6TJ4YYI" -d "client_secret=060c36f2-cce2-4f74-bde0-a17d8bb30a97" -d "scope=/read-public" -d "grant_type=client_credentials" "https://sandbox.orcid.org/oauth/token"

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

{"access_token":"a3e496db-5a3b-4cdb-9275-c209e395503f","token_type":"bearer","refresh_token":"f253d852-4a52-4dd0-9f06-7511b684f1cc","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. An example cURL call to search with a member token is:

curl -H "Content-Type: application/orcid+xml" -H "Authorization: Bearer a3e496db-5a3b-4cdb-9275-c209e395503f" "Accept: application/xml" "https://api.sandbox.orcid.org/v1.2/search/orcid-bio/?q=..."

 

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 searching

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 free-form, unrestricted search across all available indexed fields. A basic search for "newman" will therefore turn up contributors with credit-name Newman, or given name Newman, or associated with a work with "newman" in the title, and so on.

 

curl -H "Content-Type: application/orcid+xml" -H "Authorization: Bearer a3e496db-5a3b-4cdb-9275-c209e395504c" "https://pub.sandbox.orcid.org/v1.2/search/orcid-bio/?q=newman"

Boolean searches with multiple keywords are supported. Multiple keywords can be incuded using "AND" or "OR" and brackets; exact phrases and other features of the chosen syntax are supported. The Boolean terms must be in capital letters, lower case "and" and "or" are treated as part of the search.

curl -H "Content-Type: application/orcid+xml" -H "Authorization: Bearer a3e496db-5a3b-4cdb-9275-c209e345503c" "https://pub.sandbox.orcid.org/v1.2/search/orcid-bio/?q=johnson+AND+cardiology+AND+houston"

curl -H "Content-Type: application/orcid+xml" -H "Authorization: Bearer a3e496db-5a3b-4cdb-9275-c209e345503c" "https://pub.sandbox.orcid.org/v1.2/search/orcid-bio/?q=johnson+AND(caltech+OR+"California+Institute+of+Technology")"

 

Paging of search results

The number of items and starting position in the overall list of ranked search results can  be specified with rows and start parameters to allow for paging of long lists of results. The maximum number of results that can be returned in any one query is 100. This request shows profile 2 through 5 in the result set:

curl -H "Content-Type: application/orcid+xml" -H "Authorization: Bearer a3e496db-5a3b-4cdb-9275-c249e395503c" "https://pub.sandbox.orcid.org/v1.2/search/orcid-bio/?q=johnson+cardiology+houston&start=2&rows=3"

 

Fielded search for specific elements

When more specific results are required, fielded search should be used. The following fields are recognized, corresponding to elements in the profile record structure.

Search field Element location in schema Description
orcid //orcid-profile/orcid-identifier The ORCID identifier for the researcher or contributor
given-names //orcid-profile/orcid-bio/personal-details/given-names The given names of the researcher of contributor
family-name //orcid-profile/orcid-bio/personal-details/family-name The family name of the researcher of contributor
credit-name //orcid-profile/orcid-bio/personal-details/credit-name The name that normally appears on publications by the researcher or contributor
other-names //orcid-profile/orcid-bio/personal-details/other-names Alternative names that may have appeared on publications by the researcher or contributor
email //orcid-profile/orcid-bio/contact-details/email The email address of the researcher or contributor
external-id-reference //orcid-profile/orcid-bio/external-identifiers/external-identifier/external-id-reference Identifiers from other systems included in the ORCID record
digital-object-ids* //orcid-profile/orcid-activities/orcid-works/orcid-work/work-external-identifiers/work-external-identifier[work-external-identifier-type="doi"]/work-external-identifier-id DOI of any work in the researcher or contributor’s profile
work-titles //orcid-profile/orcid-activities/orcid-works/orcid-work/work-title/(title|subtitle) The titles of any work in the researcher or contributor’s profile
keywords //orcid-profile/orcid-bio/keywords/keyword Any keywords associated with the researcher or contributor
creation date //orcid-profile/orcid-history/submission-date The date and time the record was created.
last modified date //orcid-profile/orcid-history/last-modified-date The date and time the record was last modified.
text //orcid-profile/orcid-bio All the above fields. This is also the default field for Lucene syntax queries.

* All supported work external identifiers can also be used as a field for searching in the same way that DOIs are.  The work identifier types are listed at Supported Work Identifiers, and are recorded in the record structure as //orcid-profile/orcid-activities/orcid-works/orcid-work/work-external-identifiers/work-external-identifier[work-external-identifier-type="..."]/work-external-identifier-id.

The basic syntax for fielded search is field:value, so the query string family-name:james will find Roland James but not 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
curl -H "Content-Type: application/orcid+xml" -H "Authorization: Bearer a3e496db-5a3f-4cdb-9275-c209e395503c" "https://pub.sandbox.orcid.org/v1.2/search/orcid-bio/?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
curl -H "Content-Type: application/orcid+xml" -H "Authorization: Bearer a3e496db-5afb-4cdb-9275-c209e395503c" "https://pub.sandbox.orcid.org/v1.2/search/orcid-bio/?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
curl -H "Content-Type: application/orcid+xml" -H "Authorization: Bearer a3e496db-5a3r-4cdb-9275-c209e395503c" "https://pub.sandbox.orcid.org/v1.2/search/orcid-bio/?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
curl -H "Content-Type: application/orcid+xml" -H "Authorization: Bearer a3e496db-5a3r-4cdb-9275-c209e395503c" "https://pub.sandbox.orcid.org/v1.2/search/orcid-bio/?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. Return the results in JSON.
Syntax Lucene
Paging All results
URL
curl -H "Content-Type: application/orcid+xml" -H "Accept: application/orcid+json" -H "Authorization: Bearer a3e4r6db-5a3b-4cdb-9275-c209e395503c" "https://pub.sandbox.orcid.org/v1.2/search/orcid-bio/?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
curl -H "Content-Type: application/orcid+xml" -H "Authorization: Bearer a3e496db-5a3b-4cdb-9275-c209e394503c" "https://pub.sandbox.orcid.org/v1.2/search/orcid-bio/?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 1877-5816-0747-5659 and 6181-9093-3346-6284 will be excluded from the results.
Syntax Extended DisMax
Paging First 10 rows only
URL
curl -H "Content-Type: application/orcid+xml" -H "Authorization: Bearer a3e496db-5a3b-4cdb-9275-c204e395503c" "https://pub.sandbox.orcid.org/v1.2/search/orcid-bio/?defType=edismax&q=Raymond+-orcid:(1877-5816-0747-5659+6181-9093-3346-6284)&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
Paging All results
URL
curl -H "Content-Type: application/orcid+xml" -H "Accept: application/orcid+json" -H "Authorization: Bearer a3e496db-5a3b-44db-9275-c209e395503c" "https://pub.sandbox.orcid.org/v1.2/search/orcid-bio/?q=digital-object-ids:%2210.1087/20120404%22"

 

 

 

Example 9

Description Search for all record with an email address with an @orcid.org domain
Paging All results (Note that most ORCID records have the email address marked as private and private information will not be returned in the search results).
URL
curl -H "Content-Type: application/orcid+xml" -H "Accept: application/orcid+json" -H "Authorization: Bearer a3e496db-543b-4cdb-9275-c209e395503c" "https://pub.sandbox.orcid.org/v1.2/search/orcid-bio/?q=email:*@orcid.org"

 

 

 

Example 10

Description Search for records modified between May 6th 2015 and today
Paging First 10 results
URL
curl -H "Content-Type: application/orcid+xml" -H "Authorization: Bearer a3e496db-5a3b-4cdb-9275-c203e395503c" "https://pub.sandbox.orcid.org/v1.2/search/orcid-bio/?q=profile-last-modified-date:%5B2015-05-06T00:00:00Z%20TO%20NOW%5D&start=1&rows=10"