Skip Navigation

Java Software Development Kit

Download the SDK

Requirements

  • JDK 17 and above
  • Apache Maven 3.5+
  • IEEE Xplore API Access Key

Source Setup

  • Import the contents of the attached zip file as a maven project in your favorite java editor like eclipse or IntelliJ
  • If you want to run the app from the command line then ensure Java and Maven are in your Path and run mvn: clean package
  • The project has an application.properties file. The API URL, Customer ID and the API Access Key are configured in there.
  • If you run into any issues with the JDK Path in eclipse, try this:
    • In Eclipse, open Window | Preferences | Java | Installed JREs, make sure there's a JDK (and not just a JRE) for Java 17, then go to the submenu Execution Environments and mark this JDK as compatible with JavaSE-17 or higher. After that, Maven | Update Project should work as desired.
    • See the pom.xml in the source for the dependencies. Please make sure you have the JDK version listed in pom (maven.compiler.source tag) as the same JDK (17+) in the editor.

Methods Overview

Note: Parameters are usually strings so they should have quotes around them.

Query Methods

Class: org.ieee.ieeexplore.service.IEEEService

Method Parameter(s) Usage
findByAbstractText() One parameter: the abstract text Queries text in abstracts.
findByAffiliationText() One parameter: the affiliation text Queries text in affiliation data field.
findByArticleNumber() One parameter: article number Creates a query using IEEE’s unique article identifier.

Note: when used all other query methods are ignored.
findByArticleTitle() One parameter: article title Queries based on the title of an individual document.

Can be used with other query methods, except for findByArticleNumber().
findByAuthorFacetText() One parameter: author facet text Queries text in Open Author Facet data field.
findByAuthorText() One parameter: author text Queries text in author data field.
findByBooleanText() One parameter: boolean query Creates a boolean query against all configured metadata fields, abstract, and document text. Do not include parentheses.
findByContentTypeFacetText() One parameter: content type facet text Queries text in Open Content Type Facet data field.
findByDigitalObjectIdentifier() One parameter: digital object identifier Creates a query using IEEE’s unique digital object identifier.

Note: when used all other query methods are ignored, except for findByArticleNumber(), which overrides the digital object identifier.
findByFacetText() One parameter: facet text Queries text in Open/Facet data field.
findByIndexTerms() One parameter: index terms text Queries text in Author Keywords, IEEE Terms, and Mesh Terms.

Note: include no more than two wildcard words. Each wildcard word must have a minimum of three characters preceding the wildcard (*).
findByIsbn() One parameter: isbn number Queries based on International Standard Book Number.
findByIssn() One parameter: issn number Queries based on International Standard Serial Number.
findByIssueNumber() One parameter: issue number Queries based on Journal Issue Number.
findByMetaDataText() One parameter: meta data text Queries text in configured metadata fields and abstracts.

Note: include no more than two wildcard words. Each wildcard word must have a minimum of three characters preceding the wildcard (*).
findByPublicationFacetText() One parameter: publication facet text Queries text in Open Publication Facet data field.
findByPublisherFacetText() One parameter: publisher facet text Queries text in Open Publisher's Facet data field.
findByPublicationTitle() One parameter: publication title text Queries text in the title of a publication (Journal, Conferences, or Standard).
findByPublicationNumber() One parameter: publication number Queries by the publication number.
findByPublicationYear() One parameter: publication year Queries against the publication year data field.

Note: the format of this data varies by publication.
findByThesaurusTerms() One parameter: thesaurus terms (IEEE terms) text Queries keywords assigned to IEEE journal articles and conference papers from a controlled vocabulary created by the IEEE.

Note: include no more than two wildcard words. Each wildcard word must have a minimum of three characters preceding the wildcard (*).
setUsingOpenAccess() One parameter: boolean to enable Open Access query Queries using the article number, returning a raw String of the Open Access article text.
callApi() Takes the ApiRequest as a parameter. Used for chargeable full text requests.

Returns the ApiResponse.

See the test named FullTextQueryTest for a successful resolution.
formatApiResponseAsJson() Takes the ApiResponse as a parameter. Returns the ApiResponse as a JSON string.
formatApiResponseAsXml() Takes the ApiResponse as a parameter. Returns the ApiResponse as an XML string.
retrieveAuthToken() Used for chargeable full text article requests; to learn more contact your IEEE representative.

