PHP Software Development Kit

Download the SDK

Requirements

  • PHP 7.x / 8.x
  • cURL PHP Extension
  • JSON PHP Extension (if JSON output is desired)
  • SimpleXML PHP Extension (if XML output is desired)
  • IEEE Xplore API Access Key

Methods Overview

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

Query Methods

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

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

Can be used with other query methods, except for articleNumber().
authorBio() One parameter: author ID number Queries cites and bio for that author ID.
authorFacetText() One parameter: author facet text Queries text in Open Author Facet data field.
authorText() One parameter: author text Queries text in author data field.
authToken() One parameter: auth token Used for chargeable full text of articles; needs to be called prior to fullTextRequest(). Contact your IEEE representative for further details and to get started with chargeable full text article requests.
booleanText() One parameter: boolean query Creates a boolean query against all configured metadata fields, abstract, and document text. Do not include parentheses.
citations() Two parameters are passed.

The first parameter is the article number.

The second parameter is the citation type. Accepted values are:

"ieee"
"non-ieee"
"patent"

The second parameter defaults to "ieee" if omitted.
Used for citations queries and the data returned is only for the type requested.
contentTypeFacetText() One parameter: content type facet text Queries text in Open Content Type Facet data field.
doi() 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 articleNumber(), which overrides the digital object identifier.
facetText() One parameter: facet text Queries text in Open/Facet data field.
fullTextRequest() One parameter: article number Used to issue a chargeable full text article request. Must be preceded by a call to authToken(). Contact your IEEE representative for further details and to get started with chargeable full text article requests.
indexTerms() 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 (*).
insertionStartDate() One parameter: Insertion date in YYYYMMDD format Queries based on insert date and includes results inserted on this date or later. Must be paired with an insertionEndDate().
insertionEndDate() One parameter: Insertion date in YYYYMMDD format Queries based on insert date and includes results inserted on this date or before. Must be paired with an insertionStartDate().
isbn() One parameter: isbn number Queries based on International Standard Book Number.
issn() One parameter: issn number Queries based on International Standard Serial Number.
issueNumber() One parameter: issue number Queries based on Journal Issue Number.
metaDataText() 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 (*).
openAccess() One parameter: article number Queries article based on its article number and returns the full text for that article, if the article is Open Access. When this method is used the only output returned is the article.
publicationFacetText() One parameter: publication facet text Queries text in Open Publication Facet data field.
publisherFacetText() One parameter: publisher facet text Queries text in Open Publisher’s Facet data field.
publicationTitle() One parameter: publication title text Queries text in the title of a publication (Journal, Conferences, or Standard).
publicationYear() One parameter: publication year Queries against the publication year data field.

Note: the format of this data varies by publication.
queryText() One parameter: text to query Queries against all configured metadata fields, abstract, and document text.

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

The first parameter is the name of the data field being queried or the type of query; accepted values are:

"abstract"
"affiliation"
"article_number"
"article_title"
"author"
"boolean_text"
"d-au"
"d-pubtype"
"d-publisher"
"d-year"
"doi"
"end_date" (for insertion end date)
"facet"
"index_terms"
"isbn"
"issn"
"is_number"
"meta_data"
"publication_title"
"publication_year"
"querytext"
"start_date" (for insertion start date)
"thesaurus_terms"


The second parameter is the value to query in that data field.
Serves as a general-purpose query builder, as it is not tied to a particular data field.

Also used for Boolean queries against all configured metadata fields, abstract, and document text, if ‘boolean_text’ is passed for the first parameter and the Boolean query is passed as the second parameter (omit parentheses in value).
thesaurusTerms() 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 (*).

Filter and Sort Methods

Method Parameter(s) Usage
startingResult() One parameter: result position (a number) Sets the starting position in the set of results (for example, starting at the third result).
maximumResults() One parameter: maximum number of results to return Sets the maximum size of the result set returned.

