Java Software Development Kit
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(); HttpResponseresponse = 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". |