Reads the auth token from the properties file and queries the auth API to get a session based token back that is valid for 15 minutes. This token has to be passed to query the full text document.
Returns the auth token passed along with the api call. This method does not need to be explicitly called as it will be invoked from the callApi() method.

Filter and Sort Methods

Method Parameter(s) Usage
setMaxRecords() Configured in the ApiRequest. Sets the maximum size of the result set returned.

Defaults to 25 and has a max of 200.
setResultsFilter() Configured in the ApiRequest.

Accepted keys to the Map are:

"content_type"
"end_year"
"open_access"
"publication_number"
"publisher"
"start_year"

 

Reduces the result set based on the parameter matching the value passed.

Multiple filters can be in place, but only one filter per type (for example, only one end_year filter can be used for filtering).

See the Filtering Parameters for the accepted values.
setSortByField() Configured in the ApiRequest.

Accepted values are:

"author"
"article_number"
"article_title"
"publication_title"
"publication_year"
Sets the field used for sorting.
setSortOrder() Configured in the ApiRequest.

Accepted values are:

"asc"
"desc"
Sets the direction of the sorting.
setStartRecord() Configured in the ApiRequest. Sets the starting position in the set of results (for example, starting at the third result).

Results Method

Method Parameter(s) Usage
setDataType() Configured in the ApiRequest.

One parameter is passed for the data type; the accepted values are:

"json"
"xml"
Sets the data type for the results; defaults to JSON.

Running the Query and Getting Results

Method Parameter(s) Usage
callApi() Static method that can be called from the Service class IEEEService.

Takes ApiRequest as a method argument. All the API search configuration can be handled in that class. Documentation is included in the SDK.
Returns the search results as a String.

Defaults

  • Data type defaults to JSON.
  • Position 1 in the set of results is the starting position.
  • Results sort by Article Title and in ascending order (A-Z) by default; if the Content Type is set to ‘Standards’ then sorting is by Publication Year because Standards do not have some of the other sorting fields.
  • Maximum number of results returned defaults to 25.

Examples

Italicized text in the examples below should be replaced with your desired values.

Find Auth Token

String token = IEEEService.retrieveAuthToken().getToken();
The following properties are expected to be in the application.properties file.

#Auth Token Endpoint
auth.token.endpoint=https://ieeexploreapi.ieee.org/api/v1/auth/token

#Auth Token
auth.token=

#API Key
api.key=


application.properties sample

-- the application.properties file should have the following properties specified.

# End Point Other than Open Access Articles and Full Text requests
api.endpoint=https://ieeexploreapi.ieee.org/api/v1/search/articles

# Used For: Open Access Articles lookup, Full Text requests, Citations requests
open.access.endpoint=https://ieeexploreapi.ieee.org/api/v1/search/document/

# Used For: paper cites and author bio
author.endpoint='https://ieeexploreapi.ieee.org/api/v1/author/';

#usage requests
usage.endpoint=https://ieeexploreapi.ieee.org/api/v1/user/

# Customer ID
customer.id=[replace with customerid]

usage.endpoint.service=/samlreport

#End Point used to request chargeable Full Text auth token
auth.token.endpoint=https://ieeexploreapi.ieee.org/api/v1/auth/token

#Auth Token
auth.token=[replace with auth token]

#API Key
api.key=[replace with api key]


#Token Expiration in minutes
auth.token.alive=15

Query Using Auth Token

	// @see callApi in IEEEService class.

	String params =
		new StringBuilder("?apikey=").append(API_KEY)
			.append("&includeTerms=true")
			.append("&startDate=").append(apiRequest.getStartDate())
			.append("&endDate=").append(apiRequest.getEndDate())
			.append("&cltoken=").append(token.getToken().trim())
			.toString();
	String url = USAGE_URL + params;
	HttpRequest request = HttpRequest.newBuilder()
		.version(HttpClient.Version.HTTP_2)
		.uri(URI.create(url))
		.GET()
		.build();
	HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
	String responseBody = response.body();


Query by Abstract Text