Defaults to 25 and has a max of 200.
resultsFilter() Two parameters are passed.

The first parameter is the filter type; accepted values are:

"content_type"
"end_date" (for insertion end date)
"end_year"
"open_access"
"publication_number"
"publisher"
"start_date" (for insertion start date)
"start_year"

The second parameter is the value used for the filtering.
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.
resultsSorting() One or two parameters are passed.

The first parameter is the data field being used for sorting; accepted values are:

"author"
"article_number"
"article_title"
"end_date" (for insertion end date)
"publication_title"
"publication_year"
"start_date" (for insertion start date)

The second parameter is optional and sets the sort order (if omitted the value is "asc"). Values accepted are:

"asc"
"desc"
Sets the field used for sorting and the direction of the sorting.

Results Methods

Method Parameter(s) Usage
dataType() One parameter is passed for the data type; the accepted values are:

"json"
"xml"
Sets the data type for the results; defaults to JSON.
dataFormat() One parameter is passed for the data structure; the accepted values are:

"raw"
"object"
"array"
Sets the data structure for the result.

"raw" is the unmodified data string from the API.

"object" returns a PHP object (JSON object or SimpleXML object, depending on the data type specified).

"array" returns an associative array.

Running the Query and Getting Results

Method Parameter(s) Usage
callAPI() There is an optional debugging parameter – pass false to this method to enter that mode This is called after one or more Query Methods are specified.

If debugging mode is enabled (by passing false), then the complete query that would be sent to the API is returned.

Otherwise the data or an error message is returned.

Defaults

  • Data type defaults to JSON.
  • Data format defaults to array.
  • 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.

Query by Abstract Text

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->abstractText('query');
$results = $query->callAPI();
?>

Query by Affiliation

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->affiliationText('query');
$results = $query->callAPI();
?>

Query by Article Number

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->articleNumber('article_number');
$results = $query->callAPI();
?>

Query by Article Title

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->articleTitle('query');
$results = $query->callAPI();
?>

Query Author Bio

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->dataType('data_type');
$query->authorBio('author_id');
$results = $query->callAPI();
?>

Query by Author Facet

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->authorFacetText('query');
$results = $query->callAPI();
?>

Query by Author Name

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->authorText('query');
$results = $query->callAPI();
?>

Boolean Query

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

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->booleanText('boolean_query_without_parentheses');
$results = $query->callAPI();
?>

Citations Query

Returns citations of a given type (ieee, non-ieee, patent) for the indicated article number.

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->citations('article_number', 'citation_type');
$results = $query->callAPI();
?>

Query by Open Content Type Facet

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->contentTypeFacetText('query');
$results = $query->callAPI();
?>

Query for Chargeable Full Text Article

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->authToken('auth_token');
$query->dataType('json');
$query->dataFormat('raw');
$query->fullTextRequest('article_number');
$results = $query->callAPI();
?>

Query by DOI (Digital Object Identifier)

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->doi(‘doi’);
$results = $query->callAPI();
?>

Query by Open/Facet Value

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->facetText(‘query’);
$results = $query->callAPI();
?>

Query by Index Terms

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

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->indexTerms(‘terms’);
$results = $query->callAPI();
?>

Query by Insertion Start and End Dates

Narrows result set based on insert date being on or between the specified start and end dates.

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->indexTerms(‘terms’);
$query->insertionStartDate(‘date in YYYYMMDD format’);
$query->insertionEndDate(‘date in YYYYMMDD format’);
$results = $query->callAPI();
?>

Query by ISBN

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->isbn(‘isbn’);
$results = $query->callAPI();
?>

Query by ISSN

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->issn(‘issn’);
$results = $query->callAPI();
?>

Query by Issue Number

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->issueNumber(‘issue_number’);
$results = $query->callAPI();
?>

Query by Meta Data

Queries text in configured metadata fields and abstracts.

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->metaDataText(‘query’);
$results = $query->callAPI();
?>