String response = IEEEService.findByAbstractText("query");

Query by Affiliation

String response = IEEEService.findByAffiliationText("query");

Query by Article Number

String response = IEEEService.findByArticleNumber("article_number");

Query by Article Title

String response = IEEEService.findByArticleTitle("query");

Query by Author Facet

String response = IEEEService.findByAuthorFacetText("query");

Query by Author Name

String response = IEEEService.findByAuthorName("query");

Boolean Query

Searches all configured metadata fields, abstract, and document text.

String response = IEEEService.findByBooleanText("boolean_query_without_parentheses");

Query by Open Content Type Facet

String response = IEEEService.findByContentTypeFacetText(“query");

Query by DOI (Digital Object Identifier)

String response = IEEEService.findByDigitalObjectIdentifier(“query");

Query by Open/Facet Value

String response = IEEEService.findByFacetText(“query");

Query by Index Terms

Queries text in Author Keywords, IEEE Terms, and Mesh Terms.

String response = IEEEService.findByIndexTerms(“query");

Query by ISBN

String response = IEEEService.findByIsbn(“query");

Query by ISSN

String response = IEEEService.findByIssn(“query");

Query by Issue Number

String response = IEEEService.findByIssueNumber(“query");

Query by Meta Data

Queries text in configured metadata fields and abstracts.

String response = IEEEService.findByMetaDataText(“query");

Query for Open Access Article

ApiRequest request = new ApiRequest();
request.setUsingOpenAccess(true);
request.setArticleNumber(“article number");
String response = IEEEService.callApi(request);

Query by Publication Facet

String response = IEEEService.findByPublicationFacetText(“query");

Query by Publisher Facet

String response = IEEEService.findByPublisherFacetText(“query");

Query by Publication Title

String response = IEEEService.findByPublicationTitle(“query");

Query by Publication Number

String response = IEEEService.findByPublicationNumber(“query");

Query by Publication Year

Note: Depending on publication the format of the year may vary.

String response = IEEEService.findByPublicationYear(“year");

Query by Meta Data, Abstract, or Document Text

String response = IEEEService.findByMetaDataText(“query");

Query by Thesaurus Terms

Note: Thesaurus Terms are also called IEEE Terms.

String response = IEEEService.findByThesaurusTerms(“query");

Query Involving a Wildcard

Note: include no more than two wildcard words. Each wildcard word must have a minimum of three characters preceding the wildcard (*).

String response = IEEEService.findByWildcard(“query*");

Query Involving Multiple Data Fields

ApiRequest request = new ApiRequest();
request.setAffiliationText(“query");
// add more search parameters
String response = IEEEService.callApi(request);

Query Involving Filtering and Sorting of Results

Note: Multiple filters can be added as long as a different data field is specified as its first parameter.

ApiRequest request = new ApiRequest();
Map<String, String> filterMap = new HashMap<>();
// add filtering criteria to filterMap
request.setResultsFilter(filterMap);
String response = IEEEService.callApi(request);

Query with XML Object as Data Output

ApiRequest request = new ApiRequest();
request.setDataType(“xml");
// add search parameters
String response = IEEEService.callApi(request);

Query with JSON Object as Data Output

Note: Data type defaults to JSON.

String response = IEEEService.findByAbstractText(“query");

Query with Citations

String response = IEEEService.citations(“articleNumber", “citationType");

Query with Debug Enabled

Note: The query URL that would be sent to the API is output; no call is made to the API.

ApiRequest request = new ApiRequest();
request.setDebugModeOff(false);
String response = IEEEService.callApi(request);

Error Messages

Message Text Trigger
No search criteria provided No query methods were used.
Wildcard word {word} has fewer than 3 valid characters (only for search). Wildcard words (word*) must have at least three characters preceding *. Wildcard character (*) used in words with too few characters.
Query contains more than 2 wildcard words (only for search). Wildcard character (*) used too often in a query.
Service Not Found API error; returns HTTP Status Code 500.
Internal Server Error API error; returns HTTP Status Code 596 or HTTP Status Code 500.
Bad Request If the Auth token is not specified when expected (for chargeable full text). Bad request of 400 is thrown with an error message "Token Expired".