Query for Open Access Article

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->openAccess(‘article number’);
$results = $query->callAPI();
?>

Query by Publication Facet

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->publicationFacetText(‘query’);
$results = $query->callAPI();
?>

Query by Publisher Facet

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->publisherFacetText(‘query’);
$results = $query->callAPI();
?>

Query by Publication Title

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->publicationTitle(‘query’);
$results = $query->callAPI();
?>

Query by Publication Year

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

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->publicationYear(‘year’);
$results = $query->callAPI();
?>

Query by Meta Data, Abstract, or Document Text

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->queryText(‘query’);
$results = $query->callAPI();
?>

Query by Thesaurus Terms

Note: Thesaurus Terms are also called IEEE Terms.

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->thesaurusTerms(‘terms’);
$results = $query->callAPI();
?>

Query by Specific Data Field

This is a general-purpose method that accepts two parameters - the first is the field(s) to search, the second is the query.

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->searchField(‘datafield’, ‘query’);
$results = $query->callAPI();
?>

Query Involving Multiple Data Fields

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->queryText(‘query’);
$query->publicationYear(‘year’);
$results = $query->callAPI();
?>

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 (*).

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->queryText(‘query*’);
$results = $query->callAPI();
?>

Query Involving Multiple Data Fields

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->queryText(‘query’);
$query->publicationYear(‘year’);
$results = $query->callAPI();
?>

Query Involving Filtering and Sorting of Results

Note: resultsFilter() can be called more than once, as long as a different data field is specified as its first parameter.

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->queryText(‘query’);
$query->startingResult(‘result_number’);
$query->maximumResults(‘result_maximum_number’);
$query->resultsFilter(‘data_field_name’,’filter_by_text’);
$query->resultsSorting(‘data_field_name’,’sort_asc_or_desc’);
$results = $query->callAPI();
?>

Query with XML String as Data Output

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->queryText(‘query’);
$query->dataType(‘xml’);
$query->dataFormat(‘raw’);
$results = $query->callAPI();
?>

Query with SimpleXML Object as Data Output

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->queryText(‘query’);
$query->dataType(‘xml’);
$query->dataFormat(‘object’);
$results = $query->callAPI();
?>

Query with Array of XML Values as Data Output

Note: Data format defaults to array.

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->queryText(‘query’);
$query->dataType(‘xml’);
$query->dataFormat(‘array’);
$results = $query->callAPI();
?>

Query with JSON String as Data Output

Note: Data type defaults to JSON.

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->queryText(‘query’);
$query->dataType(‘json’);
$query->dataFormat(‘raw’);
$results = $query->callAPI();
?>

Query with JSON Object as Data Output

Note: Data type defaults to JSON.

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->queryText(‘query’);
$query->dataType(‘json’);
$query->dataFormat(‘object’);
$results = $query->callAPI();
?>

Query with Array of JSON Values as Data Output

Note: Data format defaults to array.

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->queryText(‘query’);
$query->dataType(‘json’);
$query->dataFormat(‘array’);
$results = $query->callAPI();
?>

Query with Debugging Enabled

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

<?php
require_once ‘/path/to/xplore-php-sdk.php’;
$query = new XPLORE('api_access_key');
$query->queryText(‘query’);
$results = $query->callAPI(false);
?>

Error Messages

Message Text Trigger
"Searches against field <fieldname> are not supported" Passing an invalid field name as the first parameter to the searchField() method.
No search criteria provided No query methods were used.
URL generated is invalid URL does not follow the proper format for submission to the API; use callAPI(false) to retrieve the URL.
SimpleXML extension is not loaded dataType("xml") used and SimpleXML is not loaded on server.
JSON extension is not loaded JSON extension is not loaded on server and that data type is used for the output.
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.
Authorization token not provided Chargeable full text article request made without having a valid authToken() call first.
Full text token cannot be retrieved The authorization code provided to authToken() does not produce a valid token to retrieve chargeable full text articles.